Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

OpenTelemetry OpenAI Instrumentation

pypi

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.

Many LLM platforms support the OpenAI SDK. This means systems such as the following are observable with this instrumentation when accessed using it:

OpenAI Compatible Platforms

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

Installation

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.

Usage

This section describes how to set up OpenAI instrumentation if you’re setting OpenTelemetry up manually. Check out the manual example for more details.

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()

References

Metadata

Release files for opentelemetry-instrumentation-genai-openai 1.3b0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for opentelemetry-instrumentation-genai-openai 1.3b0
File Size Uploaded Provenance Actions
opentelemetry_instrumentation_genai_openai-1.3b0.tar.gz 361.3 kB With provenance Details for opentelemetry_instrumentation_genai_openai-1.3b0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for opentelemetry-instrumentation-genai-openai 1.3b0
File Interpreter ABI Platform Actions
opentelemetry_instrumentation_genai_openai-1.3b0-py3-none-any.whl Python 3 none any Details for opentelemetry_instrumentation_genai_openai-1.3b0-py3-none-any.whl

Total release size: 400.6 kB

Release files / opentelemetry_instrumentation_genai_openai-1.3b0.tar.gz

Download URL opentelemetry_instrumentation_genai_openai-1.3b0.tar.gz
Size 361.3 kB
Tags Source
SHA-256 checksum
How to use checksums
84c9f05227d213eeaeced4fac9630ffc908956195e73ada853a34883dfc4961f
BLAKE2b-256 checksum
How to use checksums
c00de57f64e81c605862cfb608c6a16d6617444504eed2e07645d361190a4193
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 23, 2026.

Transparency log

Release files / opentelemetry_instrumentation_genai_openai-1.3b0-py3-none-any.whl

Download URL opentelemetry_instrumentation_genai_openai-1.3b0-py3-none-any.whl
Size 39.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c9d5745a278aacde6745b253272dc56f478942a9062d647cae000e099903d301
BLAKE2b-256 checksum
How to use checksums
99ca50f9efc4fe93addfd384e96041379c652a6d9a293804082229ae198520fc
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 23, 2026.

Transparency log

Security for opentelemetry-instrumentation-genai-openai 1.3b0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for opentelemetry_instrumentation_genai_openai-1.3b0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 23, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page