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:

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:

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.