telemetry-dev-openai

OpenAI SDK instrumentation for telemetry.dev. It wraps the official openai Python SDK and emits telemetry.dev generation and embedding spans through telemetry-dev.

Install

pip install telemetry-dev-openai

Initialize the core SDK first:

import telemetry_dev

telemetry_dev.init(
    api_key="td_live_...",
    base_url="http://localhost:4318",
    service_name="my-service",
)

Per-client wrapping

from openai import OpenAI
from telemetry_dev_openai import wrap_openai

client = wrap_openai(OpenAI())

client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Tell me a joke about OpenTelemetry"}],
)

Use this when you want explicit control over which sync or async clients are instrumented.

Global instrumentation

from openai import OpenAI
from telemetry_dev_openai import instrument_openai, uninstrument_openai

instrument_openai()
client = OpenAI()

try:
    client.responses.create(model="gpt-4o-mini", input="Tell me a joke about OpenTelemetry")
finally:
    uninstrument_openai()

Use this as the app-wide one-liner at startup when all OpenAI clients should be instrumented.

Instrumented surfaces

Sync and async variants are covered:

• client.chat.completions.create(...)
• client.chat.completions.parse(...)
• client.chat.completions.stream(...)
• client.responses.create(...)
• client.responses.parse(...)
• client.responses.stream(...) when starting a new response
• client.embeddings.create(...)
• client.images.generate(...), edit(...), and create_variation(...)
• client.audio.speech.create(...), transcriptions.create(...), and translations.create(...)
• client.batches.create(...), retrieve(...), and cancel(...)

The integration maps native OpenAI request/response shapes directly into telemetry.dev fields. It does not normalize messages into another schema.

Streaming

Chat completion streams are traced. Requests are sent unchanged by default, so token usage is only captured when the caller sets stream_options={"include_usage": True} themselves. Pass inject_stream_usage=True to wrap_openai or instrument_openai to inject it automatically; the synthetic usage-only chunk is then hidden from the caller. Injection is opt-in because some providers reject stream_options — for example Azure OpenAI "on your data" (data_sources) returns 400 for it while plain stream=True works.

client = wrap_openai(OpenAI(), inject_stream_usage=True)

Responses API streams are traced through responses.create(stream=True) and responses.stream(response_id=...); terminal response.completed, response.failed, and response.incomplete events close the span.

Embeddings

Embedding calls emit gen_ai.operation.name = "embeddings", request model/input, response model, and token usage. Embedding vectors are intentionally not captured as output.

Provider detection

wrap_openai(AzureOpenAI(...)) and wrap_openai(AsyncAzureOpenAI(...)) record provider azure.ai.openai. Global class instrumentation detects Azure from the resource client when available.

OpenAI clients configured with https://openrouter.ai/api/v1 as their base URL record provider openrouter. The same detection applies to OpenRouter subdomains; unrelated hosts containing openrouter.ai are not matched.

OpenAI-compatible URLs on Groq, xAI, DeepSeek, Together, and Fireworks domains (including their subdomains) record the corresponding provider. Other compatible endpoints retain the openai default.

Limitations

• with_raw_response and with_streaming_response snapshot bound methods on first access in the OpenAI Python SDK. Call wrap_openai() or instrument_openai() before accessing either helper if those methods need instrumentation.
• Unconsumed streams end their spans only when the stream is exhausted, errors, or is closed.
• Binary image and audio bodies are never captured, including binary fields nested in Responses API input and output. Speech download/streaming response spans cover request creation, not later byte consumption. Transcription stream spans remain open through stream consumption and record terminal or bounded partial transcript text and usage.
• Realtime is not wrapped: OpenAI Python 2.x exposes an async WebSocket connection (realtime.connect), not an event emitter with a stable listener lifecycle, so an explicit event-emitter wrapper would be misleading.
• Videos (client.videos) are not instrumented yet; video create and retrieve calls produce no spans. The TypeScript integration traces them.
• Batch list pagination is not instrumented so the SDK's synchronous AsyncPaginator remains directly usable with async for.