OpenTelemetry GenAI Utilities

0.3b0 · active · verified Mon Apr 13

The `opentelemetry-util-genai` package provides boilerplate and helper functions to standardize instrumentation for Generative AI applications within the OpenTelemetry Python ecosystem. It aims to minimize the effort required to instrument GenAI libraries by offering standardized approaches for generating spans, metrics, and events. The library is currently in a beta development stage (v0.3b0) and is part of the larger `opentelemetry-python-contrib` project, with ongoing updates and a focus on evolving semantic conventions.

Warnings

breaking The library is in beta (0.x.x) and still under active development. APIs and semantic conventions may change in future versions without backward compatibility guarantees.
Fix: Refer to the latest official documentation and release notes for breaking changes before upgrading. Regularly test applications after updates.
gotcha GenAI semantic conventions are currently experimental and require explicit opt-in. To use the latest experimental GenAI conventions, the environment variable `OTEL_SEMCONV_STABILITY_OPT_IN` must be set to `gen_ai_latest_experimental`.
Fix: Set `os.environ['OTEL_SEMCONV_STABILITY_OPT_IN'] = 'gen_ai_latest_experimental'` at the start of your application.
gotcha By default, GenAI message content (prompts, responses) is *not* captured for privacy and PII reasons. To enable capturing this content, you must explicitly set the `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` environment variable.
Fix: Set `os.environ['OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT']` to `SPAN_ONLY`, `EVENT_ONLY`, or `SPAN_AND_EVENT` depending on your requirements.
gotcha Emission of `gen_ai.client.inference.operation.details` events is controlled by the `OTEL_INSTRUMENTATION_GENAI_EMIT_EVENT` environment variable. Its default behavior depends on the `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` setting, so explicit configuration might be needed.
Fix: Explicitly set `os.environ['OTEL_INSTRUMENTATION_GENAI_EMIT_EVENT'] = 'true'` (or `'false'`) if you need to override the default event emission behavior.

Install

pip install opentelemetry-util-genai Install `opentelemetry-util-genai`

Quickstart

This quickstart demonstrates how to configure the essential environment variables that control the behavior of `opentelemetry-util-genai` when used by other OpenTelemetry GenAI instrumentation libraries. It also includes a basic OpenTelemetry tracer setup, which is a prerequisite for any instrumentation. This package primarily provides internal utilities and relies on these environment variables for user-facing configuration, rather than direct API calls for typical end-user instrumentation.

import os

# Enable experimental GenAI semantic conventions
os.environ['OTEL_SEMCONV_STABILITY_OPT_IN'] = 'gen_ai_latest_experimental'

# Configure message content capture for spans and events
os.environ['OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT'] = 'SPAN_AND_EVENT'

# Explicitly enable event emission (optional, defaults based on CAPTURE_MESSAGE_CONTENT)
os.environ['OTEL_INSTRUMENTATION_GENAI_EMIT_EVENT'] = 'true'

# Example of a basic OpenTelemetry setup (from opentelemetry-sdk, not util-genai itself)
from opentelemetry import trace
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter

# Service name is required for most backends
resource = Resource.create({"service.name": "my-genai-app"})

provider = TracerProvider(resource=resource)
processor = BatchSpanProcessor(OTLPSpanExporter())
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)

tracer = trace.get_tracer(__name__)

print("OpenTelemetry GenAI environment variables configured and basic tracer initialized.")
print("Further GenAI specific instrumentation would be provided by specialized libraries (e.g., opentelemetry-instrumentation-openai).")

view raw JSON →