Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 46 additions & 0 deletions .github/workflows/vercel-gateway-tests.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
name: Vercel gateway client tests

on:
pull_request:
branches: [main, dev]
paths:
- 'python/frameworks/openai/**'
- 'python/fi_instrumentation/**'
- '.github/workflows/vercel-gateway-tests.yml'
push:
branches: [dev]
paths:
- 'python/frameworks/openai/**'
- 'python/fi_instrumentation/**'
- '.github/workflows/vercel-gateway-tests.yml'
workflow_dispatch:

permissions:
contents: read

jobs:
contracts:
name: Gateway OTLP (openai ${{ matrix.sdk }})
runs-on: ubuntu-24.04
timeout-minutes: 10
strategy:
fail-fast: false
matrix:
sdk: ['1.69.0', '3.42.0']
steps:
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
with:
persist-credentials: false
- uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
with:
python-version: '3.13'
- name: Install the SDK and published tracing core
env:
SDK_VERSION: ${{ matrix.sdk }}
run: python -m pip install "openai==$SDK_VERSION" 'fi-instrumentation-otel==1.2.2' pytest pytest-socket
- name: Run SDK-to-OTLP contracts with non-local sockets blocked
env:
PYTHONPATH: python/frameworks/openai
run: |
python -m pytest python/frameworks/openai/tests/test_vercel_gateway.py -q \
--disable-socket --allow-hosts=127.0.0.1,localhost --allow-unix-socket
77 changes: 57 additions & 20 deletions python/frameworks/openai/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,15 +12,13 @@ pip install traceAI-openai
```


### Set Environment Variables
Set up your environment variables to authenticate with FutureAGI
### Set environment variables
Set the Future AGI keys for tracing and the OpenAI key for the Quickstart request:

```python
import os

os.environ["FI_API_KEY"] = FI_API_KEY
os.environ["FI_SECRET_KEY"] = FI_SECRET_KEY
os.environ["OPENAI_API_KEY"] = OPENAI_API_KEY
```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"
```

## Quickstart
Expand All @@ -47,22 +45,61 @@ from traceai_openai import OpenAIInstrumentor
OpenAIInstrumentor().instrument(tracer_provider=trace_provider)
```

### Create OpenAI Components
Set up your OpenAI client with built-in observability.
### Make a traced request
Create the client after calling `OpenAIInstrumentor().instrument(...)`.

```python
import openai

openai.api_key = os.environ["OPENAI_API_KEY"]
from openai import OpenAI

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

## 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:

print(response.choices[0].message['content'].strip())
```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.

96 changes: 96 additions & 0 deletions python/frameworks/openai/tests/test_readme_examples.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,96 @@
"""Run the README's actual Quickstart and gateway blocks without vendor traffic."""

import json
import re
from pathlib import Path

import openai
import pytest
from opentelemetry.proto.collector.trace.v1.trace_service_pb2 import (
ExportTraceServiceRequest,
)

from tests.test_vercel_gateway import (
ANSWER,
GATEWAY_KEY,
REQUEST_MODEL,
attributes,
gateway_response,
sdk_httpx,
)

pytest_plugins = ("tests.test_vercel_gateway",)


@pytest.mark.parametrize(
"section,host,provider,model",
[
("Quickstart", "api.openai.com", "openai", "gpt-4o-mini"),
("Vercel AI Gateway", "ai-gateway.vercel.sh", "vercel", REQUEST_MODEL),
],
)
def test_readme_request_blocks(collector, monkeypatch, section, host, provider, model):
readme = (Path(__file__).resolve().parents[1] / "README.md").read_text()
quickstart = readme.split("## Quickstart\n", 1)[1].split(
"## Vercel AI Gateway\n", 1
)[0]
setup, instrument, openai_request = re.findall(
r"```python\n(.*?)```", quickstart, flags=re.DOTALL
)
gateway = readme.split("## Vercel AI Gateway\n", 1)[1]
gateway_request = re.findall(r"```python\n(.*?)```", gateway, flags=re.DOTALL)
assert len(gateway_request) == 1
request = gateway_request[0] if section == "Vercel AI Gateway" else openai_request

seen = []
original_init = openai.OpenAI.__init__

def handle(http_request):
seen.append(http_request)
return gateway_response("success", True)

def mock_transport_only(self, *args, **kwargs):
kwargs["http_client"] = sdk_httpx.Client(
transport=sdk_httpx.MockTransport(handle), trust_env=False
)
original_init(self, *args, **kwargs)

monkeypatch.setenv("OPENAI_API_KEY", "synthetic-openai-key")
monkeypatch.setenv("AI_GATEWAY_API_KEY", GATEWAY_KEY)
monkeypatch.setenv("AI_GATEWAY_MODEL", REQUEST_MODEL)
monkeypatch.setattr(openai.OpenAI, "__init__", mock_transport_only)
namespace = {}
try:
for block in (setup, instrument, request):
# The README is repository-owned; executing it catches stale SDK APIs.
exec( # noqa: S102
compile(
block,
str(Path(__file__).resolve().parents[1] / "README.md"),
"exec",
),
namespace,
)
assert len(collector) == 1 # The README flushes its own short-lived trace.
finally:
if "trace_provider" in namespace:
namespace["trace_provider"].shutdown()
from traceai_openai import OpenAIInstrumentor

OpenAIInstrumentor().uninstrument()

assert len(seen) == len(collector) == 1
assert seen[0].url.host == host
assert json.loads(seen[0].content)["model"] == model
if section == "Vercel AI Gateway":
assert seen[0].headers["authorization"] == f"Bearer {GATEWAY_KEY}"
wire = ExportTraceServiceRequest.FromString(collector[0][2])
spans = [
span
for resource in wire.resource_spans
for scope in resource.scope_spans
for span in scope.spans
]
assert len(spans) == 1
assert attributes(spans[0].attributes)["gen_ai.provider.name"] == provider
assert ANSWER.encode() in collector[0][2]
Loading
Loading