Skip to content

Commit d3b8333

Browse files
feat: expose native trace context
1 parent 71ae120 commit d3b8333

14 files changed

Lines changed: 817 additions & 23 deletions

File tree

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
"""Continue an explicit parent through native tools and a second worker.
2+
3+
Run with ``python -m examples.observability.trace_context``. All provider and
4+
collector traffic is synthetic and stays on loopback.
5+
"""
6+
7+
from __future__ import annotations
8+
9+
import asyncio
10+
11+
from agents import Agent, ToolContext, TraceContext, function_tool, telemetry
12+
from agents.testing import ScriptedResponses, text, tool_call
13+
14+
from .trace_walkthrough import Collector
15+
16+
17+
async def exercise(collector_url: str) -> None:
18+
await telemetry.configure(
19+
traces=telemetry.OtlpHttp(endpoint=collector_url + "/v1/traces", protocol="json")
20+
)
21+
try:
22+
23+
@function_tool
24+
async def delegate(ctx: ToolContext[None]) -> str:
25+
"""Run synthetic work under the issuing native tool span."""
26+
# An application HTTP client can send these two headers, or create
27+
# its own client span with this explicit parent before injecting.
28+
# No Python provider or ambient ContextVar is adopted by the SDK.
29+
assert ctx.trace_context is not None
30+
headers = ctx.trace_context.to_headers()
31+
async with ScriptedResponses([text("Worker finished")]) as worker:
32+
result = await Agent(
33+
instructions="Complete the synthetic task.", provider=worker.provider
34+
).run("Work", parent_trace=headers)
35+
return result.final_output
36+
37+
parent = TraceContext(traceparent="00-11111111111111111111111111111111-2222222222222222-01")
38+
async with ScriptedResponses(
39+
[tool_call("delegate", {}, call_id="delegate-1")], [text("Done")]
40+
) as peer:
41+
agent = Agent(
42+
instructions="Delegate the synthetic task.",
43+
tools=[delegate],
44+
provider=peer.provider,
45+
)
46+
result = await agent.run("Start", parent_trace=parent)
47+
print(result.final_output)
48+
finally:
49+
await telemetry.shutdown()
50+
51+
52+
def main() -> None:
53+
# Telemetry initialization and shutdown belong to one process, outside all
54+
# Session lifetimes. Fresh workers receive fresh host carriers; checkpoints
55+
# contain history and accepted receipts, never an active trace context.
56+
with Collector().serve() as collector:
57+
asyncio.run(exercise(collector.url))
58+
count = sum(
59+
len(scope["spans"])
60+
for batch in collector.snapshot()
61+
for resource in batch["data"]["resourceSpans"]
62+
for scope in resource["scopeSpans"]
63+
)
64+
print(f"Received {count} native spans")
65+
66+
67+
if __name__ == "__main__":
68+
main()

‎packages/codex/rust/lib.rs‎

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1628,11 +1628,21 @@ impl NativeThread {
16281628
manual_checkpoint::prepare(&inner, &self.manual).map_err(py_error)
16291629
}
16301630

1631-
fn _continue_manual<'py>(&self, py: Python<'py>) -> PyResult<Bound<'py, PyAny>> {
1631+
#[pyo3(signature = (trace_json=None))]
1632+
fn _continue_manual<'py>(
1633+
&self,
1634+
py: Python<'py>,
1635+
trace_json: Option<String>,
1636+
) -> PyResult<Bound<'py, PyAny>> {
1637+
let trace = trace_json
1638+
.as_deref()
1639+
.map(serde_json::from_str::<codex_protocol::protocol::W3cTraceContext>)
1640+
.transpose()
1641+
.map_err(|_| PyValueError::new_err("Invalid trace carrier"))?;
16321642
let inner = self.current()?;
16331643
let manual = self.manual.clone();
16341644
async_bridge::future_into_py(py, async move {
1635-
let receipt = manual_checkpoint::continue_if_ready(&inner, &manual)
1645+
let receipt = manual_checkpoint::continue_if_ready(&inner, &manual, trace)
16361646
.await
16371647
.map_err(py_error)?;
16381648
serde_json::to_string(&receipt).map_err(py_error)

‎packages/codex/rust/manual_checkpoint.rs‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -549,6 +549,7 @@ pub(crate) fn prepare(thread: &crate::engine::ThreadState, owner: &Owner) -> Res
549549
pub(crate) async fn continue_if_ready(
550550
thread: &crate::engine::ThreadState,
551551
owner: &Owner,
552+
trace: Option<codex_protocol::protocol::W3cTraceContext>,
552553
) -> Result<Value> {
553554
let _operation = thread.engine.operation(false)?;
554555
let _mutation = thread.mutations.lock().await;
@@ -580,8 +581,8 @@ pub(crate) async fn continue_if_ready(
580581
frame.turn,
581582
frame.seen.into_iter().collect(),
582583
match frame.state["native_continuation"].get("output_schema") {
583-
Some(schema) => serde_json::json!({"output_schema":schema}),
584-
None => serde_json::json!({}),
584+
Some(schema) => serde_json::json!({"output_schema":schema,"trace":trace}),
585+
None => serde_json::json!({"trace":trace}),
585586
},
586587
)
587588
.await?;

‎packages/codex/rust/ops.rs‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -522,6 +522,7 @@ pub(crate) async fn interrupt_managed_root(
522522
}
523523

524524
params!(RecoveryOptions {
525+
trace: Option<W3cTraceContext>,
525526
#[serde(default)]
526527
output_schema: Option<serde_json::Map<String, Value>>,
527528
});
@@ -541,7 +542,7 @@ pub async fn recover_prepared(
541542
RecoverTurnRequest {
542543
turn_id,
543544
thread_settings: Default::default(),
544-
trace: None,
545+
trace: p.trace,
545546
cyber_access_program: None,
546547
final_output_json_schema: p.output_schema.map(Value::Object),
547548
},

‎packages/codex/rust/python_tools.rs‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1892,7 +1892,8 @@ impl PythonTools {
18921892
"namespace": entry.name.namespace, "tool": entry.name.name,
18931893
"arguments": arguments, "_sdk_python_tool": key.reply,
18941894
"_sdk_invocation": invocation, "_sdk_manual": entry.manual,
1895-
"_sdk_code_origin": code_origin, "_sdk_model": model
1895+
"_sdk_code_origin": code_origin, "_sdk_model": model,
1896+
"_sdk_trace": codex_otel::current_span_w3c_trace_context()
18961897
}
18971898
});
18981899
let (sender, receiver) = oneshot::channel();
@@ -3843,7 +3844,7 @@ pub(crate) mod managed_tests {
38433844
let recovery_state = resumed.clone();
38443845
let manual = restored.manual.clone();
38453846
let recovering = tokio::spawn(async move {
3846-
manual_checkpoint::continue_if_ready(&recovery_state, &manual).await.unwrap()
3847+
manual_checkpoint::continue_if_ready(&recovery_state, &manual, None).await.unwrap()
38473848
});
38483849
hold.entered.acquire().await.unwrap().forget();
38493850
assert_eq!(provider.requests.lock().unwrap().len(), 2,

‎src/agents/__init__.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@
1010
ToolContext as ToolContext,
1111
function_tool as function_tool,
1212
)
13+
from ._trace_context import TraceContext as TraceContext
1314
from .agent import (
1415
Agent as Agent,
1516
ModelSettings as ModelSettings,
@@ -98,6 +99,7 @@
9899
from .turn import PendingRequests as PendingRequests, Turn as Turn
99100

100101
_MODULES = {
102+
"TraceContext": "._trace_context",
101103
"Allow": ".native_interception",
102104
"Deny": ".native_interception",
103105
"ReplaceArguments": ".native_interception",

‎src/agents/_function_tools.py‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@
2929
from pydantic import BaseModel, PydanticSchemaGenerationError, TypeAdapter
3030
from typing_extensions import ParamSpec, TypeVar
3131

32+
from ._trace_context import TraceContext
3233
from .manual import ActionRequested, InputT, ResultT, _CapturedManual
3334
from .mcp import HttpMCP, StdioMCP
3435
from .native_agents import ChildInvocation, NativeAgents
@@ -61,6 +62,10 @@ class ToolContext(Generic[ContextT_co]):
6162
6263
A first parameter annotated with ToolContext is injected by the session.
6364
Its value never becomes part of the model-visible argument schema.
65+
trace_context snapshots the native issuing span for outgoing propagation;
66+
None means native tracing supplied no carrier in the supported profile.
67+
Retaining this metadata
68+
does not keep that span alive or grant callback execution authority.
6469
"""
6570

6671
context: ContextT_co = field(repr=False)
@@ -69,6 +74,7 @@ class ToolContext(Generic[ContextT_co]):
6974
original_arguments: Mapping[str, Any] = field(default_factory=dict, repr=False)
7075
effective_arguments: Mapping[str, Any] = field(default_factory=dict, repr=False)
7176
call: ToolCallInfo = field(kw_only=True)
77+
trace_context: TraceContext | None = field(default=None, kw_only=True, repr=False)
7278

7379

7480
@dataclass(frozen=True, kw_only=True)

‎src/agents/_trace_context.py‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
"""Explicit W3C correlation values; no ambient tracing state."""
2+
3+
from __future__ import annotations
4+
5+
import re
6+
from collections.abc import Mapping
7+
from dataclasses import dataclass, field
8+
from typing import cast
9+
10+
_PARENT = re.compile(r"([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})")
11+
_KEY = re.compile(
12+
r"(?:[a-z][a-z0-9_*/-]{0,255}|[a-z0-9][a-z0-9_*/-]{0,240}@[a-z][a-z0-9_*/-]{0,12})"
13+
)
14+
15+
16+
@dataclass(frozen=True, kw_only=True)
17+
class TraceContext:
18+
"""An immutable W3C parent carrier, independent of any tracing provider.
19+
20+
The traceparent has an SDK limit of 512 ASCII characters. Trace IDs and span
21+
IDs must be nonzero lowercase hex. Version 00 accepts defined flags 00 or
22+
01. Future versions retain their opaque suffix; native execution interprets
23+
the known prefix. Tracestate accepts at most 32 members, each with a key and
24+
value of at most 256 ASCII characters. The native propagator limits the
25+
system ID after @ to 13 characters. Optional whitespace and empty members
26+
are normalized. These limits define the supported native carrier profile.
27+
Put no credentials or private content in either header. This value does
28+
not keep a span alive, create spans, or propagate baggage.
29+
"""
30+
31+
traceparent: str = field(repr=False)
32+
tracestate: str | None = field(default=None, repr=False)
33+
34+
def __post_init__(self) -> None:
35+
parent = self.traceparent
36+
if not isinstance(parent, str):
37+
raise TypeError("traceparent must be a string")
38+
match = _PARENT.match(parent)
39+
if (
40+
match is None
41+
or len(parent) > 512
42+
or match[1] == "ff"
43+
or int(match[2], 16) == 0
44+
or int(match[3], 16) == 0
45+
or (match[1] == "00" and len(parent) != 55)
46+
or (match[1] == "00" and match[4] not in ("00", "01"))
47+
or (len(parent) > 55 and parent[55] != "-")
48+
or any(not 0x21 <= ord(char) <= 0x7E for char in parent)
49+
):
50+
raise ValueError("Invalid W3C traceparent")
51+
state = self.tracestate
52+
if state is None:
53+
return
54+
if not isinstance(state, str):
55+
raise TypeError("tracestate must be a string or None")
56+
if len(state.split(",")) > 32:
57+
raise ValueError("Invalid W3C tracestate")
58+
members: dict[str, str] = {}
59+
for member in state.split(","):
60+
member = member.strip(" \t")
61+
if not member:
62+
continue
63+
key, separator, value = member.partition("=")
64+
if (
65+
not separator
66+
or _KEY.fullmatch(key) is None
67+
or key in members
68+
or not 1 <= len(value) <= 256
69+
or any(not 0x20 <= ord(char) <= 0x7E or char in ",=" for char in value)
70+
):
71+
raise ValueError("Invalid W3C tracestate")
72+
members[key] = value
73+
object.__setattr__(
74+
self, "tracestate", ",".join(f"{k}={v}" for k, v in members.items()) or None
75+
)
76+
77+
def to_headers(self) -> dict[str, str]:
78+
"""Return a new lowercase header map containing only this carrier."""
79+
headers = {"traceparent": self.traceparent}
80+
if self.tracestate is not None:
81+
headers["tracestate"] = self.tracestate
82+
return headers
83+
84+
85+
def _trace_context(value: TraceContext | Mapping[str, str | None] | None) -> TraceContext | None:
86+
"""Normalize once at public admission, before runtime effects."""
87+
if value is None or isinstance(value, TraceContext):
88+
return value
89+
if not isinstance(value, Mapping):
90+
raise TypeError("parent_trace must be TraceContext, a carrier mapping, or None")
91+
if "traceparent" not in value or any(key not in ("traceparent", "tracestate") for key in value):
92+
raise ValueError("A trace carrier requires traceparent and optional tracestate only")
93+
return TraceContext(
94+
traceparent=cast(str, value["traceparent"]), tracestate=value.get("tracestate")
95+
)
96+
97+
98+
def _native_trace_context(value: Mapping[str, str | None] | None) -> TraceContext | None:
99+
# Native tracing can inherit settings outside the public carrier profile.
100+
# Optional correlation metadata must not turn a valid tool into a failure.
101+
try:
102+
return _trace_context(value)
103+
except (TypeError, ValueError):
104+
return None

0 commit comments

Comments
 (0)