OpenTelemetry GenAI semantic conventions

The OpenTelemetry GenAI semantic conventions are a vendor-neutral vocabulary for model telemetry: what a span for a model call is named, which attributes carry the model and provider, and which metrics report token usage and latency. Genkit can emit telemetry in that shape, so any backend that speaks OTLP receives data it already understands, with no Genkit-specific mapping on your side.

This is separate from the Developer UI pipeline. The Developer UI is fed by a built-in provider that posts spans straight to the Genkit telemetry server; see Local observability and metrics for that workflow. The two compose, so you can keep the Developer UI while also exporting OTLP.

What gets emitted

The conventions are defined by the spec, so the shape below is the same wherever Genkit implements them.

Model spans. One client span per model call, named chat <model>, carrying:

Attribute	Notes
gen_ai.operation.name	chat
gen_ai.provider.name	Derived from the plugin, for example gcp.gemini, gcp.vertex_ai, openai, anthropic. Unknown plugins pass through lowercased.
gen_ai.request.model	The model name, without the plugin prefix.
gen_ai.request.*	Request config that was actually set: temperature, top_p, top_k, max_tokens, stop_sequences, frequency_penalty, presence_penalty, seed, choice.count.
gen_ai.output.type	json or text, when an output format was requested.
gen_ai.usage.input_tokens, gen_ai.usage.output_tokens	Token counts from the response. Reasoning and cached tokens land in gen_ai.usage.reasoning.output_tokens and gen_ai.usage.cache_read.input_tokens when the model reports them.
gen_ai.response.finish_reasons	Mapped to spec values. A turn that ends in tool calls reports tool_calls.
error.type	On failure. The exception is recorded on the span and rethrown unchanged.

Metrics. The two spec-defined client metrics:

• gen_ai.client.token.usage, a histogram of token counts split by gen_ai.token.type (input or output).
• gen_ai.client.operation.duration, in seconds, recorded for successful and failed calls alike. Failures carry error.type.

Both are tagged only with operation name, model, and provider, so cardinality stays low.

Everything else in the trace. Tool calls can be emitted as execute_tool spans, and every other Genkit action type gets a generic span named after the action, so the trace tree stays connected rather than showing model calls as orphans. Generic spans carry genkit.action.type, kept outside the reserved gen_ai.* namespace so GenAI-aware backends do not try to render Genkit payloads as spec content. Telemetry labels become span attributes, and attributes set with span.setAttribute on the span passed to a runInNewSpan callback are written as genkit:metadata:<key>. Metadata set with setCustomMetadataAttribute is not recorded on these spans.

In JavaScript, error.type is the thrown error’s name, for example GenkitError or Error, not its status.

Setup

The instrumentation lives in the @genkit-ai/otel package:

npm i @genkit-ai/otel @opentelemetry/sdk-node

Your application owns the OpenTelemetry SDK. Start it, register the GenAI instrumentation with configureInstrumentation, then create Genkit:

import { googleAI } from '@genkit-ai/google-genai';
import { GenAiInstrumentation } from '@genkit-ai/otel';
import { NodeSDK } from '@opentelemetry/sdk-node';
import { genkit } from 'genkit';
import { configureInstrumentation } from 'genkit/tracing';

// With no arguments, NodeSDK configures traces, metrics, and logs from the
// standard OTEL_* env vars, defaulting to OTLP http/protobuf on localhost:4318.
const sdk = new NodeSDK();
sdk.start();

configureInstrumentation(new GenAiInstrumentation({ emitToolSpans: true }));

const ai = genkit({ plugins: [googleAI()] });

const { text } = await ai.generate({
  model: googleAI.model('gemini-flash-latest'),
  prompt: 'Explain OpenTelemetry in one sentence.',
});
console.log(text);

await sdk.shutdown(); // Flushes spans, metrics, and logs.

Point it at a collector with the usual environment variables, no code change:

export OTEL_SERVICE_NAME=my-service
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

Some properties to know before you deploy:

• It replaces the default encoding. configureInstrumentation replaces Genkit’s default OpenTelemetry provider, which writes the genkit:* attributes.
• The Developer UI keeps working. Under genkit start, the Developer UI’s own provider runs first, whatever you configure, so it keeps showing Genkit’s traces next to this export.
• Without an SDK, it does nothing. When no OpenTelemetry SDK is registered, @opentelemetry/api returns non-recording spans and no-op instruments, so the instrumentation can stay wired up in builds that do not export. The first span logs one warning that nothing is exported.

Do not combine with the Firebase or Google Cloud telemetry plugins

enableFirebaseTelemetry() and enableGoogleCloudTelemetry() build their metrics and logs from the genkit:* attributes that this instrumentation replaces, so their Genkit metrics and logs stop, without an error. Use one or the other.

Capturing message content

Prompts and responses can contain PII, so content capture is off by default. The mode mirrors the spec’s ContentCapturingMode:

Mode	Where content goes
noContent (default)	Not captured.
spanOnly	Span attributes gen_ai.input.messages, gen_ai.output.messages, and gen_ai.system_instructions, as JSON strings.
eventOnly	A gen_ai.client.inference.operation.details log record.
spanAndEvent	Both.

In JavaScript, the modes are the string values 'NO_CONTENT', 'SPAN_ONLY', 'EVENT_ONLY', and 'SPAN_AND_EVENT':

configureInstrumentation(
  new GenAiInstrumentation({ contentCapturingMode: 'SPAN_ONLY' }), // May contain PII.
);

Left unset, the value comes from the OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT environment variable using the same tokens. An explicit option overrides it, and an unrecognized token logs one warning and falls back to NO_CONTENT. With emitToolSpans, content also covers tool call arguments and results (gen_ai.tool.call.arguments, gen_ai.tool.call.result). Inline data: media longer than 128 characters is replaced with <header>,<omitted N bytes> to stay within attribute size limits.

eventOnly is invisible to trace-only backends

eventOnly writes content to the OpenTelemetry logs signal, not to the span. Jaeger cannot display it: its GenAI tab reads span attributes and its Trace Logs tab reads span events, and neither is the logs signal. Use spanOnly or spanAndEvent for Jaeger, or send logs to a backend such as Loki or OpenSearch.

Options

new GenAiInstrumentation(options) accepts:

Option	Default	What it does
contentCapturingMode	env, else NO_CONTENT	Where spec-shaped gen_ai.* message content is recorded.
captureActionIO	false	Records raw Genkit input and output as genkit.input / genkit.output on every span. A debugging aid, independent of contentCapturingMode. May contain PII.
emitToolSpans	false	execute_tool spans for tool actions.
emitMetrics	true	Emits the token usage and operation duration metrics.
scopeName	genkit-genai	Instrumentation scope for the tracer, meter, and logger.
tracer, meter, logger	the globals	Explicit OpenTelemetry instruments, for when you do not want the global providers.

Try it

The otel sample is a runnable end-to-end setup: traces to Jaeger and metrics to a collector, with a script that downloads and runs both without Docker.