Cloudflare AI Gateway
Cloudflare AI Gateway provides a unified interface to access multiple AI providers with observability, caching, and rate limiting. Braintrust traces requests routed through Cloudflare AI Gateway across all supported providers.Setup
Install the Braintrust SDK alongside the OpenAI client, then configure your environment variables.1
Install packages
2
Set environment variables
.env
Manual instrumentation
To trace requests routed through Cloudflare AI Gateway, wrap your OpenAI client withwrapOpenAI and point it at the gateway’s OpenAI-compatible endpoint.Switching providers
Cloudflare AI Gateway’s unified API allows you to easily switch between different AI providers by changing themodel parameter and corresponding API key. All requests are automatically traced by Braintrust regardless of which provider you use.AI Gateway resources
Cloudflare Workers AI
Workers AI runs models from a Worker through an AI binding. Braintrust v3.40.0+ traces calls to Cloudflare’s Clef decision models (@cf/cloudflare/clef, @cf/cloudflare/clef-flash, and @cf/cloudflare/clef-omni) and the Clairic extraction model (@cf/cloudflare/clairic).Setup
Install the Braintrust SDK in your Worker project, then configure the Worker and add your Braintrust API key.1
Install packages
2
Configure the Worker
In your Worker’s
wrangler.jsonc, add a Workers AI binding named AI and enable the nodejs_compat compatibility flag, which the Braintrust SDK needs for the Node.js AsyncLocalStorage API:wrangler.jsonc
3
Add your Braintrust API key
Store your Braintrust API key as a Worker secret named
BRAINTRUST_API_KEY:Manual instrumentation
To trace Workers AI calls, wrap the AI binding withwrapWorkersAI() and call run() on the wrapped binding. wrapWorkersAI() traces Clef and Clairic calls that return a JSON result. Calls to other models, and calls that stream, return a raw response, use a WebSocket, or queue the request, pass through unchanged.logger.flush() to ctx.waitUntil() sends the trace after the response returns. See the Cloudflare Workers setup guide for the full deployment configuration.What Braintrust traces
Braintrust records each traced call as aworkers_ai.run span:- Decision spans (
workers_ai.run) for Clef calls, with the state and each question’s ID, type, instructions, and criteria as input, and the list of answers, each with its question ID, as output. - Extraction spans (
workers_ai.run) for Clairic calls, with the state, each field’s ID and settings, the reference date, and options as input, and each field’s extracted value and confidence details as output. - Model, provider (
cloudflare), and operation (decisionorextraction) in metadata. - Token usage metrics (prompt, completion, and total) when Workers AI reports them.
- Base64 images, audio, and video in the input, stored as attachments when
BRAINTRUST_CAPTURE_ATTACHMENTSis enabled and recorded as<omitted>otherwise.
Workers AI resources
Cloudflare Agents
Cloudflare Agents instrument each agent run with OpenTelemetry spans that follow the GenAI semantic conventions. Because Braintrust ingests OpenTelemetry data, you can export these spans to Braintrust from Cloudflare’s Workers Observability without adding the Braintrust SDK to your Worker. Braintrust maps the incoming spans toLLM and tool spans automatically.
1
Get your Braintrust credentials
Create an API key in Settings > API keys. Find your project ID using the Copy project ID button at the bottom of the project’s configuration page.
2
Add a tracing destination in Cloudflare
In the Cloudflare dashboard, go to your account’s Workers Observability section and add a destination pointing at Braintrust’s OpenTelemetry endpoint. Name it
braintrust so you can reference it in the next step:- Name:
braintrust. - OTLP endpoint:
https://api.braintrust.dev/otel/v1/traces. - Custom headers:
Authorization:Bearer <BRAINTRUST_API_KEY>.x-bt-parent:project_id:<BRAINTRUST_PROJECT_ID>.
x-bt-parent header sets the project or experiment that receives the traces. For other parent formats and the full attribute mapping, see the OpenTelemetry integration.If your organization is on the EU data plane, use
https://api-eu.braintrust.dev/otel/v1/traces instead. Self-hosted deployments should use their stack’s API URL followed by /otel/v1/traces. See Data plane region.3
Enable trace export in wrangler
In your Worker’s Deploy your Worker. Agent runs now appear as traces in Braintrust.
wrangler.jsonc, enable trace export and reference the braintrust destination you created by name:wrangler.jsonc