> ## Documentation Index
> Fetch the complete documentation index at: https://docs.honeyhive.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# How to trace Vercel AI Gateway with HoneyHive

> HoneyHive integration for Vercel AI Gateway. Trace gateway requests with prompts and completions through the OpenAI SDK, or export gateway traces with a Vercel AI Gateway drain.

[Vercel AI Gateway](https://vercel.com/docs/ai-gateway) gives you one endpoint for models from many providers, with provider failover, BYOK, and spend tracking. You can send its traces to HoneyHive in two ways:

| Route | Code change | Captures |
| - | - | - |
| [SDK instrumentor](#quick-start) | Point your provider SDK (OpenAI, Anthropic, and others) at the gateway and call its instrumentor | Prompts, completions, tool calls, token usage, and gateway cost |
| [AI Gateway drain](#ai-gateway-drain-no-code) | None. You configure it in Vercel team settings | Model, provider, token usage, cost, latency, routing, and failover attempts for every gateway request. No prompts or completions |

The SDK route traces the apps you instrument, with full content. The drain covers every gateway request on your Vercel team without code changes. You can run both. Vercel's gateway traces [do not include prompt or completion content](https://vercel.com/docs/ai-gateway/observability-and-spend/trace-drains#what-a-trace-contains), so drain events in HoneyHive have empty inputs and outputs.

## Quick Start

<Tip>
  **Point your OpenAI client at the gateway, then instrument as usual.** `OpenAIInstrumentor` patches the SDK, so chat completions, tools, and token usage are traced regardless of the `base_url`.
</Tip>

AI Gateway exposes an OpenAI-compatible API at `https://ai-gateway.vercel.sh/v1`. HoneyHive traces the OpenAI SDK, not the gateway, so the [OpenAI integration](/v2/integrations/openai) works unchanged. Model IDs use `provider/model`.

<Tip>
  To see where to initialize the tracer for your environment, including AWS Lambda and long-running servers, see [Tracer Initialization](/v2/tracing/tracer-initialization).
</Tip>

<Note>
  Last tested with `honeyhive 1.6.0`, `openai 3.20.0`, and `openinference-instrumentation-openai 0.1.61` (September 2026).
</Note>

```bash theme={null}
pip install "honeyhive[openinference-openai]"
```

```python theme={null}
import os
from openai import OpenAI
from honeyhive import HoneyHiveTracer
from openinference.instrumentation.openai import OpenAIInstrumentor

tracer = HoneyHiveTracer.init()  # Reads HH_INGESTION_API_KEY from your environment
OpenAIInstrumentor().instrument(tracer_provider=tracer.provider)

client = OpenAI(
    api_key=os.getenv("AI_GATEWAY_API_KEY"),
    base_url="https://ai-gateway.vercel.sh/v1",
)

response = client.chat.completions.create(
    model="openai/gpt-4o-mini",
    messages=[{"role": "user", "content": "Write a one-sentence bedtime story."}],
)
print(response.choices[0].message.content)
```

Create an API key in the [AI Gateway dashboard](https://vercel.com/d?to=%2F%5Bteam%5D%2F%7E%2Fai%2Fapi-keys). On Vercel deployments, you can use the Vercel OIDC token instead. See Vercel's [authentication docs](https://vercel.com/docs/ai-gateway/authentication-and-byok).

The instrumentor captures:

* **Chat completions** - Inputs, outputs, and token usage
* **Tool / function calls** - Arguments and results for each tool invocation
* **Streaming responses** - Streamed completions with aggregated tokens
* **Gateway response fields** - The gateway returns `generationId` and `usage.cost` in each response, and they arrive in the event's `config`

The same pattern works with any provider SDK that AI Gateway supports and HoneyHive instruments, such as the [OpenAI](/v2/integrations/openai) and [Anthropic](/v2/integrations/anthropic) SDKs. Point the SDK at the gateway (`https://ai-gateway.vercel.sh/v1` for OpenAI, `https://ai-gateway.vercel.sh` for Anthropic) and call that SDK's instrumentor. Raw `fetch` / `curl` calls are not autotraced. The [AI Gateway drain](#ai-gateway-drain-no-code) captures those requests.

***

## AI Gateway drain (no code)

The drain forwards a trace of every gateway request your Vercel team makes, from any app, with no code changes. It needs a Vercel team on the Pro or Enterprise plan. Vercel bills each delivered trace plus trace egress. See Vercel's [trace drain pricing](https://vercel.com/docs/ai-gateway/observability-and-spend/trace-drains#usage-and-pricing).

### Configure the drain

<Steps>
  <Step title="Create a HoneyHive ingestion key">
    Create an [ingestion API key](/v2/workspace/api-keys#ingestion-keys) in [**Settings → Project → API Keys**](https://app.us.honeyhive.ai/settings/project/keys), on the Ingestion tab. The key sets which HoneyHive project receives the traces.
  </Step>

  <Step title="Add an AI Gateway drain">
    In the Vercel dashboard, go to **Team Settings → [Drains](https://vercel.com/d?to=%2F%5Bteam%5D%2F%7E%2Fsettings%2Fdrains)** and click **Add Drain**. Select **AI Gateway** as the data type. A **Traces** drain sends your deployments' request spans, not AI Gateway requests.
  </Step>

  <Step title="Point the custom endpoint at HoneyHive">
    Select **Custom Endpoint** and set:

    | Field | Value |
    | - | - |
    | Endpoint URL | `https://<provider-host>/opentelemetry/v1/traces` |
    | Format | `JSON` or `Protobuf` |
    | Custom Headers | `Authorization: Bearer <HH_INGESTION_API_KEY>` |

    For US production, the endpoint is `https://api.dp1.us.prod.honeyhive.ai/opentelemetry/v1/traces`. Use the host shown in your HoneyHive dashboard.
  </Step>

  <Step title="Create the drain and send a request">
    Click **Create Drain**, then send any request through AI Gateway, for example with the [Quick Start](#quick-start) code.
  </Step>
</Steps>

### What HoneyHive records

Each gateway request is one OpenTelemetry trace with `service.name: ai-gateway`. HoneyHive maps its spans to events:

| Vercel span | HoneyHive event type | Fields |
| - | - | - |
| `<operation> <model>` (root, for example `chat openai/gpt-4o-mini`) | `model` | `config.model`, `config.provider`, `metadata.input_tokens`, `metadata.output_tokens`, `metadata.total_tokens`, latency |
| `vercel.ai_gateway.routing` | `tool` | Provider filters and ordering |
| `vercel.ai_gateway.model_attempt <model>` | `model` | Position in the fallback chain and result |
| `<model> (<provider>)` | `model` | One per upstream provider call, with the provider status code |

Gateway-specific attributes arrive in `metadata` with their original names. Useful ones:

* `vercel.ai_gateway.cost.total` and `vercel.ai_gateway.cost.currency` - Request cost, as Vercel billed it. Vercel sends the cost as a decimal string, so it arrives in `metadata` as a string
* `vercel.ai_gateway.user.id` and `vercel.ai_gateway.tags` - The user ID and tags you attached to the request
* `vercel.ai_gateway.generation.id` - The generation ID in the AI Gateway dashboard
* `vercel.ai_gateway.credential.type` - `byok` or `system`
* `vercel.ai_gateway.api_format` - The API the client called: `openai-compat` for Chat Completions, `openresponses-compat` for the Responses API
* `vercel.ai_gateway.api_key.name` and `vercel.ai_gateway.environment` - The AI Gateway key that made the request, and the Vercel environment
* `gen_ai.response.time_to_first_chunk` - Time to first token, in seconds
* `vercel.ai_gateway.provider` - The exact gateway provider slug (for example `vertexAnthropic`). `config.provider` holds the OTel provider name instead (for example `aws.bedrock`)

The drain sends no session attribute, so these events appear in the Events view, not the Sessions view. To find them, filter by `service.name` = `ai-gateway`. To see one gateway request, filter by the `trace_id` metadata field.

***

## Troubleshooting

### SDK traces not appearing

1. **Check the instrumentor** - Call the instrumentor for your SDK with `tracer_provider=tracer.provider` before creating the client or making requests
2. **Confirm you use an instrumented SDK** - Raw `fetch` / `curl` to the gateway is not autotraced. Check the base URL: `https://ai-gateway.vercel.sh/v1` for OpenAI, `https://ai-gateway.vercel.sh` for Anthropic
3. **Check `HH_INGESTION_API_KEY`** - Set it to an [ingestion API key](/v2/workspace/api-keys#ingestion-keys)

### Drain traces not appearing

1. **Data type** - The drain must use the **AI Gateway** data type. A **Traces** drain forwards only `vercel.serverless-runtime` and `vercel.edge-network` spans
2. **Endpoint and header** - The URL must end with `/opentelemetry/v1/traces`, and the header must be exactly `Authorization: Bearer <HH_INGESTION_API_KEY>`. A wrong key returns `401`
3. **Project** - The key sets the project. Check the project where you created the key

***

## Resources

* [Vercel AI Gateway](https://vercel.com/docs/ai-gateway)
* [AI Gateway Trace Drains](https://vercel.com/docs/ai-gateway/observability-and-spend/trace-drains)
* [AI Gateway OpenAI Chat Completions API](https://vercel.com/docs/ai-gateway/sdks-and-apis/openai-chat-completions)


## Related topics

- [How to trace Cloudflare AI Gateway with HoneyHive](/v2/integrations/cloudflare-ai-gateway.md)
- [How to trace OpenAI with HoneyHive](/v2/integrations/openai.md)
- [How to trace LiteLLM with HoneyHive](/v2/integrations/litellm.md)