Skip to main content
Braintrust integrates with Cloudflare in three ways: tracing LLM requests routed through Cloudflare AI Gateway, tracing Clef and Clairic calls on Workers AI bindings, and exporting traces from Cloudflare Agents over OpenTelemetry. This page covers all three.

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 with wrapOpenAI 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 the model parameter and corresponding API key. All requests are automatically traced by Braintrust regardless of which provider you use.
Cloudflare AI Gateway supports OpenAI, Anthropic, Google AI Studio, Groq, Mistral, Cohere, Perplexity, DeepSeek, Cerebras, xAI, and Workers AI. See the Cloudflare documentation for the complete list.

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 with wrapWorkersAI() 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.
Passing 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 a workers_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 (decision or extraction) 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_ATTACHMENTS is 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 to LLM 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>.
The 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 wrangler.jsonc, enable trace export and reference the braintrust destination you created by name:
wrangler.jsonc
Deploy your Worker. Agent runs now appear as traces in Braintrust.

Cloudflare Agents resources