:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
use serde_json::Value;
/// Configuration for a single supported AI provider. Adding a new provider
/// means adding one entry here — both the namespace prefix (for broad span
/// acceptance) and the classifier (for specific event type mapping) live
/// together, so they can't get out of sync.
pub struct SupportedProvider {
/// Accept any span whose attribute key starts with one of these prefixes.
prefixes: &'static [&'static str],
/// Maps a span's attributes to a PostHog event type.
pub classify: fn(&serde_json::Map<String, Value>) -> &'static str,
}
/// Looks up `key` in `attrs` as a string value and passes it to `classify`.
/// Falls back to `$ai_span` if the key is missing or the value isn't a string.
fn classify_by_key(
attrs: &serde_json::Map<String, Value>,
key: &str,
classify: fn(&str) -> &'static str,
) -> &'static str {
attrs
.get(key)
.and_then(|v| v.as_str())
.map(classify)
.unwrap_or("$ai_span")
}
/// Maps the standard OTel GenAI `gen_ai.operation.name` value to a PostHog event
/// type. Shared so the Vercel provider can reuse it for AI SDK 7 spans.
fn classify_gen_ai_operation(op: &str) -> &'static str {
match op {
"chat" => "$ai_generation",
"embeddings" => "$ai_embedding",
_ => "$ai_span",
}
}
/// OpenAI-style semantic conventions (`gen_ai.*`).
const GEN_AI: SupportedProvider = SupportedProvider {
prefixes: &["gen_ai."],
classify: |attrs| classify_by_key(attrs, "gen_ai.operation.name", classify_gen_ai_operation),
};
/// Vercel AI SDK (`ai.*`) and Eve (`eve.*`). Eve root turn spans can omit
/// `ai.*` attributes, so its namespace must be accepted by the same provider.
const VERCEL_AI: SupportedProvider = SupportedProvider {
prefixes: &["ai.", "eve."],
classify: |attrs| match attrs.get("ai.operationId").and_then(|v| v.as_str()) {
Some(op_id) => match op_id {
s if s.ends_with(".doGenerate") || s.ends_with(".doStream") => "$ai_generation",
s if s == "ai.embed.doEmbed" || s == "ai.embedMany.doEmbed" => "$ai_embedding",
_ => "$ai_span",
},
// AI SDK 7's gen_ai-native integration emits standard gen_ai.* semconv
// plus supplemental ai.usage.* details, but no ai.operationId. Those ai.*
// keys make this provider match first, so classify by the standard
// operation name instead of defaulting the span to $ai_span.
None => classify_by_key(attrs, "gen_ai.operation.name", classify_gen_ai_operation),
},
};
/// Traceloop OpenLLMetry SDK (`traceloop.*`). The classifier key
/// (`llm.request.type`) doesn't share the `traceloop.` prefix, so both
/// prefixes are needed to catch all Traceloop spans.
const TRACELOOP: SupportedProvider = SupportedProvider {
prefixes: &["traceloop.", "llm.request.type"],
classify: |attrs| {
classify_by_key(
attrs,
"llm.request.type",
|request_type| match request_type {
"chat" | "completion" => "$ai_generation",
"embedding" | "embeddings" => "$ai_embedding",
_ => "$ai_span",
},
)
},
};
/// Pydantic AI SDK (`pydantic_ai.*`). No specific event types — all spans
/// default to `$ai_span`.
const PYDANTIC_AI: SupportedProvider = SupportedProvider {
prefixes: &["pydantic_ai."],
classify: |_| "$ai_span",
};
/// Providers are matched in order — first prefix match wins. More specific
/// matchers must come before less specific ones to avoid shadowing. For example,
/// Vercel AI spans carry both `ai.*` and `gen_ai.*` attributes; if GEN_AI were
/// checked first it would match on `gen_ai.*` but fail to classify (Vercel AI
/// doesn't set `gen_ai.operation.name`), shadowing the VERCEL_AI classifier.
const SUPPORTED_PROVIDERS: &[SupportedProvider] = &[
// 1. Framework-specific — dedicated SDKs with their own attribute namespaces
VERCEL_AI,
PYDANTIC_AI,
// 2. Spec variations — alternative telemetry standards with distinct classification keys
TRACELOOP,
// 3. Generic catch-all — standard OpenTelemetry semantic conventions (gen_ai.*)
GEN_AI,
];
/// Returns the matching provider for raw protobuf attributes, based on prefix
/// matching. Used as a lightweight pre-filter to avoid converting irrelevant
/// spans into JSON.
pub fn get_provider_raw(
attrs: &[opentelemetry_proto::tonic::common::v1::KeyValue],
) -> Option<&'static SupportedProvider> {
SUPPORTED_PROVIDERS.iter().find(|p| {
attrs
.iter()
.any(|kv| p.prefixes.iter().any(|prefix| kv.key.starts_with(prefix)))
})
}
#[cfg(test)]
mod tests {
use super::*;
fn attrs_with(key: &str, value: &str) -> serde_json::Map<String, Value> {
let mut map = serde_json::Map::new();
map.insert(key.to_string(), Value::String(value.to_string()));
map
}
fn get_event_name(attrs: &serde_json::Map<String, Value>) -> Option<&'static str> {
SUPPORTED_PROVIDERS
.iter()
.find(|p| {
attrs
.keys()
.any(|key| p.prefixes.iter().any(|prefix| key.starts_with(prefix)))
})
.map(|p| (p.classify)(attrs))
}
#[test]
fn test_from_gen_ai_operation_name() {
assert_eq!(
get_event_name(&attrs_with("gen_ai.operation.name", "chat")),
Some("$ai_generation")
);
assert_eq!(
get_event_name(&attrs_with("gen_ai.operation.name", "embeddings")),
Some("$ai_embedding")
);
assert_eq!(
get_event_name(&attrs_with("gen_ai.operation.name", "unknown")),
Some("$ai_span")
);
}
#[test]
fn test_from_vercel_ai_operation_id() {
for (op_id, expected) in [
("ai.generateText.doGenerate", "$ai_generation"),
("ai.streamText.doStream", "$ai_generation"),
("ai.generateObject.doGenerate", "$ai_generation"),
("ai.streamObject.doStream", "$ai_generation"),
("ai.embed.doEmbed", "$ai_embedding"),
("ai.embedMany.doEmbed", "$ai_embedding"),
("ai.toolCall", "$ai_span"),
("ai.generateText", "$ai_span"),
("ai.streamText", "$ai_span"),
] {
assert_eq!(
get_event_name(&attrs_with("ai.operationId", op_id)),
Some(expected),
"ai.operationId={op_id}"
);
}
}
#[test]
fn test_from_traceloop_request_type() {
for (request_type, expected) in [
("chat", "$ai_generation"),
("completion", "$ai_generation"),
("embedding", "$ai_embedding"),
("embeddings", "$ai_embedding"),
("rerank", "$ai_span"),
("unknown", "$ai_span"),
] {
assert_eq!(
get_event_name(&attrs_with("llm.request.type", request_type)),
Some(expected),
"llm.request.type={request_type}"
);
}
}
#[test]
fn test_vercel_ai_takes_precedence_over_gen_ai() {
// Vercel AI spans carry both ai.* and gen_ai.* attributes. The
// SDK-specific VERCEL_AI provider should match first.
let mut attrs = serde_json::Map::new();
attrs.insert(
"gen_ai.operation.name".to_string(),
Value::String("chat".to_string()),
);
attrs.insert(
"ai.operationId".to_string(),
Value::String("ai.toolCall".to_string()),
);
assert_eq!(get_event_name(&attrs), Some("$ai_span"));
}
#[test]
fn test_vercel_ai_do_generate_with_gen_ai_attrs() {
// Real-world scenario: Vercel AI .doGenerate spans carry gen_ai.*
// attributes (e.g. gen_ai.request.model) but not gen_ai.operation.name.
// VERCEL_AI must match first and classify via ai.operationId.
let mut attrs = serde_json::Map::new();
attrs.insert(
"gen_ai.request.model".to_string(),
Value::String("gpt-4".to_string()),
);
attrs.insert(
"ai.operationId".to_string(),
Value::String("ai.generateText.doGenerate".to_string()),
);
assert_eq!(get_event_name(&attrs), Some("$ai_generation"));
}
#[test]
fn test_ai_sdk_7_gen_ai_native_spans_classify_by_operation_name() {
// AI SDK 7's @ai-sdk/otel integration emits standard gen_ai.* semconv
// plus supplemental ai.usage.* details, but no ai.operationId. The
// ai.usage.* keys make VERCEL_AI match first, so it must fall back to
// gen_ai.operation.name. Operations that are not inference stay
// $ai_span, or a tool-call span becomes a second priced generation.
for (operation, expected) in [
("chat", "$ai_generation"),
("embeddings", "$ai_embedding"),
("execute_tool", "$ai_span"),
] {
let mut attrs = serde_json::Map::new();
attrs.insert(
"gen_ai.operation.name".to_string(),
Value::String(operation.to_string()),
);
attrs.insert(
"ai.usage.outputTokenDetails.reasoningTokens".to_string(),
Value::Number(5.into()),
);
assert_eq!(
get_event_name(&attrs),
Some(expected),
"gen_ai.operation.name={operation}"
);
}
}
#[test]
fn test_supported_provider_prefix_defaults_to_ai_span() {
assert_eq!(
get_event_name(&attrs_with("gen_ai.request.model", "gpt-4")),
Some("$ai_span")
);
assert_eq!(
get_event_name(&attrs_with("eve.session.id", "session-123")),
Some("$ai_span")
);
assert_eq!(
get_event_name(&attrs_with("pydantic_ai.agent_name", "my-agent")),
Some("$ai_span")
);
assert_eq!(
get_event_name(&attrs_with("traceloop.workflow.name", "my-workflow")),
Some("$ai_span")
);
}
#[test]
fn test_traceloop_span_with_only_llm_request_type() {
// Traceloop spans may carry only `llm.request.type` without any
// `traceloop.*` prefixed attribute. The dual-prefix design ensures
// these are still accepted and classified correctly.
assert_eq!(
get_event_name(&attrs_with("llm.request.type", "chat")),
Some("$ai_generation")
);
assert_eq!(
get_event_name(&attrs_with("llm.request.type", "embedding")),
Some("$ai_embedding")
);
}
#[test]
fn test_unsupported_provider_returns_none() {
assert_eq!(
get_event_name(&attrs_with("logfire.msg", "running 1 tool")),
None
);
}
#[test]
fn test_irrelevant_span_returns_none() {
assert_eq!(
get_event_name(&attrs_with("http.request.method", "POST")),
None
);
assert_eq!(get_event_name(&serde_json::Map::new()), None);
assert_eq!(
get_event_name(&attrs_with("langchain.chain.name", "my-chain")),
None
);
}
}