OpenTelemetry Python - OpenAI Instrumentation

OpenAI client instrumentation supporting openai, it can be enabled by using OpenAIInstrumentor.

Usage

from openai import OpenAI
from opentelemetry.instrumentation.openai_v2 import OpenAIInstrumentor

OpenAIInstrumentor().instrument()

client = OpenAI()
response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "user", "content": "Write a short poem on open telemetry."},
    ],
)

Configuration

By default, the instrumentation aligns with Semantic Conventions v1.30.0 and does not capture prompt or completion content. Behavior is controlled via environment variables:

  • OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental - opt into the latest GenAI semantic conventions. Required to access the newer attributes and the span_only / event_only / span_and_event content modes. Without this flag, the instrumentation stays on v1.30.0 conventions.

  • OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT - enable capture of prompts, completions, tool arguments, and return values. Set to true on the legacy path, or one of span_only, event_only, span_and_event when experimental conventions are enabled.

  • OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK=upload together with OTEL_INSTRUMENTATION_GENAI_UPLOAD_BASE_PATH=<fsspec-uri> - upload prompts and completions to an fsspec-compatible destination (local filesystem, gs://, s3://, etc.) and record reference URIs as gen_ai.input.messages.ref / gen_ai.output.messages.ref attributes. Inline content is not captured unless OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT is also set.

See the opentelemetry-util-genai README for the full list of GenAI configuration variables.

A custom CompletionHook implementation can also be passed programmatically:

OpenAIInstrumentor().instrument(completion_hook=my_hook)

When provided, this takes precedence over the hook resolved from OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK.

API

class opentelemetry.instrumentation.openai_v2.OpenAIInstrumentor(*args, **kwargs)[source]

Bases: BaseInstrumentor

instrumentation_dependencies()[source]

Return a list of python packages with versions that the will be instrumented.

The format should be the same as used in requirements.txt or pyproject.toml.

For example, if an instrumentation instruments requests 1.x, this method should look like: :rtype: Collection[str]

def instrumentation_dependencies(self) -> Collection[str]:

return [‘requests ~= 1.0’]

This will ensure that the instrumentation will only be used when the specified library is present in the environment.