How to trace Cloudflare AI Gateway with HoneyHive

Cloudflare AI Gateway sits in front of provider APIs and adds caching, rate limiting, and logging. Keep the provider SDK you already use, point it at the gateway, and call that SDK’s HoneyHive instrumentor. HoneyHive traces the SDK, not Cloudflare. No Cloudflare-specific tracer is required. The OpenAI example below is the common case.

Quick Start

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.

To see where to initialize the tracer for your environment, including AWS Lambda and long-running servers, see Tracer Initialization.

pip install "honeyhive[openinference-openai]"

import os
from openai import OpenAI
from honeyhive import HoneyHiveTracer
from openinference.instrumentation.openai import OpenAIInstrumentor

tracer = HoneyHiveTracer.init(api_key=os.getenv("HH_API_KEY"))
OpenAIInstrumentor().instrument(tracer_provider=tracer.provider)

account_id = os.getenv("CLOUDFLARE_ACCOUNT_ID")
gateway_id = os.getenv("CLOUDFLARE_GATEWAY_ID")

client = OpenAI(
    api_key=os.getenv("OPENAI_API_KEY"),
    base_url=f"https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/openai",
)

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello, world!"}],
)
print(response.choices[0].message.content)

Create a gateway in the Cloudflare dashboard, then copy the account ID and gateway ID into the URL. See Cloudflare’s OpenAI provider docs for the current endpoint shape.

What Gets Traced

The instrumentor captures gateway-routed SDK calls the same way it captures direct provider calls:

Chat completions - Inputs, outputs, and token usage
Tool / function calls - Arguments and results for each tool invocation
Streaming responses - Streamed completions with aggregated tokens

Authenticated Gateway

If the gateway requires Cloudflare authentication, send the token in cf-aig-authorization and keep the provider key as api_key:

client = OpenAI(
    api_key=os.getenv("OPENAI_API_KEY"),
    base_url=f"https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/openai",
    default_headers={
        "cf-aig-authorization": f"Bearer {os.getenv('CF_AIG_TOKEN')}",
    },
)

With BYOK or Unified Billing, Cloudflare stores the provider key. Set api_key to the Cloudflare token instead:

client = OpenAI(
    api_key=os.getenv("CF_AIG_TOKEN"),
    base_url=f"https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/openai",
)

Unified REST API

Cloudflare also exposes OpenAI-compatible endpoints on api.cloudflare.com. That client is still the OpenAI SDK, so the same instrumentor traces it. Model names use author/model (for example openai/gpt-4.1-mini), and the Cloudflare API token is api_key:

client = OpenAI(
    api_key=os.getenv("CLOUDFLARE_API_TOKEN"),
    base_url=f"https://api.cloudflare.com/client/v4/accounts/{account_id}/ai/v1",
    default_headers={"cf-aig-gateway-id": gateway_id},
)

cf-aig-gateway-id targets a specific gateway. Omit it for third-party models to use the account default. Workers AI models require the header. See Cloudflare’s REST API for the current model catalog and /ai/v1/responses usage. Either base URL traces the same way, so if you already call OpenAI through gateway.ai.cloudflare.com, keep that base_url.

Other Provider SDKs

HoneyHive patches the SDK you import, not the host. For a provider SDK that accepts a custom base URL:

Install the extra from that SDK’s integration page
Call its instrumentor with tracer_provider=tracer.provider
Point the SDK base_url (or equivalent, such as http_options.base_url) at Cloudflare’s provider URL. The {provider} segment and any extra path pieces live on Cloudflare’s provider pages. Authenticated gateways still send cf-aig-authorization.

HoneyHive ships instrumentors for these provider SDKs:

SDK	Extra	Instrumentor
OpenAI	`honeyhive[openinference-openai]`	`OpenAIInstrumentor`
Anthropic	`honeyhive[openinference-anthropic]`	`AnthropicInstrumentor`
Google Gemini	`honeyhive[openinference-google-ai]`	`GoogleGenAIInstrumentor`
Azure OpenAI	`honeyhive[openinference-azure-openai]`	`OpenAIInstrumentor`

Do not re-point a boto3 Bedrock client at the gateway. Bedrock uses SigV4, so a base_url / endpoint_url swap fails. Use the unified REST API with the OpenAI SDK (aws-bedrock/...), or follow Cloudflare’s Bedrock provider page for the signed request shape. Cloudflare also proxies Groq, DeepSeek, Mistral, xAI, OpenRouter, and other OpenAI-compatible APIs. Keep OpenAIInstrumentor and the OpenAI SDK. Change base_url to that provider’s Cloudflare path. A vendor package that is not openai (for example a Groq-only SDK) is not patched. If HoneyHive has no instrumentor for that SDK, use the unified REST API with the OpenAI SDK, or LiteLLM if you already route calls through LiteLLM. Raw fetch / curl is not autotraced.

Environment Configuration

export HH_API_KEY="your-honeyhive-api-key"

export OPENAI_API_KEY="your-openai-api-key"
export CLOUDFLARE_ACCOUNT_ID="your-cloudflare-account-id"
export CLOUDFLARE_GATEWAY_ID="your-gateway-id"

# Authenticated gateway or BYOK / Unified Billing
export CF_AIG_TOKEN="your-cloudflare-ai-gateway-token"

# Unified REST API
export CLOUDFLARE_API_TOKEN="your-cloudflare-api-token"

Troubleshooting

Traces not appearing

Check the instrumentor - Call the instrumentor for the SDK you import, with tracer_provider=tracer.provider, before creating the client or making requests
Confirm you use a provider SDK - HoneyHive traces SDK methods. Raw fetch / curl to the gateway is not autotraced
Check HH_API_KEY - Use a project API key from Settings → Project → API Keys

Requests fail at the gateway

Account and gateway IDs - Both path segments must match a gateway in the Cloudflare dashboard
Authenticated gateway - Provider-specific URLs on gateway.ai.cloudflare.com use cf-aig-authorization, not Authorization, for the Cloudflare token
Model name - Provider-specific OpenAI URLs use OpenAI model IDs (gpt-4o-mini). The unified REST API uses author/model for third-party models and @cf/author/model for Workers AI
/ai/run is not autotraced - That envelope endpoint is not a provider SDK. Use /ai/v1/chat/completions or a provider-native SDK URL if you want HoneyHive to capture the call
Cache hits - HoneyHive records the completion the SDK receives. A gateway cache hit still returns a completion body, so the span still has inputs, outputs, and any usage on that body. The instrumentor does not capture Cloudflare headers such as cf-aig-cache-status. Add that with enrich_span if you need it.

Integrations Overview

Provider SDK instrumentors to pair with a gateway base_url

OpenAI Integration

OpenAIInstrumentor used in the Quick Start

Portkey

Another OpenAI-compatible gateway traced the same way

Custom Spans

Create spans for business logic around API calls

Enrich Your Traces

Add user IDs and custom metadata to traces

Agent Frameworks & Platforms

Model Providers

AI Gateways

Coding Agents

Evaluation

How to trace Cloudflare AI Gateway with HoneyHive

Quick Start

What Gets Traced

Authenticated Gateway

Unified REST API

Other Provider SDKs

Environment Configuration

Troubleshooting

Traces not appearing

Requests fail at the gateway

Integrations Overview

OpenAI Integration

Portkey

Custom Spans

Enrich Your Traces

Resources

​Quick Start

​What Gets Traced

​Authenticated Gateway

​Unified REST API

​Other Provider SDKs

​Environment Configuration

​Troubleshooting

​Traces not appearing

​Requests fail at the gateway

​Related

Integrations Overview

OpenAI Integration

Portkey

Custom Spans

Enrich Your Traces

​Resources

Quick Start

What Gets Traced

Authenticated Gateway

Unified REST API

Other Provider SDKs

Environment Configuration

Troubleshooting

Traces not appearing

Requests fail at the gateway

Related

Resources