genkit_otel 0.1.0

OpenTelemetry GenAI semantic-conventions instrumentation for Genkit Dart (traces, metrics, and message-content capture).

genkit_otel

OpenTelemetry GenAI semantic-conventions instrumentation for Genkit Dart, built on the dartastic_opentelemetry SDK.

It 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. Initialize it, then register the provider before creating Genkit:

import 'package:dartastic_opentelemetry/dartastic_opentelemetry.dart';
import 'package:genkit/genkit.dart';
import 'package:genkit/telemetry.dart';
import 'package:genkit_otel/genkit_otel.dart';

Future<void> main() async {
  // Reads OTEL_* env vars; defaults to http://localhost:4318.
  await OTel.initialize();

  configureInstrumentation(GenAiInstrumentation());

  final ai = Genkit(/* plugins: [...] */);
  // ...
  await ai.shutdown();
  await OTel.shutdown(); // flushes spans and metrics
}

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

SDK logging

dartastic's internal logger defaults to printing an [ERROR] Tracer: Exception in withSpanAsync ... line for every exception that flows through a span. The exception is still recorded and rethrown; the line is just diagnostic noise. To quiet it, lower the level after OTel.initialize():

OTelLog.currentLevel = LogLevel.fatal; // or set OTEL_LOG_LEVEL=fatal

Content capture (PII)

Prompt and response content may contain PII, so capture is off by default. contentCapturingMode mirrors the OTel GenAI ContentCapturingMode:

Mode	Where content goes
noContent (default)	not captured
spanOnly	span attributes (gen_ai.*.messages) as JSON strings
eventOnly	a gen_ai.client.inference.operation.details log event
spanAndEvent	both

GenAiInstrumentation(
  contentCapturingMode: ContentCapturingMode.spanOnly,
);

When not supplied, the env var OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT is consulted using the spec's UPPER_SNAKE tokens (NO_CONTENT, SPAN_ONLY, EVENT_ONLY, SPAN_AND_EVENT); an explicit value overrides it. An unknown token logs a one-time warning and falls back to NO_CONTENT.

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

Option	Default	Description
contentCapturingMode	env or noContent	Where spec-shaped gen_ai.* message content is recorded (noContent/spanOnly/eventOnly/spanAndEvent).
captureActionIO	false	Capture raw Genkit input/output as genkit.input/genkit.output on every span (debugging / Dev UI).
emitMetrics	true	Emit token-usage and operation-duration metrics.
emitToolSpans	false	Emit execute_tool spans for tool actions.
scopeName	genkit-genai	Instrumentation scope for tracer/meter/logger.
tracer / meter	resolved lazily	Escape hatches to inject explicit instances.

Example

See testapps/otel_jaeger for a runnable sample that exports traces to Jaeger and metrics to a local collector, with a Docker-free script that downloads and runs both.