OpenTelemetry Integration

Requires pip install 'techrevati-runtime[otel]'.

techrevati.runtime.otel

OpenTelemetry integration — GenAI semantic-conventions-aligned sink.

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 OpenTelemetry GenAI semantic conventions attributes (https://opentelemetry.io/docs/specs/semconv/gen-ai/) so any GenAI-aware APM ingest (the same one consuming OpenAI Agents SDK telemetry) will surface our runtime as a first-class agent.

What gets emitted in 0.2.0 (v2 — agent-level nesting): - AGENT_STARTED / PHASE_STARTED open a long-lived parent span and stash it on the sink keyed by (role, phase). - All other events emit one-shot spans as children of the matching open parent (if any) via OTel context propagation, so a typical session produces a invoke_agent root with execute_tool / recovery siblings nested under it. - AGENT_COMPLETED / AGENT_FAILED / PHASE_COMPLETED end the parent span, copying the terminal event's attributes onto it (incl. error.type and a Status(StatusCode.ERROR, ...) on failure).

Full tool-call-level nesting (invoke_agent > invoke_agent per turn > execute_tool per tool) is still a 0.3.0 item; today every non-parent event is a leaf under the agent span.

OpenTelemetrySink dataclass

OpenTelemetrySink(tracer=None, provider_name=DEFAULT_PROVIDER_NAME, agent_id=None)

EventSink that mirrors AgentEvents into nested OTel spans.

Span names follow GenAI operation naming (https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-agent-spans/). 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).