Registry /
observability / openinference-instrumentation-openai
Install & Compatibility
Where this runs
tested against v0.1.57 · 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
902MB installed
● package 902MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
OpenAIInstrumentor
✓ from openinference.instrumentation.openai import OpenAIInstrumentor
OpenAI Client
✓ import openai
client = openai.OpenAI()
OTLPSpanExporter
✓ from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
TracerProvider
✓ from opentelemetry.sdk import trace as trace_sdk
SimpleSpanProcessor, ConsoleSpanExporter
✓ from opentelemetry.sdk.trace.export import SimpleSpanProcessor, ConsoleSpanExporter
This quickstart demonstrates how to instrument OpenAI API calls using `openinference-instrumentation-openai` and send the resulting traces to an OpenTelemetry collector. It sets up a `TracerProvider` to export traces via HTTP OTLP and then instruments the OpenAI client. You should ensure an OpenTelemetry collector (like Arize Phoenix, running `python -m phoenix.server.main serve`) is running to receive traces. Remember to set your `OPENAI_API_KEY` environment variable.
import os
import openai
from openinference.instrumentation.openai import OpenAIInstrumentor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk import trace as trace_sdk
from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor
# Set your OpenAI API key from environment variables
os.environ['OPENAI_API_KEY'] = os.environ.get('OPENAI_API_KEY', 'sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx')
# Configure OpenTelemetry Tracer Provider to send traces to a collector (e.g., Phoenix)
endpoint = "http://127.0.0.1:6006/v1/traces" # Default Phoenix endpoint
tracer_provider = trace_sdk.TracerProvider()
tracer_provider.add_span_processor(SimpleSpanProcessor(OTLPSpanExporter(endpoint)))
# Optionally, also print spans to the console for debugging
tracer_provider.add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))
# Instrument the OpenAI SDK
OpenAIInstrumentor().instrument(tracer_provider=tracer_provider)
if __name__ == "__main__":
client = openai.OpenAI()
try:
response = client.chat.completions.create(
model="gpt-3.5-turbo",
messages=[{"role": "user", "content": "Write a haiku about observability."}],
max_tokens=20,
stream=False # Set to True and add stream_options={'include_usage': True} for streaming with token counts
)
print("OpenAI API call successful.")
print(f"Response: {response.choices[0].message.content}")
except openai.AuthenticationError:
print("Error: OpenAI API key is missing or invalid. Please set OPENAI_API_KEY.")
except Exception as e:
print(f"An unexpected error occurred: {e}")
Debug
Known issues
gotchaCompatibility with OpenAI SDK versions: The instrumentation might require specific OpenAI SDK versions to correctly handle new output formats or features. For example, `openai>=1.26` is required to capture token counts when using streaming completions with `stream_options={'include_usage': True}`.fixEnsure you are using a compatible `openai` SDK version as specified in the `openinference-instrumentation-openai` documentation or releases. Upgrade both if experiencing unexpected trace data.
affects: <0.1.44 for some features, generally sensitive to OpenAI SDK updates
gotchaOpenTelemetry `suppress_instrumentation` context flag is not fully respected by `openinference-instrumentation-openai`.fixDirectly reading `_SUPPRESS_INSTRUMENTATION_KEY` for span creation, rather than using OpenTelemetry's `is_instrumentation_suppressed()` utility, can lead to spans being created even when suppression is intended. Manual intervention or alternative span filtering might be necessary if strict suppression is required.
affects: All versions up to 0.1.44 (as of Jan 2026)
gotchaIn certain environments like Google Colab, `openinference-instrumentation-openai` might fail to instrument correctly immediately after `pip install`. A session restart or explicit dependency check bypass might be needed.fixAfter `pip install`, restart the Colab runtime. Alternatively, you can try `OpenAIInstrumentor().instrument(skip_dep_check=True)` as a workaround, though it's generally recommended to restart the runtime.
affects: Reported in earlier versions, potentially affects recent ones in similar environments
Upgrade
Version history
0.1.57latest on PyPI · released Aug 28, 2026
Audit
Dependencies
openairequiredRequired to instrument OpenAI API calls. Version `openai>=1.26` is recommended for full functionality, including streaming token counts.
opentelemetry-sdkrequiredCore OpenTelemetry SDK components for creating and processing traces.
opentelemetry-apirequiredOpenTelemetry API for interacting with the tracing system (implicitly installed with opentelemetry-sdk).
opentelemetry-exporter-otlprequiredOpenTelemetry OTLP exporter for sending traces to a collector (e.g., Phoenix).
arize-phoenixoptionalA recommended OpenTelemetry collector and visualization tool for viewing traces, often used in quickstarts.