trulens.core.otel.propagation¶
trulens.core.otel.propagation
¶
W3C trace context propagation across process and HTTP boundaries.
TruLens instruments the caller, but the LLM provider runs on the other side of an HTTP call. Nothing carries the active span's context across that boundary, so the provider's server span starts a trace of its own and the two ends are correlated only by timing. The helpers here put the active span's W3C trace context on the outbound request headers, so the provider's span becomes a child of the caller's span and both ends land in one trace.
The same boundary problem runs the other way. TruLens is sometimes the callee:
a coding agent exports a trace context to the processes it spawns, and spans
built in one of those processes belong in the trace the agent already started.
extract_trace_context reads a context back out of a carrier for that case.
Functions¶
inject_trace_context
¶
inject_trace_context(
headers: MutableMapping[str, str],
) -> bool
Inject the active span's trace context into headers.
Uses the globally configured propagators, so a traceparent header is
written when the default W3C propagator is installed, and nothing is
written when the span context is invalid or propagation is disabled.
| PARAMETER | DESCRIPTION |
|---|---|
headers
|
Mutable header mapping to write into, modified in place.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
bool
|
True when the configured propagators actually wrote something. |
extract_trace_context
¶
Extract a remote span context from carrier.
The counterpart to inject_trace_context. Uses the globally configured
propagators, so turning propagation off globally turns extraction off with
it, and a carrier that does not parse yields None rather than raising.
| PARAMETER | DESCRIPTION |
|---|---|
carrier
|
Header-style mapping to read from, for example
|
| RETURNS | DESCRIPTION |
|---|---|
Optional[SpanContext]
|
The remote |
Optional[SpanContext]
|
None. The result carries |
Optional[SpanContext]
|
a parent for locally built spans. |
tracing_transport
¶
Return an httpx transport that injects trace context on every request.
This is the synchronous transport. For httpx.AsyncClient, use
async_tracing_transport; the two are not interchangeable, because httpx
dispatches sync and async requests through different base classes.
Attach it to a client and hand that client to the provider SDK, so the provider's server span is parented under the active TruLens span:
client = httpx.Client(transport=tracing_transport())
provider = OpenAI(http_client=client)
| PARAMETER | DESCRIPTION |
|---|---|
inner
|
Transport to delegate to. Defaults to |
| RETURNS | DESCRIPTION |
|---|---|
Any
|
An |
async_tracing_transport
¶
Return an async httpx transport that injects trace context.
The async counterpart to tracing_transport, for the async clients the
provider SDKs expose:
client = httpx.AsyncClient(transport=async_tracing_transport())
provider = AsyncOpenAI(http_client=client)
| PARAMETER | DESCRIPTION |
|---|---|
inner
|
Transport to delegate to. Defaults to
|
| RETURNS | DESCRIPTION |
|---|---|
Any
|
An |