Registry / llm-agents / opentelemetry-instrumentation-openai-v2

opentelemetry-instrumentation-openai-v2

JSON →
library2.4b0pypypi✓ verified 21d ago

This library provides official OpenTelemetry instrumentation for the OpenAI Python API library (version 1.0.0 and above). It enables automatic tracing of LLM requests, capturing model name, token usage, finish reason, duration, and errors without modifying existing OpenAI client code. It also supports logging of messages and metrics, and is maintained as part of the OpenTelemetry Python Contrib project.

pip install opentelemetry-instrumentation-openai-v2 opentelemetry-sdk openai
INSTALL
IMPORT
SIG · OPENTELEMETRY-INST
O
opentelemetry-instrumentation-openai-v2
llm-agentspythonv2.4b0
Install
6.4s avg
Import
2635ms
Disk
58MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v2.4b0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.540s · 59MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 6.4s · import 0.514s · 58MB
58MB installed
● package 58MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

OpenAIInstrumentor
from opentelemetry.instrumentation.openai_v2 import OpenAIInstrumentor
from opentelemetry.instrumentation.openai import OpenAIInstrumentor
The `_v2` suffix is crucial. `opentelemetry.instrumentation.openai` refers to an older, community-maintained instrumentation that does not support the OpenAI Python SDK v1.x API.

This quickstart demonstrates how to set up OpenTelemetry with the OpenAI instrumentation. It initializes a `TracerProvider` with a `ConsoleSpanExporter` to print traces to the console, then calls `OpenAIInstrumentor().instrument()` to automatically trace interactions with the OpenAI Python client (v1.0.0+). An example OpenAI chat completion call is included.

import os from opentelemetry import trace from opentelemetry.sdk.resources import Resource from opentelemetry.sdk.trace import TracerProvider from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor from opentelemetry.instrumentation.openai_v2 import OpenAIInstrumentor from openai import OpenAI # Configure OpenTelemetry Tracer Provider def setup_and_instrument_otel(): resource = Resource.create({"service.name": "my-openai-app"}) provider = TracerProvider(resource=resource) processor = SimpleSpanProcessor(ConsoleSpanExporter()) provider.add_span_processor(processor) trace.set_tracer_provider(provider) # Instrument OpenAI OpenAIInstrumentor().instrument() print("OpenTelemetry and OpenAI instrumentation initialized.") if __name__ == "__main__": # Set OpenAI API key from environment variable os.environ['OPENAI_API_KEY'] = os.environ.get('OPENAI_API_KEY', 'sk-YOUR_OPENAI_API_KEY') if not os.environ['OPENAI_API_KEY'] or os.environ['OPENAI_API_KEY'] == 'sk-YOUR_OPENAI_API_KEY': print("Please set the OPENAI_API_KEY environment variable.") exit(1) setup_and_instrument_otel() client = OpenAI() try: print("\nMaking an OpenAI chat completion call...") chat_completion = client.chat.completions.create( model="gpt-3.5-turbo", messages=[ {"role": "user", "content": "Tell me a short story about OpenTelemetry."} ] ) print("OpenAI call successful. Check console for traces.") # print(chat_completion.choices[0].message.content) except Exception as e: print(f"An error occurred during OpenAI call: {e}") # To see traces, you'd typically export to a collector, e.g., Jaeger, instead of ConsoleSpanExporter. # This example prints to console to show basic functionality.
opentelemetry-instrument --version
Debug
Known issues
breakingThis instrumentation (`opentelemetry-instrumentation-openai-v2`) is designed for the OpenAI Python SDK v1.0.0 and above. The OpenAI SDK v1.0.0 introduced extensive breaking changes, including a complete rewrite of the client API. Users migrating from older OpenAI SDK versions (pre-1.0.0) or older OpenTelemetry OpenAI instrumentations must update their code and use this `-v2` package.
fix
Ensure your `openai` package is `openai>=1.0.0`. Use `pip install opentelemetry-instrumentation-openai-v2` and import `OpenAIInstrumentor` from `opentelemetry.instrumentation.openai_v2`. Refer to OpenAI's official v1 migration guide for SDK changes.
affects: < 2.0.0
gotchaThe package is in beta (`b0`) status, which indicates that API stability is not guaranteed and breaking changes may occur in minor versions without notice. Furthermore, semantic convention updates (e.g., to 1.30.0 as noted in `2.3b0` release) can change attribute names used in telemetry.
fix
Monitor release notes for breaking changes, especially when upgrading between minor beta versions. Configure your OpenTelemetry collector or backend to handle potential changes in attribute names by using schema URL transformations if available, or by adjusting dashboards/alerts.
affects: >= 2.0.0b0
gotchaMessage content, such as prompts, completions, and function arguments/return values, is not captured by default due to privacy and data sensitivity concerns.
fix
To enable content capture for logs, set the environment variable `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` to `true`. Be aware of the implications for sensitive data.
affects: All versions
gotchaEarly beta versions (including `2.3b0`) included fixes for `AttributeError` when handling `LegacyAPIResponse` (from `with_raw_response`) and crashes with streaming `with_raw_response`. This indicates that using less common or raw response patterns with the OpenAI client might have previously led to instrumentation errors.
fix
Ensure you are using the latest available `opentelemetry-instrumentation-openai-v2` version. Test thoroughly if using `with_raw_response` or streaming functionalities, especially if encountering `AttributeError`.
affects: <= 2.3b0
Upgrade
Version history
2.4b0latest on PyPI · released May 1, 2026
Audit
Dependencies
openairequiredThis instrumentation specifically targets OpenAI Python SDK version 1.0.0 and above, which introduced significant API changes.
opentelemetry-sdkrequiredCore OpenTelemetry SDK for tracing and metrics.
opentelemetry-apirequiredCore OpenTelemetry API for common interfaces.
opentelemetry-semantic-conventionsrequiredProvides standard semantic attributes for telemetry data.
opentelemetry-util-genairequiredUtility library for Generative AI related OpenTelemetry instrumentations.
Agent activity
35 hits · last 30 days
node
30
Amazon
1
OpenAI (training)
1
Resources
opentelemetry-instrumentation-openai-v2 — pip install opentelemetry-instrumentation-openai-v2 · libregistry