This library allows tracing LLM requests and logging of messages made by the OpenAI Python API library. It also captures the duration of the operations and the number of tokens used as metrics, and for streaming chat completions the time to the first chunk and the time between output chunks.
Note
This package continues the project previously published as
opentelemetry-instrumentation-openai-v2
Many LLM platforms support the OpenAI SDK. This means systems such as the following are observable with this instrumentation when accessed using it:
| Name | gen_ai.system |
|---|---|
| Azure OpenAI | azure.ai.openai |
| Gemini | gemini |
| Perplexity | perplexity |
| xAI (Compatible with Anthropic) | xai |
| DeepSeek | deepseek |
| Groq | groq |
| MistralAI | mistral_ai |
If your application is already instrumented with OpenTelemetry, add this package to your requirements.
pip install opentelemetry-instrumentation-genai-openai
If you don't have an OpenAI application, yet, try our examples which only need a valid OpenAI API key.
Check out zero-code example for a quick start.
This section describes how to set up OpenAI instrumentation if you're setting OpenTelemetry up manually. Check out the manual example for more details.
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"
)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).
To enable the built-in upload hook, set:
OTEL_INSTRUMENTATION_GENAI_COMPLETION_HOOK=uploadOTEL_INSTRUMENTATION_GENAI_UPLOAD_BASE_PATHto anfsspec-compatible URI/path (e.g./path/to/promptsorgs://my_bucket).
Install the upload extra to pull in fsspec:
pip install opentelemetry-util-genai[upload]
See the opentelemetry-util-genai for additional options.
The latest experimental GenAI semantic conventions are used unconditionally; there is no environment variable to opt in or out.
Note
Generative AI semantic conventions are still evolving. The latest experimental features may introduce breaking changes in future releases.
To uninstrument clients, call the uninstrument method:
from opentelemetry.instrumentation.genai.openai import OpenAIInstrumentor
OpenAIInstrumentor().instrument()
# ...
# Uninstrument all clients
OpenAIInstrumentor().uninstrument()