Skip to content

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

feat(ai-gateway): record Codex client metadata as agent metadata (#17641)

Hassieb Pakzad330bb86bcc33
diff --git a/ai-gateway/README.md b/ai-gateway/README.md
index 6ea69dd386..da50000756 100644
--- a/ai-gateway/README.md
+++ b/ai-gateway/README.md
@@ -268,7 +268,7 @@ pricing without duplicating it in metadata. Missing usage is not reported as zer
Gateway metadata uses `langfuse.gateway.*`: `project_id`, `organization_id`,
`ingestion_mode`, `api_format`, `api-key.id`, and `provider.connection_id`,
-`provider.request_id`, `provider.response_id`. API-key attribution entries appear
+`provider.request.id`, `provider.response.id`. API-key attribution entries appear
both as top-level metadata and under `langfuse.gateway.api-key.metadata.*`.
Gateway, agent and OpenTelemetry fields win collisions; the namespaced attribution
copy preserves the original value. `http_status` stays top level. Relay outcome,
@@ -358,7 +358,7 @@ The gateway also recognizes correlation headers emitted by coding agents:
| Agent | Session source | Turn source |
| --- | --- | --- |
| Claude Code | `x-claude-code-session-id` | Not available |
-| Codex | `thread_id` in `x-codex-turn-metadata` | `turn_id` in `x-codex-turn-metadata` |
+| Codex | `thread_id` in the Codex turn snapshot | `turn_id` in the Codex turn snapshot |
| OpenCode | `x-opencode-session`, falling back to `x-session-id` or `x-session-affinity` for an OpenCode user agent | `x-opencode-request` |
| Pi | `x-session-id`, `session_id`, `x-session-affinity`, or `x-client-request-id` for a Pi user agent | Not available |
@@ -375,11 +375,33 @@ This includes `agent.name`, `agent.project_id`, `agent.session_id`,
routing-oriented `session_id` is retained as metadata, while its
conversation-oriented `thread_id` supplies the Langfuse session.
-Agent extraction has a separate 8 KiB aggregate header limit. Codex turn metadata is
-limited to 4 KiB, and each extracted identifier uses the same 1 KiB field limit as
-the explicit context headers. Empty, duplicate, malformed, oversized, or
-control-character-bearing values are ignored. Generic affinity/request headers are
-used only after an agent-specific header or user agent identifies the caller.
+Codex sends its turn snapshot canonically in the request body as
+`client_metadata["x-codex-turn-metadata"]`; the `x-codex-turn-metadata` header and the
+flat `client_metadata` keys (`session_id`, `thread_id`, `turn_id`, `root_turn_id`,
+`parent_turn_id`, `x-codex-installation-id`, `x-codex-window-id`,
+`x-codex-parent-thread-id`) are compatibility projections of it. The gateway reads the
+body snapshot first, then the header, and finally the flat keys. A recognized
+`client_metadata` object is removed from the recorded input in full mode because it is
+request metadata rather than prompt content; other clients' `client_metadata` stays in
+the input untouched. Besides the identifiers above, Codex generations carry
+`agent.id` (Codex's `agent_name`, the agent's path in a multi-agent team such as
+`/root`), `agent.installation_id`, `agent.root_turn_id`, `agent.parent_turn_id`,
+`agent.parent_thread_id`, `agent.forked_from_thread_id`,
+`agent.forked_from_ordinal_exclusive`, `agent.window_id`, `agent.window_number`,
+`agent.context_window_id`, `agent.request_kind` (`turn`, `compaction`, `prewarm`,
+`memory`), `agent.compaction.{trigger,reason,implementation,phase,strategy}`,
+`agent.subagent_kind`, `agent.thread_source`, `agent.turn_trigger`, `agent.sandbox`,
+`agent.sandbox_mode`, `agent.workspace_kind`, `agent.auto_review_enabled`, and
+`agent.turn_started_at_unix_ms`. Numbers and booleans keep their native JSON type.
+Nested snapshot objects such as `workspaces` and `tool_namespaces_info` are not
+copied, and unknown snapshot keys are ignored so they cannot override `agent.name`.
+
+Agent extraction has a separate 8 KiB aggregate header limit. The Codex turn metadata
+header is limited to 4 KiB and the body `client_metadata` object to 64 KiB, and each
+extracted identifier uses the same 1 KiB field limit as the explicit context headers.
+Empty, duplicate, malformed, oversized, or control-character-bearing values are
+ignored. Generic affinity/request headers are used only after an agent-specific header
+or user agent identifies the caller.
Caller context is kept outside ambient operational context and operational logs.
Resolver and ingestion HTTP requests propagate only the gateway's internal trace;
@@ -396,9 +418,9 @@ including at debug level. `LANGFUSE_LOG_FORMAT=json` emits one JSON object per l
Web's resolved ingestion mode controls content capture:
- `full`: input retains native `input`, `instructions`, tools, prompt/context
- references and unknown fields. Model and configuration are projected out of input.
- Output is an ordered array of native completed items. Content is sent only through
- Langfuse ingestion.
+ references and unknown fields. Model, configuration and a recognized coding agent's
+ `client_metadata` are projected out of input. Output is an ordered array of native
+ completed items. Content is sent only through Langfuse ingestion.
- `usage`: input and output are null. Model, scalar parameters, native usage,
timing and trusted attribution are retained; request schemas/content are omitted.
diff --git a/ai-gateway/src/capture/mod.rs b/ai-gateway/src/capture/mod.rs
index 5a64baacf7..1d13b51d56 100644
--- a/ai-gateway/src/capture/mod.rs
+++ b/ai-gateway/src/capture/mod.rs
@@ -50,6 +50,12 @@ impl ProtocolCapture {
Self::OpenAiResponses(capture) => ("openai.responses", capture.into_facts()),
}
}
+
+ fn client_metadata(&self) -> Option<&Map<String, Value>> {
+ match self {
+ Self::OpenAiResponses(capture) => capture.client_metadata(),
+ }
+ }
}
/// Owned before dispatch and moved into the response body. Drop also covers a
@@ -144,9 +150,13 @@ impl ExecutionCapture {
context: &ResolvedRequestContext,
headers: &HeaderMap,
) {
+ let client_metadata = self
+ .protocol
+ .as_ref()
+ .and_then(ProtocolCapture::client_metadata);
self.delivery = Some((
telemetry,
- telemetry::DeliveryContext::from_resolved(context, headers),
+ telemetry::DeliveryContext::from_resolved(context, headers, client_metadata),
));
}
diff --git a/ai-gateway/src/capture/openai_responses.rs b/ai-gateway/src/capture/openai_responses.rs
index 6f221f8365..3db27e8ba3 100644
--- a/ai-gateway/src/capture/openai_responses.rs
+++ b/ai-gateway/src/capture/openai_responses.rs
@@ -3,7 +3,7 @@ use super::{
MAX_CAPTURE_BYTES, MAX_FACT_STRING, MAX_ITEMS, bounded_string, facts::ProviderFacts,
identity_encoding, sse::SseDecoder,
};
-use crate::resolution::IngestionMode;
+use crate::{resolution::IngestionMode, telemetry};
use axum::http::{HeaderMap, header};
use serde_json::{Map, Value};
use std::collections::BTreeMap;
@@ -25,6 +25,7 @@ pub(super) struct OpenAiResponsesCapture {
expected_items: Option<usize>,
request_complete: bool,
response_valid: bool,
+ client_metadata: Option<Map<String, Value>>,
}
impl OpenAiResponsesCapture {
@@ -39,6 +40,7 @@ impl OpenAiResponsesCapture {
expected_items: None,
request_complete: false,
response_valid: true,
+ client_metadata: None,
};
if identity_encoding(headers)
&& body.len() <= MAX_CAPTURE_BYTES
@@ -140,6 +142,11 @@ impl OpenAiResponsesCapture {
self.facts
}
+ /// The coding agent's `client_metadata` object removed from the request, if any.
+ pub fn client_metadata(&self) -> Option<&Map<String, Value>> {
+ self.client_metadata.as_ref()
+ }
+
fn capture_request(&mut self, mut request: Map<String, Value>) {
self.facts.requested_model = request
.get("model")
@@ -147,6 +154,8 @@ impl OpenAiResponsesCapture {
.and_then(bounded_string);
self.facts.model.clone_from(&self.facts.requested_model);
request.remove("model");
+ // Agent identifiers are recorded as `agent.*` metadata in both ingestion modes.
+ self.client_metadata = telemetry::take_agent_client_metadata(&mut request);
for key in [
"temperature",
"top_p",
diff --git a/ai-gateway/src/capture/openai_responses/tests.rs b/ai-gateway/src/capture/openai_responses/tests.rs
index ccc63f9ed9..3ec0af0fa9 100644
--- a/ai-gateway/src/capture/openai_responses/tests.rs
+++ b/ai-gateway/src/capture/openai_responses/tests.rs
@@ -217,6 +217,50 @@ async fn request_configuration_is_projected_out_of_input() {
assert_eq!(capture.request_metadata["prompt_cache_key"], "cache-key");
}
+#[tokio::test]
+async fn agent_client_metadata_is_projected_out_of_input_in_both_modes() {
+ let codex = json!({
+ "model": "requested", "input": "hello", "future_field": {"keep": true},
+ "client_metadata": {
+ "thread_id": "thread-1", "turn_id": "turn-1",
+ "x-codex-installation-id": "install-1",
+ "x-codex-turn-metadata": "{\"thread_id\":\"thread-1\",\"turn_id\":\"turn-1\",\"agent_name\":\"/root\"}"
+ }
+ });
+ for mode in [IngestionMode::Full, IngestionMode::Usage] {
+ let capture =
+ OpenAiResponsesCapture::new(&HeaderMap::new(), codex.to_string().as_bytes(), mode);
+ assert_eq!(
+ capture.client_metadata().unwrap()["x-codex-installation-id"],
+ "install-1"
+ );
+ let facts = capture.into_facts();
+ if mode == IngestionMode::Full {
+ assert_eq!(
+ facts.input.unwrap(),
+ json!({"input": "hello", "future_field": {"keep": true}})
+ );
+ } else {
+ assert!(facts.input.is_none());
+ }
+ }
+
+ let unknown = json!({
+ "model": "requested", "input": "hello",
+ "client_metadata": {"team": "search"}
+ });
+ let capture = OpenAiResponsesCapture::new(
+ &HeaderMap::new(),
+ unknown.to_string().as_bytes(),
+ IngestionMode::Full,
+ );
+ assert!(capture.client_metadata().is_none());
+ assert_eq!(
+ capture.into_facts().input.unwrap(),
+ json!({"input": "hello", "client_metadata": {"team": "search"}})
+ );
+}
+
#[tokio::test]
async fn completion_time_requires_sse_generated_content_in_either_ingestion_mode() {
for mode in ["full", "usage"] {
@@ -707,7 +751,7 @@ async fn client_compression_preferences_do_not_disable_capture() {
assert!(metadata.get("output_complete").is_none());
assert!(metadata.get("provider_status").is_none());
assert!(metadata.get("native_usage").is_none());
- assert_eq!(metadata["langfuse.gateway.provider.response_id"], "resp-1");
+ assert_eq!(metadata["langfuse.gateway.provider.response.id"], "resp-1");
assert!(
uploaded_attribute(&upload, "langfuse.observation.usage_details")["input_tokens"]
.is_number()
@@ -719,6 +763,93 @@ async fn client_compression_preferences_do_not_disable_capture() {
}
}
+#[tokio::test]
+async fn codex_body_metadata_reaches_the_generation_without_agent_headers() {
+ let upstream = FakeServer::start(|_| async move {
+ Response::builder()
+ .header("content-type", "application/json")
+ .body(Body::from(
+ json!({"id":"resp-1","status":"completed","model":"actual","output":[],"usage":{"input_tokens":10,"output_tokens":21,"total_tokens":31}}).to_string(),
+ ))
+ .unwrap()
+ })
+ .await;
+ let uploaded = Arc::new(Mutex::new(Value::Null));
+ let received = uploaded.clone();
+ let collector = FakeServer::start(move |request| {
+ let received = received.clone();
+ async move {
+ let bytes = to_bytes(request.into_body(), 64 * 1024).await.unwrap();
+ *received.lock().unwrap() = serde_json::from_slice(&bytes).unwrap();
+ Response::new(Body::from("{}"))
+ }
+ })
+ .await;
+ let telemetry = crate::telemetry::Telemetry::new(
+ &crate::resolution::ControlPlaneConfig::new(&collector.url, "test-service-key").unwrap(),
+ )
+ .unwrap();
+ let context = resolved_request_context_with_mode("provider-secret", "full").await;
+ let provider =
+ OpenAiProvider::for_test(format!("{}/v1", upstream.url), ProviderLimits::default())
+ .with_telemetry(telemetry.clone());
+ let turn_metadata = json!({
+ "installation_id": "install-1", "session_id": "routing-session",
+ "thread_id": "thread-1", "agent_name": "/root", "turn_id": "turn-1",
+ "request_kind": "turn", "root_turn_id": "turn-1", "sandbox_mode": "workspace-write",
+ "tool_namespaces_info": {"functions": {"name": "functions", "functions": {}}}
+ });
+ let body = json!({
+ "model": "requested", "input": "hello",
+ "client_metadata": {
+ "session_id": "routing-session", "thread_id": "thread-1", "turn_id": "turn-1",
+ "x-codex-installation-id": "install-1", "x-codex-window-id": "thread-1:1",
+ "x-codex-turn-metadata": turn_metadata.to_string()
+ }
+ });
+ let forwarded = provider
+ .forward(
+ provider.try_admit().unwrap(),
+ context,
+ &HeaderMap::new(),
+ Bytes::from(body.to_string()),
+ )
+ .await
+ .unwrap();
+ to_bytes(forwarded.into_body(), 4096).await.unwrap();
+ telemetry
+ .shutdown(tokio::time::Instant::now() + Duration::from_secs(2))
+ .await;
+ assert_eq!(collector.calls(), 1);
+ let upload = uploaded.lock().unwrap();
+ let attributes = upload["resourceSpans"][0]["scopeSpans"][0]["spans"][0]["attributes"]
+ .as_array()
+ .unwrap();
+ let attribute = |key: &str| {
+ attributes
+ .iter()
+ .find(|attribute| attribute["key"] == key)
+ .map(|attribute| attribute["value"]["stringValue"].clone())
+ };
+ assert_eq!(attribute("session.id").unwrap(), "codex:thread-1");
+ assert_eq!(attribute("langfuse.trace.name").unwrap(), "codex");
+ assert!(attribute("user.id").is_none());
+ let metadata = uploaded_attribute(&upload, "langfuse.observation.metadata");
+ assert_eq!(metadata["agent.name"], "codex");
+ assert_eq!(metadata["agent.id"], "/root");
+ assert_eq!(metadata["agent.installation_id"], "install-1");
+ assert_eq!(metadata["agent.root_turn_id"], "turn-1");
+ assert_eq!(metadata["agent.window_id"], "thread-1:1");
+ assert_eq!(metadata["agent.request_kind"], "turn");
+ assert_eq!(metadata["agent.sandbox_mode"], "workspace-write");
+ assert!(metadata.get("agent.tool_namespaces_info").is_none());
+ assert_eq!(metadata["langfuse.gateway.provider.response.id"], "resp-1");
+ assert_eq!(
+ uploaded_attribute(&upload, "langfuse.observation.input"),
+ json!({"input": "hello"})
+ );
+}
+
#[tokio::test]
async fn capture_regression_large_request_does_not_invalidate_output() {
let context = resolved_request_context_with_mode("provider-secret", "full").await;
diff --git a/ai-gateway/src/providers/openai/tests.rs b/ai-gateway/src/providers/openai/tests.rs
index 72b0e65fb8..3de94dd761 100644
--- a/ai-gateway/src/providers/openai/tests.rs
+++ b/ai-gateway/src/providers/openai/tests.rs
@@ -685,7 +685,7 @@ fn assert_completed_upload(payload: &serde_json::Value, streaming: bool) {
.unwrap();
assert!(metadata.get("relay_outcome").is_none());
assert!(metadata.get("native_usage").is_none());
- assert_eq!(metadata["langfuse.gateway.provider.response_id"], "resp-1");
+ assert_eq!(metadata["langfuse.gateway.provider.response.id"], "resp-1");
let usage: Value = serde_json::from_str(
attrs
.iter()
diff --git a/ai-gateway/src/telemetry/context.rs b/ai-gateway/src/telemetry/context.rs
index ab5750b94a..9f471abea1 100644
--- a/ai-gateway/src/telemetry/context.rs
+++ b/ai-gateway/src/telemetry/context.rs
@@ -17,6 +17,53 @@ const MAX_FIELD_BYTES: usize = 1024;
const MAX_ENTRIES: usize = 64;
const MAX_AGENT_HEADER_BYTES: usize = 8 * 1024;
const MAX_AGENT_METADATA_BYTES: usize = 4 * 1024;
+/// Codex's body blob additionally carries its tool inventory, so it is bounded separately.
+const MAX_CLIENT_METADATA_BYTES: usize = 64 * 1024;
+const CODEX_TURN_METADATA_KEY: &str = "x-codex-turn-metadata";
+/// Codex turn metadata retained as `agent.*`. Nested objects such as the tool inventory
+/// and workspaces are not copied; the tool inventory already lives in the captured input.
+const CODEX_STRING_FIELDS: [(&str, &str); 18] = [
+ ("session_id", "agent.session_id"),
+ ("thread_id", "agent.thread_id"),
+ ("turn_id", "agent.turn_id"),
+ ("agent_name", "agent.id"),
+ ("installation_id", "agent.installation_id"),
+ ("root_turn_id", "agent.root_turn_id"),
+ ("parent_turn_id", "agent.parent_turn_id"),
+ ("parent_thread_id", "agent.parent_thread_id"),
+ ("forked_from_thread_id", "agent.forked_from_thread_id"),
+ ("window_id", "agent.window_id"),
+ ("context_window_id", "agent.context_window_id"),
+ ("request_kind", "agent.request_kind"),
+ ("subagent_kind", "agent.subagent_kind"),
+ ("thread_source", "agent.thread_source"),
+ ("turn_trigger", "agent.turn_trigger"),
+ ("sandbox", "agent.sandbox"),
+ ("sandbox_mode", "agent.sandbox_mode"),
+ ("workspace_kind", "agent.workspace_kind"),
+];
+const CODEX_SCALAR_FIELDS: [(&str, &str); 4] = [
+ ("window_number", "agent.window_number"),
+ (
+ "forked_from_ordinal_exclusive",
+ "agent.forked_from_ordinal_exclusive",
+ ),
+ ("turn_started_at_unix_ms", "agent.turn_started_at_unix_ms"),
+ ("auto_review_enabled", "agent.auto_review_enabled"),
+];
+const CODEX_COMPACTION_FIELDS: [&str; 5] =
+ ["trigger", "reason", "implementation", "phase", "strategy"];
+/// Flat `client_metadata` keys Codex projects from the same snapshot, used when the blob is absent.
+const CODEX_FLAT_FIELDS: [(&str, &str); 8] = [
+ ("session_id", "session_id"),
+ ("thread_id", "thread_id"),
+ ("turn_id", "turn_id"),
+ ("root_turn_id", "root_turn_id"),
+ ("parent_turn_id", "parent_turn_id"),
+ ("x-codex-installation-id", "installation_id"),
+ ("x-codex-window-id", "window_id"),
+ ("x-codex-parent-thread-id", "parent_thread_id"),
+];
const HEADERS: [&str; 8] = [
"traceparent",
"tracestate",
@@ -63,7 +110,14 @@ pub(super) struct GenerationContext {
}
impl GenerationContext {
+ #[cfg(test)]
pub fn from_headers(headers: &HeaderMap) -> Self {
+ Self::from_request(headers, None)
+ }
+
+ /// `client_metadata` is the request body's agent metadata object, already
+ /// removed from the captured input by [`take_agent_client_metadata`].
+ pub fn from_request(headers: &HeaderMap, client_metadata: Option<&Map<String, Value>>) -> Self {
let ids = RandomIdGenerator::default();
let mut result = Self {
trace_id: ids.new_trace_id().to_string(),
@@ -124,7 +178,7 @@ impl GenerationContext {
result.metadata.insert(key, value.into());
}
}
- result.apply_agent(headers);
+ result.apply_agent(headers, client_metadata);
result
}
@@ -170,12 +224,12 @@ impl GenerationContext {
}
}
- fn apply_agent(&mut self, headers: &HeaderMap) {
- let Some(agent) = AgentContext::from_headers(headers) else {
+ fn apply_agent(&mut self, headers: &HeaderMap, client_metadata: Option<&Map<String, Value>>) {
+ let Some(agent) = AgentContext::from_request(headers, client_metadata) else {
return;
};
- for (key, value) in &agent.metadata {
- self.metadata.insert((*key).into(), value.clone().into());
+ for (key, value) in agent.metadata {
+ self.metadata.insert(key, value);
}
self.metadata.insert("agent.name".into(), agent.name.into());
if let Some(session_id) = &agent.session_id
@@ -202,11 +256,14 @@ struct AgentContext {
name: &'static str,
session_id: Option<String>,
turn_id: Option<String>,
- metadata: Vec<(&'static str, String)>,
+ metadata: Vec<(String, Value)>,
}
impl AgentContext {
- fn from_headers(headers: &HeaderMap) -> Option<Self> {
+ fn from_request(
+ headers: &HeaderMap,
+ client_metadata: Option<&Map<String, Value>>,
+ ) -> Option<Self> {
let bytes = AGENT_HEADERS
.iter()
.flat_map(|name| headers.get_all(*name))
@@ -216,7 +273,7 @@ impl AgentContext {
return None;
}
Self::parse_claude_code(headers)
- .or_else(|| Self::parse_codex(headers))
+ .or_else(|| Self::parse_codex(headers, client_metadata))
.or_else(|| Self::parse_opencode(headers))
.or_else(|| Self::parse_pi(headers))
}
@@ -240,23 +297,58 @@ impl AgentContext {
})
}
- fn parse_codex(headers: &HeaderMap) -> Option<Self> {
- let value = single_header(headers, "x-codex-turn-metadata")?;
- if value.len() > MAX_AGENT_METADATA_BYTES {
+ /// Codex sends its turn snapshot canonically as `client_metadata["x-codex-turn-metadata"]`
+ /// in the request body; the same-named header and the flat `client_metadata` keys are
+ /// compatibility projections of that snapshot.
+ fn parse_codex(
+ headers: &HeaderMap,
+ client_metadata: Option<&Map<String, Value>>,
+ ) -> Option<Self> {
+ let header = single_header(headers, CODEX_TURN_METADATA_KEY);
+ let client_metadata = client_metadata.filter(|metadata| is_codex_client_metadata(metadata));
+ if header.is_none() && client_metadata.is_none() {
return None;
}
- let value = serde_json::from_str::<Value>(value).ok()?;
- let value = value.as_object()?;
- let session_id = agent_json_field(value, "session_id");
- let thread_id = agent_json_field(value, "thread_id");
- let turn_id = agent_json_field(value, "turn_id");
+ let mut fields = client_metadata
+ .and_then(|metadata| metadata.get(CODEX_TURN_METADATA_KEY)?.as_str())
+ .and_then(|blob| parse_turn_metadata(blob, MAX_CLIENT_METADATA_BYTES))
+ .or_else(|| header.and_then(|blob| parse_turn_metadata(blob, MAX_AGENT_METADATA_BYTES)))
+ .unwrap_or_default();
+ for (source, target) in CODEX_FLAT_FIELDS {
+ if let Some(value) = client_metadata.and_then(|metadata| metadata.get(source))
+ && value.is_string()
+ && !fields.contains_key(target)
+ {
+ fields.insert(target.to_owned(), value.clone());
+ }
+ }
+ let session_id = agent_json_field(&fields, "session_id");
+ let thread_id = agent_json_field(&fields, "thread_id");
+ let turn_id = agent_json_field(&fields, "turn_id");
if session_id.is_none() && thread_id.is_none() && turn_id.is_none() {
return None;
}
let mut metadata = Vec::new();
- push_metadata(&mut metadata, "agent.session_id", session_id.as_ref());
- push_metadata(&mut metadata, "agent.thread_id", thread_id.as_ref());
- push_metadata(&mut metadata, "agent.turn_id", turn_id.as_ref());
+ for (source, target) in CODEX_STRING_FIELDS {
+ if let Some(value) = agent_json_field(&fields, source) {
+ metadata.push((target.to_owned(), Value::String(value)));
+ }
+ }
+ for (source, target) in CODEX_SCALAR_FIELDS {
+ if let Some(value) = fields
+ .get(source)
+ .filter(|value| value.is_number() || value.is_boolean())
+ {
+ metadata.push((target.to_owned(), value.clone()));
+ }
+ }
+ if let Some(compaction) = fields.get("compaction").and_then(Value::as_object) {
+ for key in CODEX_COMPACTION_FIELDS {
+ if let Some(value) = agent_json_field(compaction, key) {
+ metadata.push((format!("agent.compaction.{key}"), Value::String(value)));
+ }
+ }
+ }
Some(Self {
name: "codex",
session_id: thread_id,
@@ -318,13 +410,46 @@ impl AgentContext {
}
}
-fn push_metadata(
- metadata: &mut Vec<(&'static str, String)>,
- key: &'static str,
- value: Option<&String>,
-) {
+/// Remove a coding agent's `client_metadata` object from a captured request so its
+/// identifiers are recorded as `agent.*` metadata rather than as prompt input.
+/// Unrecognized or oversized objects stay in the request untouched.
+pub(crate) fn take_agent_client_metadata(
+ request: &mut Map<String, Value>,
+) -> Option<Map<String, Value>> {
+ let recognized = request
+ .get("client_metadata")
+ .and_then(Value::as_object)
+ .is_some_and(|metadata| {
+ is_codex_client_metadata(metadata)
+ && serde_json::to_vec(metadata)
+ .is_ok_and(|bytes| bytes.len() <= MAX_CLIENT_METADATA_BYTES)
+ });
+ if !recognized {
+ return None;
+ }
+ match request.remove("client_metadata") {
+ Some(Value::Object(metadata)) => Some(metadata),
+ _ => None,
+ }
+}
+
+fn is_codex_client_metadata(metadata: &Map<String, Value>) -> bool {
+ metadata.keys().any(|key| key.starts_with("x-codex-"))
+}
+
+fn parse_turn_metadata(blob: &str, limit: usize) -> Option<Map<String, Value>> {
+ if blob.len() > limit {
+ return None;
+ }
+ match serde_json::from_str::<Value>(blob).ok()? {
+ Value::Object(fields) => Some(fields),
+ _ => None,
+ }
+}
+
+fn push_metadata(metadata: &mut Vec<(String, Value)>, key: &str, value: Option<&String>) {
if let Some(value) = value {
- metadata.push((key, value.clone()));
+ metadata.push((key.to_owned(), Value::String(value.clone())));
}
}
diff --git a/ai-gateway/src/telemetry/context/tests.rs b/ai-gateway/src/telemetry/context/tests.rs
index c8076ec714..10887c76c1 100644
--- a/ai-gateway/src/telemetry/context/tests.rs
+++ b/ai-gateway/src/telemetry/context/tests.rs
@@ -251,6 +251,201 @@ fn agent_metadata_preserves_original_identifiers() {
);
}
+/// The Codex turn snapshot shape, including nested inventories that must not be copied.
+fn codex_turn_metadata() -> Value {
+ json!({
+ "installation_id": "install-1",
+ "session_id": "routing-session",
+ "thread_id": "thread-1",
+ "agent_name": "/root/explorer",
+ "turn_id": "turn-1",
+ "window_id": "thread-1:1",
+ "window_number": 1,
+ "context_window_id": "context-1",
+ "request_kind": "compaction",
+ "compaction": {
+ "trigger": "auto", "reason": "context_limit", "implementation": "remote",
+ "phase": "pre_turn", "strategy": "memento", "nested": {"skip": true}
+ },
+ "root_turn_id": "root-turn",
+ "parent_turn_id": "parent-turn",
+ "parent_thread_id": "parent-thread",
+ "subagent_kind": "collab_spawn",
+ "thread_source": "user",
+ "turn_trigger": "composer",
+ "sandbox": "seatbelt",
+ "sandbox_mode": "workspace-write",
+ "auto_review_enabled": true,
+ "node_repl_auto_review_required": true,
+ "node_repl_disabled": false,
+ "turn_started_at_unix_ms": 1_789_726_284_881_i64,
+ "workspace_kind": "projectless",
+ "workspaces": {"/Users/dev/project": {"has_changes": true}},
+ "tool_namespaces_info": {"functions": {"name": "functions", "functions": {"exec": {"name": "exec"}}}},
+ "custom_extra": "from-config",
+ "name": "spoofed-agent-name"
+ })
+}
+
+fn codex_client_metadata(turn_metadata: Option<&Value>) -> Map<String, Value> {
+ let mut metadata = json!({
+ "root_turn_id": "root-turn",
+ "session_id": "routing-session",
+ "thread_id": "thread-1",
+ "turn_id": "turn-1",
+ "x-codex-installation-id": "install-1",
+ "x-codex-window-id": "thread-1:1",
+ });
+ if let Some(turn_metadata) = turn_metadata {
+ metadata["x-codex-turn-metadata"] = turn_metadata.to_string().into();
+ }
+ metadata.as_object().unwrap().clone()
+}
+
+#[test]
+fn codex_client_metadata_supplies_agent_fields_without_headers() {
+ let client_metadata = codex_client_metadata(Some(&codex_turn_metadata()));
+ let context = GenerationContext::from_request(&HeaderMap::new(), Some(&client_metadata));
+ assert_eq!(context.attributes["session.id"], "codex:thread-1");
+ assert_eq!(context.attributes["langfuse.trace.name"], "codex");
+ assert!(!context.attributes.contains_key("user.id"));
+ assert_eq!(
+ context.metadata,
+ json!({
+ "agent.name": "codex",
+ "agent.id": "/root/explorer",
+ "agent.installation_id": "install-1",
+ "agent.session_id": "routing-session",
+ "agent.thread_id": "thread-1",
+ "agent.turn_id": "turn-1",
+ "agent.root_turn_id": "root-turn",
+ "agent.parent_turn_id": "parent-turn",
+ "agent.parent_thread_id": "parent-thread",
+ "agent.window_id": "thread-1:1",
+ "agent.window_number": 1,
+ "agent.context_window_id": "context-1",
+ "agent.request_kind": "compaction",
+ "agent.compaction.trigger": "auto",
+ "agent.compaction.reason": "context_limit",
+ "agent.compaction.implementation": "remote",
+ "agent.compaction.phase": "pre_turn",
+ "agent.compaction.strategy": "memento",
+ "agent.subagent_kind": "collab_spawn",
+ "agent.thread_source": "user",
+ "agent.turn_trigger": "composer",
+ "agent.sandbox": "seatbelt",
+ "agent.sandbox_mode": "workspace-write",
+ "agent.auto_review_enabled": true,
+ "agent.turn_started_at_unix_ms": 1_789_726_284_881_i64,
+ "agent.workspace_kind": "projectless",
+ })
+ .as_object()
+ .unwrap()
+ .clone()
+ );
+ // The body snapshot and the compatibility header identify the same turn.
+ let mut headers = HeaderMap::new();
+ headers.insert(
+ "x-codex-turn-metadata",
+ r#"{"session_id":"routing-session","thread_id":"thread-1","turn_id":"turn-1"}"#
+ .parse()
+ .unwrap(),
+ );
+ assert_eq!(
+ GenerationContext::from_headers(&headers).trace_id,
+ context.trace_id
+ );
+}
+
+#[test]
+fn codex_body_snapshot_is_preferred_and_flat_keys_fill_missing_snapshots() {
+ let mut headers = HeaderMap::new();
+ headers.insert(
+ "x-codex-turn-metadata",
+ r#"{"thread_id":"thread-1","turn_id":"header-turn"}"#
+ .parse()
+ .unwrap(),
+ );
+ let mut turn_metadata = codex_turn_metadata();
+ turn_metadata["turn_id"] = "body-turn".into();
+ let client_metadata = codex_client_metadata(Some(&turn_metadata));
+ let context = GenerationContext::from_request(&headers, Some(&client_metadata));
+ assert_eq!(context.metadata["agent.turn_id"], "body-turn");
+ assert_eq!(context.metadata["agent.id"], "/root/explorer");
+
+ let context =
+ GenerationContext::from_request(&HeaderMap::new(), Some(&codex_client_metadata(None)));
+ assert_eq!(context.attributes["session.id"], "codex:thread-1");
+ assert_eq!(
+ context.metadata,
+ json!({
+ "agent.name": "codex",
+ "agent.installation_id": "install-1",
+ "agent.session_id": "routing-session",
+ "agent.thread_id": "thread-1",
+ "agent.turn_id": "turn-1",
+ "agent.root_turn_id": "root-turn",
+ "agent.window_id": "thread-1:1",
+ })
+ .as_object()
+ .unwrap()
+ .clone()
+ );
+
+ for snapshot in [
+ "{malformed".to_owned(),
+ json!({"thread_id": "thread-1", "turn_id": "a".repeat(MAX_CLIENT_METADATA_BYTES)})
+ .to_string(),
+ "[]".to_owned(),
+ ] {
+ let mut client_metadata = codex_client_metadata(None);
+ client_metadata.insert("x-codex-turn-metadata".into(), snapshot.into());
+ let context = GenerationContext::from_request(&headers, Some(&client_metadata));
+ assert_eq!(context.metadata["agent.turn_id"], "header-turn");
+ assert_eq!(context.metadata["agent.root_turn_id"], "root-turn");
+ }
+
+ let unknown: Map<String, Value> = json!({"team": "search", "turn_id": "turn-1"})
+ .as_object()
+ .unwrap()
+ .clone();
+ let context = GenerationContext::from_request(&HeaderMap::new(), Some(&unknown));
+ assert!(context.metadata.is_empty());
+ assert!(!context.attributes.contains_key("session.id"));
+}
+
+#[test]
+fn agent_client_metadata_is_taken_only_when_recognized_and_bounded() {
+ let mut request: Map<String, Value> = json!({
+ "input": "hello",
+ "client_metadata": codex_client_metadata(Some(&codex_turn_metadata())),
+ })
+ .as_object()
+ .unwrap()
+ .clone();
+ let taken = take_agent_client_metadata(&mut request).unwrap();
+ assert_eq!(taken["x-codex-installation-id"], "install-1");
+ assert_eq!(
+ request,
+ json!({"input": "hello"}).as_object().unwrap().clone()
+ );
+
+ for client_metadata in [
+ json!({"team": "search"}),
+ json!("x-codex-turn-metadata"),
+ json!({"x-codex-turn-metadata": "a".repeat(MAX_CLIENT_METADATA_BYTES)}),
+ ] {
+ let mut request: Map<String, Value> =
+ json!({"input": "hello", "client_metadata": client_metadata})
+ .as_object()
+ .unwrap()
+ .clone();
+ let before = request.clone();
+ assert!(take_agent_client_metadata(&mut request).is_none());
+ assert_eq!(request, before);
+ }
+}
+
#[test]
fn explicit_context_overrides_inferred_agent_context() {
let mut headers = HeaderMap::new();
diff --git a/ai-gateway/src/telemetry/mapping.rs b/ai-gateway/src/telemetry/mapping.rs
index a412a326af..6c56dd7087 100644
--- a/ai-gateway/src/telemetry/mapping.rs
+++ b/ai-gateway/src/telemetry/mapping.rs
@@ -138,8 +138,8 @@ fn generation_metadata(facts: &InferenceFacts) -> Map<String, Value> {
);
metadata.insert("http_status".into(), json!(facts.http_status));
for (key, value) in [
- ("response_id", &facts.inference.provider_response_id),
- ("request_id", &facts.inference.provider_request_id),
+ ("response.id", &facts.inference.provider_response_id),
+ ("request.id", &facts.inference.provider_request_id),
] {
if let Some(value) = value {
metadata.insert(format!("langfuse.gateway.provider.{key}"), json!(value));
@@ -375,7 +375,7 @@ mod tests {
"team": "search", "enabled": true, "cost_center": 42,
"http_status": 500,
"langfuse.gateway.api-key.id": "spoofed-key",
- "langfuse.gateway.provider.request_id": "spoofed-request",
+ "langfuse.gateway.provider.request.id": "spoofed-request",
"langfuse.gateway.future_field": "spoofed-future",
"langfuse.gateway.api-key.metadata.team": "spoofed-team",
"agent.name": "spoofed-agent",
@@ -405,7 +405,7 @@ mod tests {
"connection"
);
assert_eq!(
- metadata["langfuse.gateway.provider.response_id"],
+ metadata["langfuse.gateway.provider.response.id"],
"response"
);
assert_eq!(metadata["langfuse.gateway.organization_id"], "org");
@@ -424,7 +424,7 @@ mod tests {
assert!(metadata.get(key).is_none(), "{key}");
}
assert_ne!(
- metadata["langfuse.gateway.provider.request_id"],
+ metadata["langfuse.gateway.provider.request.id"],
"spoofed-request"
);
assert_eq!(
diff --git a/ai-gateway/src/telemetry/mod.rs b/ai-gateway/src/telemetry/mod.rs
index 99d291277f..e9ef212d68 100644
--- a/ai-gateway/src/telemetry/mod.rs
+++ b/ai-gateway/src/telemetry/mod.rs
@@ -13,6 +13,7 @@ use std::{
use axum::http::HeaderMap;
use opentelemetry::trace::{FutureExt, TraceContextExt};
+use serde_json::{Map, Value};
use tokio::{sync::Semaphore, task::JoinSet, time::Instant};
use tracing_opentelemetry::OpenTelemetrySpanExt;
@@ -21,6 +22,7 @@ use crate::{
resolution::{ControlPlaneConfig, ResolutionError, ResolvedRequestContext},
};
use context::GenerationContext;
+pub(crate) use context::take_agent_client_metadata;
use otlp::Uploader;
const MAX_UPLOADS: usize = 32;
@@ -37,12 +39,16 @@ pub(crate) struct DeliveryContext {
}
impl DeliveryContext {
- pub fn from_resolved(context: &ResolvedRequestContext, headers: &HeaderMap) -> Self {
+ pub fn from_resolved(
+ context: &ResolvedRequestContext,
+ headers: &HeaderMap,
+ client_metadata: Option<&Map<String, Value>>,
+ ) -> Self {
Self {
project_id: context.attribution().project_id().to_owned(),
access_token: context.ingestion().access_token().to_owned(),
expires_at: context.ingestion().expires_at(),
- generation: GenerationContext::from_headers(headers),
+ generation: GenerationContext::from_request(headers, client_metadata),
}
}
}
diff --git a/ai-gateway/src/telemetry/tests.rs b/ai-gateway/src/telemetry/tests.rs
index 826399af99..f0ff2351aa 100644
--- a/ai-gateway/src/telemetry/tests.rs
+++ b/ai-gateway/src/telemetry/tests.rs
@@ -32,6 +32,7 @@ async fn grant() -> DeliveryContext {
DeliveryContext::from_resolved(
&resolved_request_context("provider-secret").await,
&HeaderMap::new(),
+ None,
)
}
@@ -301,6 +302,7 @@ async fn retained_byte_budget_is_released_after_successful_drain() {
let second = DeliveryContext::from_resolved(
&resolved_request_context("provider-secret").await,
&HeaderMap::new(),
+ None,
);
telemetry.record(second, facts("project-1"));
assert_eq!(telemetry.0.stats.dropped.load(Ordering::Relaxed), 1);
diff --git a/packages/shared/src/server/otel/OtelIngestionProcessor.metadataDropped.test.ts b/packages/shared/src/server/otel/OtelIngestionProcessor.metadataDropped.test.ts
index b833b8a806..ab945c3910 100644
--- a/packages/shared/src/server/otel/OtelIngestionProcessor.metadataDropped.test.ts
+++ b/packages/shared/src/server/otel/OtelIngestionProcessor.metadataDropped.test.ts
@@ -152,7 +152,7 @@ describe("gateway metadata", () => {
"langfuse.observation.input": '[{"role":"user","content":"Hi"}]',
"langfuse.observation.output": '[{"type":"message","content":[]}]',
"langfuse.observation.metadata": JSON.stringify({
- "langfuse.gateway.provider.request_id": "req-test",
+ "langfuse.gateway.provider.request.id": "req-test",
}),
"langfuse.observation.metadata.langfuse.gateway.api-key.id":
"key-test",
@@ -194,7 +194,7 @@ describe("gateway metadata", () => {
}),
});
expect(observation?.metadata).toEqual({
- "langfuse.gateway.provider.request_id": "req-test",
+ "langfuse.gateway.provider.request.id": "req-test",
"langfuse.gateway.api-key.id": "key-test",
attributes: {
...(scope === "langfuse-ai-gateway" ? {} : canonicalAttributes),