Registry / observability / opentelemetry-util-genai

opentelemetry-util-genai

library0.3b0pypypiunverified

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.

observability llm-agents ai-ml

pip install opentelemetry-util-genai

github ↗package ↗

INSTALL

IMPORT

SIG · OPENTELEMETRY-UTIL

opentelemetry-util-genai

observabilitypythonv0.3b0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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).")

Debug

Known issues

breakingThe 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.

affects: <1.0.0

gotchaGenAI 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.

affects: <1.0.0

gotchaBy 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.

affects: All versions

gotchaEmission 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.

affects: All versions

Errors

Common errors & fixes

ImportError: cannot import name 'ExtendedTelemetryHandler' from 'opentelemetry.util.genai'

This error typically occurs when a dependent library (like `loongsuite-instrumentation-agentscope`) expects extended features or newer, unreleased classes from `opentelemetry-util-genai` that are not present in the installed PyPI version (0.3b0).

fix

Ensure all `opentelemetry` related packages are up-to-date. If using a library that requires experimental or unreleased features, you might need to install a specific development version or a version directly from the source repository if available, or check for compatibility notes from the dependent library. For standard use, `pip install opentelemetry-util-genai` should provide the official release. If the dependent library requires a custom extension, its documentation should specify how to install that extended version.

TypeError: Object of type Part is not JSON serializable

This error happens when attempting to serialize complex objects, specifically `google.genai.types.Part` objects, into JSON for OpenTelemetry attributes or events, which strictly require primitive types or sequences of primitives.

fix

Before setting `gen_ai` attributes or events, ensure that complex objects like `Part` are properly converted into a JSON string (e.g., using `json.dumps()`) or their relevant primitive attributes are extracted. For example, to capture the content of a `Part` object, you might extract `part.text` or `part.inline_data` as a string. The library should ideally handle this serialization internally, so an update to `opentelemetry-instrumentation-google-genai` might also resolve it.

Invalid type dict in attribute 'gen_ai.prompt' value sequence. Expected one of ['bool', 'str', 'bytes', 'int', 'float'] or None.

This warning/error indicates that a dictionary or a list of dictionaries (like a raw messages payload `[{"role": "user", "content": "..."}]`) is being directly assigned to an OpenTelemetry span attribute (e.g., `gen_ai.prompt`), which expects primitive types or sequences of primitives, not nested dictionaries.

fix

Convert the complex message payload into a JSON string using `json.dumps()` before setting it as a span attribute, or extract and flatten relevant primitive parts of the messages into separate attributes following OpenTelemetry's GenAI semantic conventions.

ModuleNotFoundError: No module named 'opentelemetry.util.genai'

This error means that the `opentelemetry-util-genai` package or one of its necessary components cannot be found in the Python environment, usually due to incomplete installation, an incorrect virtual environment, or a typo in the import statement.

fix

Ensure the package is correctly installed using pip: `pip install opentelemetry-util-genai`. Verify that you are running your code in the same Python environment where the package was installed. If using other OpenTelemetry components, it's often recommended to install `opentelemetry-distro` and run `opentelemetry-bootstrap -a install` for a consistent setup.

Upgrade

Version history

0.3b0latest on PyPI · released Feb 20, 2026

Audit

Dependencies

opentelemetry-apirequiredCore OpenTelemetry API for tracing and metrics.

opentelemetry-instrumentationrequiredBase package for OpenTelemetry instrumentation.

opentelemetry-semantic-conventionsrequiredDefines standard attribute names and values for various domains, including GenAI.

fsspecoptionalOptional dependency, likely for blob/file system operations related to GenAI content capture.

Agent activity

29 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/open-telemetry/opentelemetry-python-contrib ↗

packagehttps://pypi.org/project/opentelemetry-util-genai/ ↗