genkit-otel

OpenTelemetry instrumentation and backend for Genkit.

It provides GenAiInstrumentation: OpenTelemetry GenAI semantic-conventions instrumentation emitting gen_ai.* spans and metrics.

Pass tracer to mint on that tracer instead of the process-global one.

GenAI Semantic Conventions Instrumentation

Plugs into Genkit's pluggable instrumentation system and emits telemetry that follows the OTel GenAI semantic conventions:

• gen_ai.* client spans for model operations (chat <model>), with request config, token usage, and finish reasons.
• The GenAI client metrics gen_ai.client.token.usage (split by gen_ai.token.type) and gen_ai.client.operation.duration.
• Optional message-content capture, either as span attributes or a dedicated gen_ai.client.inference.operation.details event.
• Optional execute_tool spans, and generic spans for other Genkit action types so the trace tree stays connected.

Usage

The application owns the OpenTelemetry SDK and picks its exporter. Install them alongside this package:

pip install genkit-otel opentelemetry-sdk opentelemetry-exporter-otlp

Initialize the SDK, then register the provider before creating Genkit:

from opentelemetry import trace
from opentelemetry.sdk.resources import SERVICE_NAME, Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter

from genkit import Genkit
from genkit.telemetry import configure_instrumentation
from genkit_otel import GenAiInstrumentation

resource = Resource.create({SERVICE_NAME: 'my-service'})
provider = TracerProvider(resource=resource)
provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
trace.set_tracer_provider(provider)

configure_instrumentation(GenAiInstrumentation())

ai = Genkit()

When the SDK is not initialized, the provider is effectively a no-op.

Content capture (PII)

Prompt and response content may contain PII, so capture is off by default. content_capturing_mode is one of the spec tokens:

from genkit_otel import GenAiInstrumentation

GenAiInstrumentation(content_capturing_mode='SPAN_ONLY')

Or omit the token and set the env. Same four tokens. Same result:

export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=SPAN_ONLY

GenAiInstrumentation()

A token on the constructor wins over the env var, including an explicit NO_CONTENT. Garbage in the env var warns and stays NO_CONTENT.

To annotate a config field or variable, import the type:

from genkit_otel import ContentCapturingMode

mode: ContentCapturingMode = 'SPAN_ONLY'

EVENT_ONLY emits content on the OpenTelemetry logs signal (a gen_ai.client.inference.operation.details log record), not on the span. Trace-only backends like Jaeger cannot display it (its GenAI tab reads span attributes; its "Trace Logs" tab reads span events, neither is the logs signal). Use SPAN_ONLY or SPAN_AND_EVENT for Jaeger, or a logs backend (e.g. Loki, Elasticsearch/OpenSearch) for EVENT_ONLY.

Options

Example

See samples/otel-jaeger for a runnable sample that exports traces to Jaeger and metrics to a local collector. ./tool/telemetry.sh downloads Jaeger and otelcol-contrib and keeps them running.