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.
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 |
| RETURNS | DESCRIPTION |
|---|---|
Optional[str]
|
The |
Optional[str]
|
|
Tuple[Optional[str], Optional[str]]
|
carries no meaning on its own. |
inherited_span_context
¶
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. |
| RETURNS | DESCRIPTION |
|---|---|
Optional[SpanContext]
|
A remote |
Optional[SpanContext]
|
|