Skip to content

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

fix(ai-gateway): always attribute user-bound key generations to the key's user (#19431)

Hassieb Pakzad074731ce5c32
diff --git a/ai-gateway/README.md b/ai-gateway/README.md
index 87928811a2..6dca7a37d3 100644
--- a/ai-gateway/README.md
+++ b/ai-gateway/README.md
@@ -500,7 +500,7 @@ The gateway sets these generation fields directly:
| Generation field | OTLP attribute | Value |
| ------------------------------------------------------------- | ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Model (`provided_model_name`) | `langfuse.observation.model.name` | The first known of `model.response`, `model.upstream` and `model.requested` below |
-| User ID | `user.id` | The caller's `langfuse-user-id` header or `langfuse_user_id` baggage. Otherwise, only when the gateway starts the trace (no valid `traceparent`), the gateway key owner's user ID. The source is in `user_id_source` |
+| User ID | `user.id` | For a gateway key bound to a user, always that user's ID; the caller's user ID is ignored, also with a `traceparent`. Otherwise the caller's `langfuse-user-id` header or `langfuse_user_id` baggage. The source is in `user_id_source` |
| Session ID, trace name, environment, tags | `session.id`, `langfuse.trace.name`, `langfuse.environment`, `langfuse.trace.tags` | Caller headers, baggage or a recognized coding agent; see [Caller tracing context](#caller-tracing-context) |
| Level, status message | `langfuse.observation.level`, `langfuse.observation.status_message` | Derived from the HTTP status, provider status and relay outcome |
| Model parameters, usage, input, output, completion start time | `langfuse.observation.*` | See [Response capture](#response-capture) |
@@ -622,7 +622,8 @@ values remain strings. A literal `+` stays `+` in custom headers. Tags are trimm
and deduplicated. Valid explicit headers override baggage for the same field;
metadata merges by key with explicit entries winning. Invalid entries are ignored
independently, and invalid overrides leave valid baggage intact. Caller metadata
-cannot replace protected gateway facts or trusted API-key attribution.
+cannot replace protected gateway facts or trusted API-key attribution. A gateway
+key bound to a user ignores the caller's `langfuse-user-id` and `langfuse_user_id`.
The environment follows the SDK rule: at most 40 lowercase letters, digits, `-`
or `_`, not starting with the reserved `langfuse` prefix. An invalid value is
diff --git a/ai-gateway/src/telemetry/mapping.rs b/ai-gateway/src/telemetry/mapping.rs
index a59f5a62df..f87702c7a2 100644
--- a/ai-gateway/src/telemetry/mapping.rs
+++ b/ai-gateway/src/telemetry/mapping.rs
@@ -38,6 +38,7 @@ pub(super) fn span(facts: InferenceFacts, context: &GenerationContext) -> Value
}));
if let Some((source, user_id)) = user_id_source(&facts, context) {
if let Some(user_id) = user_id {
+ attributes.retain(|attribute| attribute["key"] != USER_ID_ATTRIBUTE);
attributes.push(attribute(USER_ID_ATTRIBUTE, user_id));
}
metadata.insert("langfuse.gateway.user_id_source".into(), json!(source));
@@ -112,23 +113,23 @@ pub(super) fn span(facts: InferenceFacts, context: &GenerationContext) -> Value
span
}
-/// The caller's user ID wins. A caller's trace may already name its user, so
-/// only a trace the gateway starts defaults to the key owner.
+/// A key bound to a user always attributes to that user, even inside a caller's
+/// trace. Only keys without a bound user accept the caller's user ID.
fn user_id_source<'a>(
facts: &'a InferenceFacts,
context: &GenerationContext,
) -> Option<(&'static str, Option<&'a str>)> {
- if context.attributes.contains_key(USER_ID_ATTRIBUTE) {
- return Some(("client", None));
- }
- if context.parent_span_id.is_some() {
- return None;
- }
- let owner = facts
+ if let Some(owner) = facts
.metadata
.get("key_owner_user_id")
- .and_then(Value::as_str)?;
- Some(("api_key_owner", Some(owner)))
+ .and_then(Value::as_str)
+ {
+ return Some(("api_key_owner", Some(owner)));
+ }
+ context
+ .attributes
+ .contains_key(USER_ID_ATTRIBUTE)
+ .then_some(("client", None))
}
pub(super) fn omit_input(span: &mut Value, reason: InputOmissionReason) -> bool {
@@ -710,40 +711,43 @@ mod tests {
}
#[test]
- fn user_id_defaults_to_the_key_owner_only_on_gateway_rooted_traces() {
- let mut owned = facts();
- owned.metadata["key_owner_user_id"] = json!("owner");
-
- let attrs = attributes(&span(owned, &context()));
- assert_eq!(attrs["user.id"], "owner");
- assert_eq!(
- metadata(&attrs)["langfuse.gateway.user_id_source"],
- "api_key_owner"
- );
+ fn user_bound_keys_always_attribute_to_the_key_owner() {
+ let mut caller_in_child = context();
+ caller_in_child.parent_span_id = Some("fedcba9876543210".into());
+ caller_in_child
+ .attributes
+ .insert("user.id".into(), json!("caller"));
+ for context in [context(), caller_in_child] {
+ let mut owned = facts();
+ owned.metadata["key_owner_user_id"] = json!("owner");
+ let span = span(owned, &context);
+ let user_ids: Vec<_> = span["attributes"]
+ .as_array()
+ .unwrap()
+ .iter()
+ .filter(|attribute| attribute["key"] == "user.id")
+ .map(|attribute| attribute["value"]["stringValue"].clone())
+ .collect();
+ assert_eq!(user_ids, [json!("owner")]);
+ assert_eq!(
+ metadata(&attributes(&span))["langfuse.gateway.user_id_source"],
+ "api_key_owner"
+ );
+ }
+ }
+ #[test]
+ fn keys_without_a_bound_user_take_the_callers_user_id() {
let mut caller = context();
+ caller.parent_span_id = Some("fedcba9876543210".into());
caller.attributes.insert("user.id".into(), json!("caller"));
- let mut owned = facts();
- owned.metadata["key_owner_user_id"] = json!("owner");
- let attrs = attributes(&span(owned, &caller));
+ let attrs = attributes(&span(facts(), &caller));
assert_eq!(attrs["user.id"], "caller");
assert_eq!(
metadata(&attrs)["langfuse.gateway.user_id_source"],
"client"
);
- let mut child = context();
- child.parent_span_id = Some("fedcba9876543210".into());
- let mut owned = facts();
- owned.metadata["key_owner_user_id"] = json!("owner");
- let attrs = attributes(&span(owned, &child));
- assert!(!attrs.contains_key("user.id"));
- assert!(
- metadata(&attrs)
- .get("langfuse.gateway.user_id_source")
- .is_none()
- );
-
let attrs = attributes(&span(facts(), &context()));
assert!(!attrs.contains_key("user.id"));
assert!(