otelgenai

otelgenai (GenAI instrumentation)

OpenTelemetry GenAI semantic-conventions instrumentation for Genkit Go.

Import path: github.com/firebase/genkit/go/plugins/otelgenai

This plugin maps Genkit actions to the OpenTelemetry GenAI semantic conventions:

• Model actions become chat <model> client spans carrying gen_ai.* attributes (provider, model, request config, response finish reasons, token usage).
• Tool actions can optionally become execute_tool <name> spans.
• Every other Genkit action type becomes a generic span tagged with genkit.action.type so the trace tree stays connected.
• The two spec metrics gen_ai.client.token.usage and gen_ai.client.operation.duration are emitted per model call.

The application owns the OpenTelemetry SDK: configure your TracerProvider / MeterProvider / LoggerProvider before constructing Genkit. When no SDK is configured, go.opentelemetry.io/otel returns non-recording spans and no-op instruments and the provider is inert.

Usage

import (
	"go.opentelemetry.io/otel"
	sdktrace "go.opentelemetry.io/otel/sdk/trace"

	"github.com/firebase/genkit/go/core/tracing"
	"github.com/firebase/genkit/go/genkit"
	"github.com/firebase/genkit/go/plugins/googlegenai"
	"github.com/firebase/genkit/go/plugins/otelgenai"
)

// 1. The app owns the OTel SDK (point the exporter at your OTLP collector).
otel.SetTracerProvider(sdktrace.NewTracerProvider(/* ... */))

// 2. Route Genkit telemetry through the GenAI provider. It composes with the
//    built-in dev instrumentation that feeds the Developer UI.
tracing.SetInstrumentation(otelgenai.New(&otelgenai.Options{
	ContentCapturingMode: otelgenai.SpanOnly, // default NoContent; may contain PII
}))

// 3. Use Genkit as usual.
g := genkit.Init(ctx, genkit.WithPlugins(&googlegenai.GoogleAI{}))

To also keep Genkit's default genkit:* OpenTelemetry spans, list both providers:

tracing.SetInstrumentation(&tracing.OTelInstrumentation{}, otelgenai.New(nil))

The configuration is process-wide on purpose: Genkit actions can run without a Genkit instance (for example a model obtained directly from a plugin), and those calls are instrumented too.

See go/samples/otel-genai for a runnable example that exports over OTLP.

Google Cloud / Firebase telemetry

Do not combine this provider with the googlecloud or firebase telemetry plugins. Configuring it replaces Genkit's default OpenTelemetry encoding (the genkit:* span attributes) that those plugins read, so their Genkit metrics stop, and their input/output redaction does not cover gen_ai.* content attributes.

What gets recorded

• gen_ai.request.* params are read from the request config, whether it is Genkit's GenerationCommonConfig or a provider SDK's native type (camelCase and snake_case names are both recognized). A param set to 0 is recorded.
• A call that fails after the model responded (for example, output schema validation) still records the response: token usage, content, and a gen_ai.response.finish_reasons of error.
• error.type is the Genkit status name, such as INVALID_ARGUMENT or RESOURCE_EXHAUSTED (INTERNAL when unclassified).
• Inline media (data: URIs) is captured as a blob part with its decoded size in size_bytes, never the payload. Remote media becomes a uri part. With CaptureActionIO, inline media in model requests/responses is replaced by a marker such as data:image/png;base64,[1834 bytes omitted].
• In EventOnly / SpanAndEvent modes, the gen_ai.client.inference.operation.details event carries content as structured (map/slice) attributes; span attributes carry it as JSON strings.
• Telemetry labels (tracing.WithTelemetryLabels) are set as span attributes.

Options

otelgenai.Options:

When ContentCapturingMode is left at its zero value, the env var OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT is consulted (spec enum names: NO_CONTENT, SPAN_ONLY, EVENT_ONLY, SPAN_AND_EVENT).