opentelemetry-instrumentation-openai-v2 2.4b0

Instrumenting all clients

When using the instrumentor, all clients will automatically trace OpenAI operations including chat completions and embeddings. You can also optionally capture prompts and completions as log events.

Make sure to configure OpenTelemetry tracing, logging, and events to capture all telemetry emitted by the instrumentation.

from opentelemetry.instrumentation.openai_v2 import OpenAIInstrumentor

OpenAIInstrumentor().instrument()

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

# Embeddings example
embedding_response = client.embeddings.create(
    model="text-embedding-3-small",
    input="Generate vector embeddings for this text"
)

Enabling message content

Message content such as the contents of the prompt, completion, function arguments and return values are not captured by default. To capture message content as log events, set the environment variable OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT to one of the following values:

• true - Legacy. Used to enable content capturing on gen_ai.{role}.message and gen_ai.choice events when latest experimental features are not enabled.

• span_only - Used to enable content capturing on span attributes when latest experimental features are enabled.

• event_only - Used to enable content capturing on event attributes when latest experimental features are enabled.

• span_and_event - Used to enable content capturing on both span and event attributes when latest experimental features are enabled.

Uploading prompts and completions

To enable the built-in upload hook, set:

• OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK=upload

• OTEL_INSTRUMENTATION_GENAI_UPLOAD_BASE_PATH to an fsspec-compatible URI/path (e.g. /path/to/prompts or gs://my_bucket).

Install the upload extra to pull in fsspec:

pip install opentelemetry-util-genai[upload]

See the opentelemetry-util-genai for additional options.

Enabling the latest experimental features

To enable the latest experimental features, set the environment variable OTEL_SEMCONV_STABILITY_OPT_IN to gen_ai_latest_experimental. Or, if you use OTEL_SEMCONV_STABILITY_OPT_IN to enable other features, append ,gen_ai_latest_experimental to its value.

Without this setting, OpenAI instrumentation aligns with Semantic Conventions v1.30.0 and would not capture additional details introduced in later versions.

Uninstrument

To uninstrument clients, call the uninstrument method:

from opentelemetry.instrumentation.openai_v2 import OpenAIInstrumentor

OpenAIInstrumentor().instrument()
# ...

# Uninstrument all clients
OpenAIInstrumentor().uninstrument()