Skip to content

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: MutableMapping[str, str]

RETURNS DESCRIPTION
bool

True when the configured propagators actually wrote something.

extract_trace_context

extract_trace_context(
    carrier: Mapping[str, str],
) -> Optional[SpanContext]

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 {"traceparent": "00-<trace>-<span>-01"}. Keys are matched the way the configured propagators expect them, which for W3C means lowercase, so environment variable names have to be lowercased before they are passed in.

TYPE: Mapping[str, str]

RETURNS DESCRIPTION
Optional[SpanContext]

The remote SpanContext when the carrier holds a valid one, otherwise

Optional[SpanContext]

None. The result carries is_remote=True, so it can be used directly as

Optional[SpanContext]

a parent for locally built spans.

tracing_transport

tracing_transport(inner: Optional[Any] = None) -> Any

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 httpx.HTTPTransport, which is what a plain httpx.Client uses.

TYPE: Optional[Any] DEFAULT: None

RETURNS DESCRIPTION
Any

An httpx.BaseTransport that injects before delegating.

async_tracing_transport

async_tracing_transport(inner: Optional[Any] = None) -> Any

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 httpx.AsyncHTTPTransport, which is what a plain httpx.AsyncClient uses.

TYPE: Optional[Any] DEFAULT: None

RETURNS DESCRIPTION
Any

An httpx.AsyncBaseTransport that injects before delegating.