Telemetry Integration¶
Requires pip install 'techrevati-runtime[otel]'.
OpenTelemetrySink keeps one parent span open for the agent or phase
lifecycle. Tool calls open child spans under that parent, and
tool-scoped failures close only the tool span. Terminal session
failures still close the parent span.
Event details are omitted from spans by default because callers may put prompt
fragments, tool arguments, or exception text into AgentEvent.detail. Use
OpenTelemetrySink(include_event_detail=True) only after detail values are
sanitized and telemetry retention is approved.
GenAI semantic conventions¶
The sink emits OpenTelemetry GenAI semantic-convention signals:
- Spans carry
gen_ai.operation.name,gen_ai.provider.name, andgen_ai.agent.name. Aninvoke_agent {role}span nests under the openinvoke_workflowspan of its phase, when there is one. Tool calls areexecute_tool {tool}children withgen_ai.tool.name(concurrent calls to the same tool each get their own span via a per-key LIFO stack). Model turns arechat {model}client spans backdated by the measured duration. - Token metrics (
OpenTelemetryUsageSink):gen_ai.client.inference.usage.input_tokens(including cached tokens),.output_tokens,.cache_read.input_tokensand.cache_write.input_tokenscounters, plus atechrevati.cost.usdcounter (no standard GenAI cost metric exists yet). - Legacy token metric: the conventions have removed
gen_ai.client.token.usage. It stays on by default so existing dashboards keep working; turn it off withOpenTelemetryUsageSink(emit_legacy_token_metric=False)once they read the counters. - Duration metrics (
OpenTelemetryMetricsSink, an event sink):gen_ai.client.inference.durationandgen_ai.execute_tool.durationhistograms in seconds, witherror.typeon failure. The conventions' bucket boundaries are applied as an advisory on OpenTelemetry API versions that support it; older ones use the SDK's default buckets. - Message bodies: if a caller places
gen_ai.input.messages/gen_ai.output.messagesinAgentEvent.data, they are emitted as span events of the same name — but only wheninclude_event_detail=True, since message content is sensitive. The runtime does not own the model call, so it never fabricates these; they appear only when the caller supplies them.
These conventions now live in the
semantic-conventions-genai
repository and are still marked Development, so names can change.
Two required attributes cannot be known exactly by the runtime:
gen_ai.provider.name: the runtime does not make the model call. Pass the real provider asprovider_name; the defaulttechrevationly marks the data's source.gen_ai.token.modality: alwaysunknown, as the conventions require whenUsageSnapshotdoes not split tokens by modality.
Process exit¶
Spans still open at normal interpreter exit are ended with
error.type=abrupt_termination. That hook does not run on a default SIGTERM,
os._exit or a hard crash, and a span ended there only reaches the exporter if the
TracerProvider shuts down afterwards, so create the provider before the first
sink. For SIGTERM, or a provider created later, call sink.shutdown() yourself.
techrevati.runtime.otel ¶
Telemetry integration for runtime events and usage.
This module is import-safe only if the [otel] extra is installed.
At import time it tries to load opentelemetry packages; if they
are missing, a clear ImportError is raised so callers learn what
to install instead of getting an obscure AttributeError later.
The sink emits semantic-convention attributes so telemetry backends can surface runtime sessions as first-class agent activity.
What gets emitted:
- AGENT_STARTED / PHASE_STARTED open a long-lived parent span
and stash it on the sink keyed by (role, phase). An agent span nests under
the open span of its phase, when there is one.
- AGENT_TOOL_CALLED opens a tool span as a child of the active
agent span. AGENT_TOOL_COMPLETED, a tool-scoped AGENT_FAILED event, or a
post-execution guardrail AGENT_BLOCKED event closes that tool span.
- AGENT_TURN_COMPLETED / AGENT_TURN_FAILED emit a chat {model} span
backdated by the turn's measured duration.
- Non-terminal failure events with structured data (for example a
catchable usage-limit overrun or tool failure) are emitted as child
spans and do not close the agent parent.
- AGENT_COMPLETED / AGENT_FAILED / PHASE_COMPLETED end the
parent span, copying the terminal event's attributes onto it. Failure classes
map to error.type and Status(StatusCode.ERROR, ...) except
caller-driven cancellations, which remain typed but are not marked as errors.
OpenTelemetrySink
dataclass
¶
OpenTelemetrySink(
tracer=None,
provider_name=DEFAULT_PROVIDER_NAME,
agent_id=None,
include_event_detail=False,
)
EventSink that mirrors AgentEvents into nested telemetry spans.
Span names follow semantic operation naming.
AGENT_STARTED / PHASE_STARTED open a long-lived parent span
keyed by (role, phase); subsequent events emit as children of
that parent until AGENT_COMPLETED / AGENT_FAILED /
PHASE_COMPLETED end it.
Pass an explicit tracer to avoid pulling the global tracer
(useful for tests with an in-memory exporter).
shutdown ¶
shutdown()
End every span still open, marking it abrupt_termination.
Call this from a SIGTERM handler or before shutting down the
TracerProvider; atexit alone covers neither case. Idempotent, and
the sink stays usable afterwards.
OpenTelemetryUsageSink
dataclass
¶
OpenTelemetryUsageSink(
meter=None,
provider_name=DEFAULT_PROVIDER_NAME,
emit_legacy_token_metric=True,
)
UsageSink that records GenAI client metrics.
Emits:
- gen_ai.client.inference.usage.input_tokens (including cached tokens),
.output_tokens, .cache_read.input_tokens and
.cache_write.input_tokens counters, as the GenAI conventions define them.
gen_ai.token.modality is always unknown because UsageSnapshot
does not split tokens by modality; the conventions require that value here.
gen_ai.operation.name is always chat, the only inference operation
the session reports.
- gen_ai.client.token.usage histogram with a gen_ai.token.type
discriminator (input / output). The conventions have removed this
metric; it stays on by default so existing dashboards keep working. Set
emit_legacy_token_metric=False once they read the counters.
- techrevati.cost.usd counter (custom — no standard GenAI cost
metric yet).
gen_ai.provider.name is required by the conventions but the runtime does
not know who served a call, so set provider_name to the real provider; the
default marks data as coming from this library instead.
OpenTelemetryMetricsSink
dataclass
¶
OpenTelemetryMetricsSink(
meter=None, provider_name=DEFAULT_PROVIDER_NAME
)
EventSink that records GenAI duration histograms from session events.
Emits gen_ai.client.inference.duration for each model turn and
gen_ai.execute_tool.duration for each tool call, in seconds, with the
conventions' bucket boundaries and error.type on failure. Events without a
usable duration_seconds are ignored. Use it next to
:class:OpenTelemetrySink, for example through FanoutEventSink.
provider_name has the same caveat as on :class:OpenTelemetryUsageSink.