AI Gateway Trace Drains

AI Gateway produces an OpenTelemetry trace for every request it handles. A trace drain forwards those traces to any OTLP/HTTP-compatible endpoint, such as your own collector or a native integration from the Marketplace, so you can inspect latency, token usage, and provider failover in the observability tool you already use.

For the underlying drain configuration and OTLP formats, see the Drains documentation.

1. Create a trace drain

   From the Vercel dashboard, go to Team Settings > Drains and click Add Drain. You can also use a native integration that configures the endpoint for you.

2. Configure the destination

   Configure the destination to send traces to your OTLP/HTTP collector.

3. Send an AI Gateway request

   Set AI_GATEWAY_API_KEY to your AI Gateway API key, then run:

   Terminal

   curl -X POST "https://ai-gateway.vercel.sh/v1/responses" \
     -H "Authorization: Bearer $AI_GATEWAY_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "model": "openai/gpt-6-astra",
       "input": "Write a one-sentence bedtime story."
     }'

   Once the drain is active, AI Gateway forwards the resulting trace based on your sampling rules.

Native integrations that support trace drains include:

• Braintrust: AI evaluation, monitoring, and observability
• Dash0: OpenTelemetry-native logs, traces, and metrics
• Kubiks: Logs, traces, dashboards, and alerts
• Sentry: Error and performance monitoring
• Statsig: Feature flags, experiments, and analytics

The Native Integrations section of the drain creation flow always shows the current list of integrations that support trace drains.

AI Gateway Traces bills on two meters: the number of trace events delivered to your drains, and the volume of trace data transferred (egress). Vercel bills the two meters separately.

Pro plans don't include an allowance for either meter. Charges begin with the first delivered trace and first byte of trace egress.

Vercel applies these billing rules:

• Each request counts as a single trace event for each drain that delivers it, even when the request fails over across multiple providers
• A trace event is counted only when a delivered payload contains the request's root span
• Failed deliveries don't incur a trace-event charge

Provider attempts appear as separate spans within the trace, but they don't add trace events.

Sampling rules control the percentage of traces forwarded to each drain. A higher sampling rate can increase both trace-event and egress charges.

You can track both meters on the Usage dashboard under Drains → AI Gateway Traces.

To stop future charges, pause or delete the trace drain.

Each AI Gateway request produces a single trace with the resource attributes service.name: ai-gateway and service.namespace: vercel. Within that trace, AI Gateway emits these spans:

The root span's <operation> reflects the request type: chat, embeddings, generate_content for image and video models, or retrieval for reranking.

Span attributes use two namespaces: gen_ai.* follows the OpenTelemetry GenAI semantic conventions, and vercel.ai_gateway.* carries gateway-specific fields. Attributes are omitted when they don't apply to a request. See the Trace Drains reference for the OTLP envelope and JSON/Protobuf formats.

AI Gateway traces contain request metadata, but they don't include prompt or completion content.

Standard gen_ai.* attributes describe the model interaction:

Gateway-specific vercel.ai_gateway.* attributes carry routing, billing, and attribution detail:

AI Gateway records project and deployment IDs as span attributes named vercel.project.id and vercel.deployment.id. These differ from the vercel.projectId and vercel.deploymentId resource attributes on Vercel deployment traces.

The routing span records how AI Gateway chose a provider, and each model attempt span records one model in the fallback chain:

Each provider attempt span records one upstream call:

• Drains overview
• Configure Drains
• Trace Drains reference
• AI Gateway pricing