Instrumenting all clients

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

Fetching a stored response with client.responses.retrieve(...) performs no inference, so it is reported as a fetch_response operation rather than as an inference call. Its span carries the fetched response’s identifier, model, status, and finish reasons, but no token usage — those counts belong to the operation that originally generated the response.

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

from opentelemetry.instrumentation.genai.openai 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."},
    ],
)

# Responses API example, fetching a stored response back by its id
created = client.responses.create(
    model="gpt-4o-mini",
    input="Write a short poem on open telemetry.",
    store=True,
)
fetched = client.responses.retrieve(created.id)

# 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, set the environment variable OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT to one of the following values:

• span_only - capture content on span attributes.

• event_only - capture content on event attributes.

• span_and_event - capture content on both span and event attributes.

• no_content - do not capture content (the default).

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

The latest experimental GenAI semantic conventions are used unconditionally; there is no environment variable to opt in or out.

Uninstrument

To uninstrument clients, call the uninstrument method:

from opentelemetry.instrumentation.genai.openai import OpenAIInstrumentor

OpenAIInstrumentor().instrument()
# ...

# Uninstrument all clients
OpenAIInstrumentor().uninstrument()