🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.
TypeScript analyticsautogenevaluationlangchainlarge-language-modelsllama-indexllmllm-evaluationllm-observabilityllmopsmonitoringobservabilityopen-sourceopenaiplaygroundprompt-engineeringprompt-managementself-hostedycombinator
feat(ai-gateway): set trace environment from langfuse-environment header (#17956)
Hassieb Pakzad3dc3820d9cfb
diff --git a/ai-gateway/README.md b/ai-gateway/README.mdindex 8091da4ac9..140c418b17 100644--- a/ai-gateway/README.md+++ b/ai-gateway/README.md@@ -434,6 +434,7 @@ The following optional headers enrich the generation, including in usage mode:| `langfuse-trace-name` | String | `langfuse_trace_name` || `langfuse-session-id` | String | `langfuse_session_id` || `langfuse-user-id` | String | `langfuse_user_id` |+| `langfuse-environment` | Environment name | `langfuse_environment` || `langfuse-tags` | Comma-separated strings | `langfuse_tags` || `langfuse-metadata` | Comma-separated `key:value` entries | `langfuse_metadata_<key>` |@@ -443,6 +444,7 @@ For example:langfuse-trace-name: support-workflowlangfuse-session-id: conversation-123langfuse-user-id: user-456+langfuse-environment: productionlangfuse-tags: support,productionlangfuse-metadata: team:search,variant:B,note:hello%2C%20world```@@ -455,8 +457,13 @@ metadata merges by key with explicit entries winning. Invalid entries are ignoreindependently, and invalid overrides leave valid baggage intact. Caller metadatacannot replace protected gateway facts or trusted API-key attribution.-Extraction is bounded to 8 KiB across the eight context header values above-(`traceparent`, `tracestate`, `baggage` and the five custom headers). Above that+The environment follows the SDK rule: at most 40 lowercase letters, digits, `-`+or `_`, not starting with the reserved `langfuse` prefix. An invalid value is+ignored like any other invalid field, so the generation lands in the `default`+environment unless valid baggage supplies one.++Extraction is bounded to 8 KiB across the nine context header values above+(`traceparent`, `tracestate`, `baggage` and the six custom headers). Above thatlimit, context is ignored and a fresh generation trace is created. Decoded fieldsare limited to 1 KiB; each baggage/tag/metadata list is limited to 64 entries.Repeated list header lines are combined in order within that same entry limit.diff --git a/ai-gateway/src/observability/http/tests.rs b/ai-gateway/src/observability/http/tests.rsindex d6457757f4..fb8e534a1d 100644--- a/ai-gateway/src/observability/http/tests.rs+++ b/ai-gateway/src/observability/http/tests.rs@@ -438,6 +438,7 @@ fn generation_request() -> HttpRequest<Body> {.header("langfuse-trace-name", "caller trace").header("langfuse-user-id", "caller-user").header("langfuse-session-id", "caller-session")+ .header("langfuse-environment", "production").header("langfuse-tags", "one,two").header("langfuse-metadata", "team:search").body(Body::from(GENERATION_REQUEST))@@ -468,6 +469,7 @@ fn assert_outbound_context(headers: &HeaderMap, span: Option<&opentelemetry_sdk:"langfuse-trace-name","langfuse-user-id","langfuse-session-id",+ "langfuse-environment","langfuse-tags","langfuse-metadata",] {@@ -499,6 +501,7 @@ fn assert_generation_context(payload: &Value) {("langfuse.trace.name", "caller trace"),("user.id", "caller-user"),("session.id", "caller-session"),+ ("langfuse.environment", "production"),("langfuse.trace.tags", r#"["one","two"]"#),] {assert_eq!(attributes[key], expected);diff --git a/ai-gateway/src/providers/tests.rs b/ai-gateway/src/providers/tests.rsindex 1de6fcfa94..13ba944669 100644--- a/ai-gateway/src/providers/tests.rs+++ b/ai-gateway/src/providers/tests.rs@@ -20,6 +20,22 @@ fn provider(server: &FakeServer, active: usize) -> ProviderTransport {)}+/// Consumed as generation context; never forwarded upstream.+const CALLER_CONTEXT_HEADERS: [(&str, &str); 9] = [+ (+ "traceparent",+ "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",+ ),+ ("tracestate", "caller=private"),+ ("baggage", "langfuse_user_id=private"),+ ("langfuse-trace-name", "private-trace"),+ ("langfuse-session-id", "private-session"),+ ("langfuse-user-id", "private-user"),+ ("langfuse-environment", "private-environment"),+ ("langfuse-tags", "private-tag"),+ ("langfuse-metadata", "private:value"),+];+#[tokio::test]async fn preserves_opaque_bytes_and_isolates_request_and_response_headers() {const REQUEST: &[u8] = b"{ \"model\": \"opaque\", \"future_field\": [true, 3] }\n";@@ -40,15 +56,10 @@ async fn preserves_opaque_bytes_and_isolates_request_and_response_headers() {"openai-project","x-api-key","x-forwarded-host",- "traceparent",- "tracestate",- "baggage",- "langfuse-trace-name",- "langfuse-session-id",- "langfuse-user-id",- "langfuse-tags",- "langfuse-metadata",- ] {+ ]+ .into_iter()+ .chain(CALLER_CONTEXT_HEADERS.map(|(name, _)| name))+ {assert!(!request.headers().contains_key(name), "forwarded {name}");}assert_eq!(to_bytes(request.into_body(), 1024).await.unwrap(), REQUEST);@@ -74,21 +85,13 @@ async fn preserves_opaque_bytes_and_isolates_request_and_response_headers() {("openai-project", "wrong-project"),("x-api-key", "wrong-key"),("x-forwarded-host", "attacker.example"),- (- "traceparent",- "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01",- ),- ("tracestate", "caller=private"),- ("baggage", "langfuse_user_id=private"),- ("langfuse-trace-name", "private-trace"),- ("langfuse-session-id", "private-session"),- ("langfuse-user-id", "private-user"),- ("langfuse-tags", "private-tag"),- ("langfuse-metadata", "private:value"),("content-type", "application/json"),("accept-encoding", "gzip"),("connection", "accept-encoding"),- ] {+ ]+ .into_iter()+ .chain(CALLER_CONTEXT_HEADERS)+ {headers.insert(axum::http::HeaderName::from_static(name),HeaderValue::from_static(value),diff --git a/ai-gateway/src/telemetry/context.rs b/ai-gateway/src/telemetry/context.rsindex 9f471abea1..bcf2fc195a 100644--- a/ai-gateway/src/telemetry/context.rs+++ b/ai-gateway/src/telemetry/context.rs@@ -64,17 +64,18 @@ const CODEX_FLAT_FIELDS: [(&str, &str); 8] = [("x-codex-window-id", "window_id"),("x-codex-parent-thread-id", "parent_thread_id"),];-const HEADERS: [&str; 8] = [+const HEADERS: [&str; 9] = ["traceparent","tracestate","baggage","langfuse-user-id","langfuse-session-id","langfuse-trace-name",+ "langfuse-environment","langfuse-tags","langfuse-metadata",];-const SCALARS: [(&str, &str, &str); 3] = [+const SCALARS: [(&str, &str, &str); 4] = [("langfuse-user-id", "langfuse_user_id", "user.id"),("langfuse-session-id", "langfuse_session_id", "session.id"),(@@ -82,7 +83,15 @@ const SCALARS: [(&str, &str, &str); 3] = ["langfuse_trace_name","langfuse.trace.name",),+ (+ "langfuse-environment",+ "langfuse_environment",+ ENVIRONMENT_ATTRIBUTE,+ ),];+const ENVIRONMENT_ATTRIBUTE: &str = "langfuse.environment";+/// Matches the SDKs' environment rule; ingestion stores `default` when none is set.+const MAX_ENVIRONMENT_BYTES: usize = 40;const AGENT_HEADERS: [&str; 13] = ["user-agent","x-claude-code-session-id",@@ -161,7 +170,10 @@ impl GenerationContext {}result.apply_baggage(headers);for (header, _, attribute) in SCALARS {- if let Some(value) = single_header(headers, header).and_then(|v| decode(v, false)) {+ if let Some(value) = single_header(headers, header)+ .and_then(|v| decode(v, false))+ .filter(|v| valid_scalar(attribute, v))+ {result.attributes.insert(attribute.into(), value.into());}}@@ -197,7 +209,9 @@ impl GenerationContext {continue;};if let Some((_, _, attribute)) = SCALARS.iter().find(|(_, name, _)| *name == key) {- self.attributes.insert((*attribute).into(), value.into());+ if valid_scalar(attribute, &value) {+ self.attributes.insert((*attribute).into(), value.into());+ }} else if key == "langfuse_tags" {if let Some(tags) = parse_tags(&value) {self.apply_tags(tags);@@ -513,6 +527,21 @@ fn valid(value: &str) -> bool {&& !value.chars().any(char::is_control)}+fn valid_scalar(attribute: &str, value: &str) -> bool {+ attribute != ENVIRONMENT_ATTRIBUTE || valid_environment(value)+}++/// Lowercase alphanumerics, `-` and `_`, at most 40 bytes; the `langfuse`+/// prefix is reserved for Langfuse-internal traces.+fn valid_environment(value: &str) -> bool {+ !value.is_empty()+ && value.len() <= MAX_ENVIRONMENT_BYTES+ && !value.starts_with("langfuse")+ && value+ .bytes()+ .all(|byte| byte.is_ascii_lowercase() || byte.is_ascii_digit() || b"-_".contains(&byte))+}+fn decode(value: &str, plus_as_space: bool) -> Option<String> {let mut decoded = Vec::with_capacity(value.len().min(MAX_FIELD_BYTES));let mut bytes = value.bytes();diff --git a/ai-gateway/src/telemetry/context/tests.rs b/ai-gateway/src/telemetry/context/tests.rsindex 10887c76c1..78131bc1b1 100644--- a/ai-gateway/src/telemetry/context/tests.rs+++ b/ai-gateway/src/telemetry/context/tests.rs@@ -159,6 +159,69 @@ fn malformed_fields_and_duplicate_custom_headers_keep_valid_baggage() {);}+#[test]+fn environment_follows_langfuse_naming_rules_and_keeps_valid_baggage() {+ let environment = |header: Option<&str>, baggage: Option<&str>| {+ let mut headers = HeaderMap::new();+ if let Some(header) = header {+ headers.insert("langfuse-environment", header.parse().unwrap());+ }+ if let Some(baggage) = baggage {+ headers.insert(+ "baggage",+ format!("langfuse_environment={baggage}").parse().unwrap(),+ );+ }+ GenerationContext::from_headers(&headers)+ .attributes+ .get("langfuse.environment")+ .cloned()+ };+ assert_eq!(+ environment(Some("production"), None),+ Some(json!("production"))+ );+ assert_eq!(+ environment(Some("staging_eu-1"), Some("baggage")),+ Some(json!("staging_eu-1"))+ );+ assert_eq!(+ environment(None, Some("from-baggage")),+ Some(json!("from-baggage"))+ );+ assert_eq!(+ environment(Some(&"a".repeat(40)), None),+ Some(json!("a".repeat(40)))+ );+ for invalid in [+ "Production",+ "prod env",+ "prod%2Fenv",+ "prod.eu",+ "langfuse",+ "langfuse-prod",+ "langfuseprod",+ &"a".repeat(41),+ "%20",+ ] {+ assert_eq!(environment(Some(invalid), None), None, "{invalid}");+ assert_eq!(environment(None, Some(invalid)), None, "{invalid}");+ assert_eq!(+ environment(Some(invalid), Some("fallback")),+ Some(json!("fallback")),+ "{invalid}"+ );+ }+ let mut headers = HeaderMap::new();+ headers.append("langfuse-environment", "first".parse().unwrap());+ headers.append("langfuse-environment", "second".parse().unwrap());+ assert!(+ !GenerationContext::from_headers(&headers)+ .attributes+ .contains_key("langfuse.environment")+ );+}+#[test]fn coding_agent_headers_group_sessions_and_turns() {let cases = [