Metadata-Version: 2.4
Name: traceAI-openai
Version: 0.1.15
Summary: OpenTelemetry instrumentation for OpenAI
License: Apache-2.0
Keywords: traceai,futureagi,opentelemetry,tracing,observability,llm,openai
Author: Future AGI
Author-email: no-reply@futureagi.com
Requires-Python: >=3.10,<3.14
Classifier: Framework :: OpenTelemetry
Classifier: Framework :: OpenTelemetry :: Instrumentations
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Requires-Dist: fi-instrumentation-otel (>=1.2.3)
Requires-Dist: openai (>=1.69.0)
Project-URL: Changelog, https://github.com/future-agi/traceAI/blob/dev/python/frameworks/openai/CHANGELOG.md
Project-URL: Documentation, https://docs.futureagi.com/docs/integrations/traceai/openai
Project-URL: Homepage, https://futureagi.com
Project-URL: Issues, https://github.com/future-agi/traceAI/issues
Project-URL: Repository, https://github.com/future-agi/traceAI/tree/dev/python/frameworks/openai
Description-Content-Type: text/markdown

# OpenAI OpenTelemetry Integration

## Overview
This integration provides support for using OpenTelemetry with the OpenAI framework. It enables tracing and monitoring of applications built with OpenAI.

## Installation

1. **Install traceAI OpenAI**

```bash
pip install traceAI-openai
```


### Set environment variables
Set the Future AGI keys for tracing and the OpenAI key for the Quickstart request:

```bash
export FI_API_KEY="your-future-agi-api-key"
export FI_SECRET_KEY="your-future-agi-secret-key"
export OPENAI_API_KEY="your-openai-api-key"
```

## Ollama and self-hosted OpenAI-compatible clients

Keep using this package when your application calls Ollama through the OpenAI
SDK. The official `https://ollama.com/v1` endpoint is attributed to `ollama`
automatically. A local address can host many providers, so set the provider
explicitly for each local or self-hosted client:

```python
from openai import OpenAI
from traceai_openai import OpenAIInstrumentor, set_client_provider

# Use the trace provider configured in the quickstart below.
OpenAIInstrumentor().instrument(tracer_provider=trace_provider)

client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")
set_client_provider(client, provider="ollama")
```

The override controls `gen_ai.provider.name` on sync and async requests,
including streams, embeddings, Responses and failures. It changes tracing
metadata only; it adds no spans and sends no provider setting to the server.
Use a lowercase provider identifier (1–64 characters, starting with a letter;
letters, digits, `.`, `_` and `-` are accepted), not a URL or secret.

Set the override before making requests. It takes precedence over host detection;
`set_client_provider(client, provider=None)` restores host detection. Other
clients are unaffected. A client returned by `copy()` or `with_options()` is a
separate instance: set its override explicitly too, especially if its endpoint
changes. Unconfigured loopback, proxy and unknown hosts retain the historical
`openai` label; the instrumentor never assumes a local server is Ollama.

For applications using the native `ollama` Python client instead, use
`traceai-ollama`. Do not install both instrumentors for the same API call.
See [Ollama's OpenAI compatibility guide](https://docs.ollama.com/api/openai-compatibility)
for supported endpoints and models.

## Quickstart

### Register Tracer Provider
Set up the trace provider to establish the observability pipeline. The trace provider:

```python
from fi_instrumentation import register
from fi_instrumentation.fi_types import ProjectType

trace_provider = register(
    project_type=ProjectType.OBSERVE,
    project_name="openai_app"
)
```

### Configure OpenAI Instrumentation
Set up your OpenAI client with built-in observability. This includes support for text, image, and audio models.

```python
from traceai_openai import OpenAIInstrumentor

OpenAIInstrumentor().instrument(tracer_provider=trace_provider)
```

### Make a traced request
Create the client after calling `OpenAIInstrumentor().instrument(...)`.

```python
from openai import OpenAI

# OpenAI reads OPENAI_API_KEY from your environment.
with OpenAI() as client:
    response = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[
            {"role": "system", "content": "You are a helpful assistant."},
            {"role": "user", "content": "Can you tell me a joke?"},
        ],
    )
    print((response.choices[0].message.content or "").strip())
trace_provider.force_flush()  # Flush before a short-lived script exits.
```

## Azure OpenAI

Use the same `traceAI-openai` package and `OpenAIInstrumentor` for Azure OpenAI.
Keep the tracer registration and instrumentation above, and replace the OpenAI
client and request with one of the following examples. Do not enable a second
OpenAI instrumentor for the same calls.

Set your Azure resource key and **deployment name** (not the underlying model ID).
You do not need an OpenAI API key:

```bash
export AZURE_OPENAI_API_KEY="your-azure-resource-key"
export AZURE_OPENAI_DEPLOYMENT="your-deployment-name"
```

### v1 API

For a resource that supports the [Azure OpenAI v1 API](https://learn.microsoft.com/en-us/azure/ai-foundry/openai/api-version-lifecycle),
set its complete base URL, including `/openai/v1/`:

```bash
export AZURE_OPENAI_BASE_URL="https://your-resource.openai.azure.com/openai/v1/"
```

```python
import os
from openai import OpenAI

with OpenAI(
    base_url=os.environ["AZURE_OPENAI_BASE_URL"],
    api_key=os.environ["AZURE_OPENAI_API_KEY"],
) as client:
    response = client.chat.completions.create(
        model=os.environ["AZURE_OPENAI_DEPLOYMENT"],
        messages=[{"role": "user", "content": "Say hello in five words."}],
    )
    print(response.choices[0].message.content)
trace_provider.force_flush()
```

### Versioned Azure API

For an existing `AzureOpenAI` application, keep your resource endpoint and an
API version supported by your deployment. Public Azure resources use
`https://your-resource.openai.azure.com`; [Azure Government](https://learn.microsoft.com/en-us/azure/azure-government/compare-azure-government-global-azure)
resources use `https://your-resource.openai.azure.us`:

```bash
export AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.us"
export AZURE_OPENAI_API_VERSION="<supported-api-version>"
```

```python
import os
from openai import AzureOpenAI

with AzureOpenAI(
    azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
    api_version=os.environ["AZURE_OPENAI_API_VERSION"],
    api_key=os.environ["AZURE_OPENAI_API_KEY"],
) as client:
    response = client.chat.completions.create(
        model=os.environ["AZURE_OPENAI_DEPLOYMENT"],
        messages=[{"role": "user", "content": "Say hello in five words."}],
    )
    print(response.choices[0].message.content)
trace_provider.force_flush()
```

Both clients use the existing instrumentation, including async clients and
streaming. Spans from resource hosts under `openai.azure.com` and
`openai.azure.us` are labelled `gen_ai.provider.name="azure"`; custom gateways
retain their existing provider label. If you use Microsoft Entra ID, keep the
SDK token-provider configuration for your cloud instead of the API-key setup.

For `AzureOpenAI` and `AsyncAzureOpenAI` instances, including custom gateways,
spans also record `azure.openai.deployment` (the client's `azure_deployment`,
otherwise the request's `model`), `azure.openai.api_version` (when present in the
client's default query), `server.address` (lowercase endpoint host only), and
`server.port` (when explicitly present in the endpoint URL). Unavailable values
are omitted; this metadata excludes full URLs, credentials and other query
parameters. Plain `OpenAI`/`AsyncOpenAI` clients, including the v1 example above,
keep provider attribution only. Explicit `set_client_provider(...)` overrides
still take precedence for `gen_ai.provider.name`.

Azure Government does not change the trace export destination. Configure an
approved Future AGI destination and content settings before tracing sensitive
workloads; prompts and responses are captured by default.
## Baseten

Use the same `OpenAIInstrumentor` with Baseten's OpenAI-compatible clients; no
second instrumentor is needed. After the Quickstart tracer setup, create your
client with `api_key=os.environ["BASETEN_API_KEY"]` and the appropriate base URL:

- Model APIs: `https://inference.baseten.co/v1`.
- Dedicated deployments: your deployment's OpenAI-compatible base URL, such as
  `https://model-abc123.api.baseten.co/environments/production/sync/v1`.

The hosted endpoint and dedicated `model-*.api.baseten.co` endpoints, including
regional model endpoints, are attributed to `baseten`. Unknown proxies retain
`openai` unless you set an explicit client provider override. Supported API
routes and model names depend on the deployment; use the values in
[Baseten's inference API reference](https://docs.baseten.co/reference/inference-api/overview).
The standalone Model APIs recipe in `python/examples/baseten` accepts only Model
APIs URLs; use the OpenAI client directly for a dedicated deployment. Baseten's
separate Performance Client and non-OpenAI protocols need their own tracing setup.

## Vercel AI Gateway

Use the same `OpenAIInstrumentor` for Chat Completions sent to Vercel AI Gateway;
no gateway-specific package or OpenAI key is needed. Set `AI_GATEWAY_API_KEY` to your Vercel
AI Gateway key and `AI_GATEWAY_MODEL` to a current
[model ID](https://vercel.com/ai-gateway/models):

```bash
export AI_GATEWAY_API_KEY="your-vercel-ai-gateway-key"
export AI_GATEWAY_MODEL="<provider>/<model>"
```

Keep the tracer registration and instrumentation from the Quickstart above,
then replace its OpenAI client and request with:

```python
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://ai-gateway.vercel.sh/v1",
    api_key=os.environ["AI_GATEWAY_API_KEY"],
)
response = client.chat.completions.create(
    model=os.environ["AI_GATEWAY_MODEL"],
    messages=[{"role": "user", "content": "Say hello in five words."}],
)
print(response.choices[0].message.content)
trace_provider.force_flush()  # Flush before a short-lived script exits.
```

The documented gateway host is labelled `gen_ai.provider.name="vercel"`.
This identifies the service the client calls, **not** the upstream model provider
or a fallback provider. Unknown proxies and look-alike hosts retain their existing
provider label. Sync, async, streamed and failed calls use the same attribution.

Client spans capture prompts, responses and returned token usage. They do not
reconstruct gateway routing, retries, cost or provider attempts. Vercel's separate
[Trace Drains](https://vercel.com/docs/ai-gateway/observability-and-spend/trace-drains)
provide those gateway details but omit prompts and completions. A drain is not
configured by `OpenAIInstrumentor`; do not sum client and drain token counts for
the same request as separate model usage.


