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, with per-tool child spans nested under the agent/phase parent (concurrent calls to the same tool each get their own span via a per-key LIFO stack). - Metrics (
OpenTelemetryUsageSink): agen_ai.client.token.usagehistogram discriminated bygen_ai.token.type(input/output) andgen_ai.request.model, plus atechrevati.cost.usdcounter (no standard GenAI cost metric exists yet). - 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.
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).
- AGENT_TOOL_CALLED opens a tool span as a child of the active
agent span. AGENT_TOOL_COMPLETED or a tool-scoped
AGENT_FAILED event closes that tool span.
- 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).
OpenTelemetryUsageSink
dataclass
¶
OpenTelemetryUsageSink(
meter=None, provider_name=DEFAULT_PROVIDER_NAME
)UsageSink that records GenAI client metrics.
Emits:
- gen_ai.client.token.usage histogram with gen_ai.token.type
discriminator (input / output).
- techrevati.cost.usd counter (custom — no standard GenAI cost
metric yet).