trulens.core.otel.client_hooks¶

trulens.core.otel.client_hooks ¶

TruLens instrumentation for coding-agent client hooks.

Classes¶

HookEvent `dataclass` ¶

A normalized event emitted by a coding-agent client.

Functions¶

to_dict ¶

to_dict() -> Dict[str, Any]

Serialize the event for durable journaling.

from_dict `classmethod` ¶

from_dict(value: Dict[str, Any]) -> 'HookEvent'

Deserialize an event from durable storage.

RunCoordinator ¶

Create and complete runs for exported coding-agent turns.

Apps and runs are cached per process because a hook export drains many turns from the same conversation, and each add_run or app construction is a round trip to the backend.

Functions¶

ensure_run ¶

ensure_run(identity: TurnIdentity) -> Optional[Any]

Ensure the run for identity exists before its spans are exported.

The run must exist first because exported spans carry its name.

Returns the run, or None when run management is disabled or the destination has no run concept. Raises if the run could not be created, so the caller retries the turn rather than exporting spans that would never reach a terminal status.

complete_turn ¶

complete_turn(
    identity: TurnIdentity, run: Optional[Any] = None
) -> bool

Start ingestion for one exported turn.

This is the call that drives the turn's invocation to a terminal status. It runs after a successful span export so that the ingestion window does not open before the spans it waits for have been sent.

Returns whether ingestion was started; False means run management is disabled or unsupported. Raises if ingestion could not be started.

HookService ¶

Normalize, sanitize, journal, assemble, and export hook events.

Functions¶

ingest ¶

ingest(
    client: str, payload: Mapping[str, Any]
) -> Tuple[str, bool]

Normalize and durably journal one hook payload without exporting.

flush ¶

flush() -> bool

Export all complete, retryable, or stale turns in the journal.

Each turn's run is created before its spans are exported, because the spans carry the run name, and its ingestion is started afterwards, which is what drives the turn's invocation to a terminal status. A turn is only marked exported once both have succeeded; otherwise it is released for retry, since spans without ingestion would leave the run in-progress forever.

trulens.core.otel.client_hooks¶