Skip to content

🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

feat(ai-gateway): set trace environment from langfuse-environment header (#17956)

Hassieb Pakzad3dc3820d9cfb
diff --git a/ai-gateway/README.md b/ai-gateway/README.md
index 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-workflow
langfuse-session-id: conversation-123
langfuse-user-id: user-456
+langfuse-environment: production
langfuse-tags: support,production
langfuse-metadata: team:search,variant:B,note:hello%2C%20world
```
@@ -455,8 +457,13 @@ metadata merges by key with explicit entries winning. Invalid entries are ignore
independently, and invalid overrides leave valid baggage intact. Caller metadata
cannot 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 that
limit, context is ignored and a fresh generation trace is created. Decoded fields
are 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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 = [