{"id":5676,"library":"opentelemetry-util-genai","title":"OpenTelemetry GenAI Utilities","description":"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.","status":"active","version":"0.3b0","language":"en","source_language":"en","source_url":"https://github.com/open-telemetry/opentelemetry-python-contrib","tags":["opentelemetry","observability","genai","ai","llm","tracing","metrics","events","semantic conventions"],"install":[{"cmd":"pip install opentelemetry-util-genai","lang":"bash","label":"Install `opentelemetry-util-genai`"}],"dependencies":[{"reason":"Core OpenTelemetry API for tracing and metrics.","package":"opentelemetry-api","optional":false},{"reason":"Base package for OpenTelemetry instrumentation.","package":"opentelemetry-instrumentation","optional":false},{"reason":"Defines standard attribute names and values for various domains, including GenAI.","package":"opentelemetry-semantic-conventions","optional":false},{"reason":"Optional dependency, likely for blob/file system operations related to GenAI content capture.","package":"fsspec","optional":true}],"imports":[],"quickstart":{"code":"import os\n\n# Enable experimental GenAI semantic conventions\nos.environ['OTEL_SEMCONV_STABILITY_OPT_IN'] = 'gen_ai_latest_experimental'\n\n# Configure message content capture for spans and events\nos.environ['OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT'] = 'SPAN_AND_EVENT'\n\n# Explicitly enable event emission (optional, defaults based on CAPTURE_MESSAGE_CONTENT)\nos.environ['OTEL_INSTRUMENTATION_GENAI_EMIT_EVENT'] = 'true'\n\n# Example of a basic OpenTelemetry setup (from opentelemetry-sdk, not util-genai itself)\nfrom opentelemetry import trace\nfrom opentelemetry.sdk.resources import Resource\nfrom opentelemetry.sdk.trace import TracerProvider\nfrom opentelemetry.sdk.trace.export import BatchSpanProcessor\nfrom opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter\n\n# Service name is required for most backends\nresource = Resource.create({\"service.name\": \"my-genai-app\"})\n\nprovider = TracerProvider(resource=resource)\nprocessor = BatchSpanProcessor(OTLPSpanExporter())\nprovider.add_span_processor(processor)\ntrace.set_tracer_provider(provider)\n\ntracer = trace.get_tracer(__name__)\n\nprint(\"OpenTelemetry GenAI environment variables configured and basic tracer initialized.\")\nprint(\"Further GenAI specific instrumentation would be provided by specialized libraries (e.g., opentelemetry-instrumentation-openai).\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Refer to the latest official documentation and release notes for breaking changes before upgrading. Regularly test applications after updates.","message":"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.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Set `os.environ['OTEL_SEMCONV_STABILITY_OPT_IN'] = 'gen_ai_latest_experimental'` at the start of your application.","message":"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`.","severity":"gotcha","affected_versions":"<1.0.0"},{"fix":"Set `os.environ['OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT']` to `SPAN_ONLY`, `EVENT_ONLY`, or `SPAN_AND_EVENT` depending on your requirements.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Explicitly set `os.environ['OTEL_INSTRUMENTATION_GENAI_EMIT_EVENT'] = 'true'` (or `'false'`) if you need to override the default event emission behavior.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}