Skip to content

trulens.core.otel.client_hooks.tracing

trulens.core.otel.client_hooks.tracing

Assemble complete OpenTelemetry traces from hook event journals.

Classes

TurnIdentity dataclass

Run and record identity for one assembled coding-agent turn.

A turn is the unit of export and the unit of ingestion: each turn contributes exactly one record to its run. run_name is shared by every turn in a conversation, so a conversation maps to one run carrying one completed invocation per turn.

TraceAssembler

Convert one completed client turn into TruLens-compatible spans.

Functions
identify
identify(events: List[HookEvent]) -> Optional[TurnIdentity]

Resolve run and record identity for one turn.

Returns None for an empty turn. Identity is derived from the native client payloads so that it stays stable across retries: re-exporting a turn reuses the same record and run names rather than creating new ones.

assemble
assemble(
    events: List[HookEvent], *, stale: bool = False
) -> List[ReadableSpan]

Assemble root, agent, and operation spans for one turn.

Functions

environ_trace_context

environ_trace_context(
    environ: Optional[Mapping[str, str]] = None,
) -> Tuple[Optional[str], Optional[str]]

Read the W3C trace context the surrounding process exported, if any.

A coding agent that propagates trace context sets TRACEPARENT, and sometimes TRACESTATE, on the processes it spawns. That is how a hook invocation learns which span it was spawned under, since the payload on stdin carries no trace context of its own.

The values are returned as read and validated later, when spans are assembled, so a value that does not parse stays visible in the journal instead of being dropped at capture time.

PARAMETER DESCRIPTION
environ

Environment mapping to read. Defaults to os.environ.

TYPE: Optional[Mapping[str, str]] DEFAULT: None

RETURNS DESCRIPTION
Optional[str]

The (traceparent, tracestate) pair, with None for anything absent.

Optional[str]

tracestate is only returned alongside a traceparent, since it

Tuple[Optional[str], Optional[str]]

carries no meaning on its own.

inherited_span_context

inherited_span_context(
    events: Iterable[HookEvent],
) -> Optional[SpanContext]

Return the remote span context a turn's events were spawned under.

Hooks fire repeatedly across one turn, and only some of them run while the agent holds an active span, so the events carry the context unevenly. The earliest one that parses wins, which puts assembled spans under the outermost span the agent had open rather than under a later, narrower one.

PARAMETER DESCRIPTION
events

The turn's events, in any order.

TYPE: Iterable[HookEvent]

RETURNS DESCRIPTION
Optional[SpanContext]

A remote SpanContext when at least one event carries a valid

Optional[SpanContext]

traceparent, otherwise None.

stale_after_from_environment

stale_after_from_environment() -> timedelta

Read the incomplete-turn timeout from adapter configuration.