trulens.core.otel.client_hooks.runs¶
AI Observability run lifecycle for coding-agent hook exports.
Exporting spans is not sufficient to make a turn observable. A run's displayed
status is derived from its run metadata, not from the presence of spans, and the
only writer that creates and completes invocation metadata is the ingestion
query started through
RunDaoBase.start_ingestion_query.
Without it a run stays non-terminal forever and renders as perpetually
in-progress.
Each conversation maps to one run, and each exported turn contributes one completed invocation to that run. The run therefore reaches a terminal status after the first turn and stays terminal as later turns arrive, because run status resolves against the most recent invocation.
Every operation here distinguishes an unsupported destination from a genuine failure. Destinations with no run concept report "not applicable" and are skipped quietly; real failures raise so the caller can apply the journal's existing retry and backoff, because a turn whose ingestion never started is not actually finished.
Classes¶
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(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(
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.