feat(app-server): add tracing to all app-server APIs (#13285)

### Overview
This PR adds the first piece of tracing for app-server JSON-RPC
requests.

There are two main changes:
- JSON-RPC requests can now take an optional W3C trace context at the
top level via a `trace` field (`traceparent` / `tracestate`).
- app-server now creates a dedicated request span for every inbound
JSON-RPC request in `MessageProcessor`, and uses the request-level trace
context as the parent when present.

For compatibility with existing flows, app-server still falls back to
the TRACEPARENT env var when there is no request-level traceparent.

This PR is intentionally scoped to the app-server boundary. In a
followup, we'll actually propagate trace context through the async
handoff into core execution spans like run_turn, which will make
app-server traces much more useful.

### Spans
A few details on the app-server span shape:
- each inbound request gets its own server span
- span/resource names are based on the JSON-RPC method (`initialize`,
`thread/start`, `turn/start`, etc.)
- spans record transport (stdio vs websocket), request id, connection
id, and client name/version when available
- `initialize` stores client metadata in session state so later requests
on the same connection can reuse it

codex-rs/otel/src/lib.rs

@@ -1,6 +1,7 @@
 pub mod config;
 pub mod metrics;
 pub mod otel_provider;
+pub mod trace_context;
 pub mod traces;
 
 mod otlp;
@@ -23,6 +24,11 @@ use tracing::debug;
 
 pub use crate::metrics::runtime_metrics::RuntimeMetricTotals;
 pub use crate::metrics::runtime_metrics::RuntimeMetricsSummary;
+pub use crate::otel_provider::traceparent_context_from_env;
+pub use crate::trace_context::context_from_w3c_trace_context;
+pub use crate::trace_context::current_span_w3c_trace_context;
+pub use crate::trace_context::set_parent_from_context;
+pub use crate::trace_context::set_parent_from_w3c_trace_context;
 
 #[derive(Debug, Clone, Serialize, Display)]
 #[serde(rename_all = "snake_case")]

codex-rs/otel/src/otel_provider.rs

@@ -3,13 +3,12 @@ use crate::config::OtelHttpProtocol;
 use crate::config::OtelSettings;
 use crate::metrics::MetricsClient;
 use crate::metrics::MetricsConfig;
+use crate::trace_context::context_from_trace_headers;
 use gethostname::gethostname;
 use opentelemetry::Context;
 use opentelemetry::KeyValue;
 use opentelemetry::context::ContextGuard;
 use opentelemetry::global;
-use opentelemetry::propagation::TextMapPropagator;
-use opentelemetry::trace::TraceContextExt;
 use opentelemetry::trace::TracerProvider as _;
 use opentelemetry_appender_tracing::layer::OpenTelemetryTracingBridge;
 use opentelemetry_otlp::LogExporter;
@@ -30,7 +29,6 @@ use opentelemetry_sdk::trace::SdkTracerProvider;
 use opentelemetry_sdk::trace::Tracer;
 use opentelemetry_semantic_conventions as semconv;
 use std::cell::RefCell;
-use std::collections::HashMap;
 use std::env;
 use std::error::Error;
 use std::sync::OnceLock;
@@ -172,7 +170,7 @@ impl Drop for OtelProvider {
     }
 }
 
-pub(crate) fn traceparent_context_from_env() -> Option<Context> {
+pub fn traceparent_context_from_env() -> Option<Context> {
     TRACEPARENT_CONTEXT
         .get_or_init(load_traceparent_context)
         .clone()
@@ -194,7 +192,7 @@ fn load_traceparent_context() -> Option<Context> {
     let traceparent = env::var(TRACEPARENT_ENV_VAR).ok()?;
     let tracestate = env::var(TRACESTATE_ENV_VAR).ok();
 
-    match extract_traceparent_context(traceparent, tracestate) {
+    match context_from_trace_headers(Some(&traceparent), tracestate.as_deref()) {
         Some(context) => {
             debug!("TRACEPARENT detected; continuing trace from parent context");
             Some(context)
@@ -206,22 +204,6 @@ fn load_traceparent_context() -> Option<Context> {
     }
 }
 
-fn extract_traceparent_context(traceparent: String, tracestate: Option<String>) -> Option<Context> {
-    let mut headers = HashMap::new();
-    headers.insert("traceparent".to_string(), traceparent);
-    if let Some(tracestate) = tracestate {
-        headers.insert("tracestate".to_string(), tracestate);
-    }
-
-    let context = TraceContextPropagator::new().extract(&headers);
-    let span = context.span();
-    let span_context = span.span_context();
-    if !span_context.is_valid() {
-        return None;
-    }
-    Some(context)
-}
-
 fn make_resource(settings: &OtelSettings) -> Resource {
     Resource::builder()
         .with_service_name(settings.service_name.clone())
@@ -407,8 +389,9 @@ mod tests {
     fn parses_valid_traceparent() {
         let trace_id = "00000000000000000000000000000001";
         let span_id = "0000000000000002";
-        let context = extract_traceparent_context(format!("00-{trace_id}-{span_id}-01"), None)
-            .expect("trace context");
+        let context =
+            context_from_trace_headers(Some(&format!("00-{trace_id}-{span_id}-01")), None)
+                .expect("trace context");
         let span = context.span();
         let span_context = span.span_context();
         assert_eq!(
@@ -421,7 +404,7 @@ mod tests {
 
     #[test]
     fn invalid_traceparent_returns_none() {
-        assert!(extract_traceparent_context("not-a-traceparent".to_string(), None).is_none());
+        assert!(context_from_trace_headers(Some("not-a-traceparent"), None).is_none());
     }
 
     #[test]

codex-rs/otel/src/trace_context.rs

@@ -0,0 +1,106 @@
+use std::collections::HashMap;
+
+use codex_protocol::protocol::W3cTraceContext;
+use opentelemetry::Context;
+use opentelemetry::propagation::TextMapPropagator;
+use opentelemetry::trace::TraceContextExt;
+use opentelemetry_sdk::propagation::TraceContextPropagator;
+use tracing::Span;
+use tracing_opentelemetry::OpenTelemetrySpanExt;
+
+pub fn current_span_w3c_trace_context() -> Option<W3cTraceContext> {
+    let context = Span::current().context();
+    if !context.span().span_context().is_valid() {
+        return None;
+    }
+
+    let mut headers = HashMap::new();
+    TraceContextPropagator::new().inject_context(&context, &mut headers);
+
+    Some(W3cTraceContext {
+        traceparent: headers.remove("traceparent"),
+        tracestate: headers.remove("tracestate"),
+    })
+}
+
+pub fn context_from_w3c_trace_context(trace: &W3cTraceContext) -> Option<Context> {
+    context_from_trace_headers(trace.traceparent.as_deref(), trace.tracestate.as_deref())
+}
+
+pub fn set_parent_from_w3c_trace_context(span: &Span, trace: &W3cTraceContext) -> bool {
+    if let Some(context) = context_from_w3c_trace_context(trace) {
+        set_parent_from_context(span, context);
+        true
+    } else {
+        false
+    }
+}
+
+pub fn set_parent_from_context(span: &Span, context: Context) {
+    let _ = span.set_parent(context);
+}
+
+pub(crate) fn context_from_trace_headers(
+    traceparent: Option<&str>,
+    tracestate: Option<&str>,
+) -> Option<Context> {
+    let traceparent = traceparent?;
+    let mut headers = HashMap::new();
+    headers.insert("traceparent".to_string(), traceparent.to_string());
+    if let Some(tracestate) = tracestate {
+        headers.insert("tracestate".to_string(), tracestate.to_string());
+    }
+
+    let context = TraceContextPropagator::new().extract(&headers);
+    if !context.span().span_context().is_valid() {
+        return None;
+    }
+    Some(context)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::context_from_trace_headers;
+    use super::context_from_w3c_trace_context;
+    use codex_protocol::protocol::W3cTraceContext;
+    use opentelemetry::trace::SpanId;
+    use opentelemetry::trace::TraceContextExt;
+    use opentelemetry::trace::TraceId;
+    use pretty_assertions::assert_eq;
+
+    #[test]
+    fn parses_valid_w3c_trace_context() {
+        let trace_id = "00000000000000000000000000000001";
+        let span_id = "0000000000000002";
+        let context = context_from_w3c_trace_context(&W3cTraceContext {
+            traceparent: Some(format!("00-{trace_id}-{span_id}-01")),
+            tracestate: None,
+        })
+        .expect("trace context");
+
+        let span = context.span();
+        let span_context = span.span_context();
+        assert_eq!(
+            span_context.trace_id(),
+            TraceId::from_hex(trace_id).unwrap()
+        );
+        assert_eq!(span_context.span_id(), SpanId::from_hex(span_id).unwrap());
+        assert!(span_context.is_remote());
+    }
+
+    #[test]
+    fn invalid_traceparent_returns_none() {
+        assert!(context_from_trace_headers(Some("not-a-traceparent"), None).is_none());
+    }
+
+    #[test]
+    fn missing_traceparent_returns_none() {
+        assert!(
+            context_from_w3c_trace_context(&W3cTraceContext {
+                traceparent: None,
+                tracestate: Some("vendor=value".to_string()),
+            })
+            .is_none()
+        );
+    }
+}