Tracing quickstart

Tracing captures the details of each step of an AI application’s execution. This lets you debug issues, understand model behavior, and optimize performance in production.

Use AI
Auto-instrument
Wrap manually

Let your AI coding assistant use the Braintrust MCP to add tracing automatically. Fastest way to get started. Works with any integration.If you’re new to Braintrust, sign up free at braintrust.dev.

2. Configure MCP

The Braintrust MCP (Model Context Protocol) server allows AI coding assistants to understand your Braintrust setup and auto-instrument your application. Add it to your AI tool’s configuration:

Claude Code

The Braintrust plugin for Claude Code wraps the MCP server and adds tracing capabilities. If you’ve installed that plugin, you don’t need to configure MCP separately.

Install Claude Code

If you haven’t already, install Claude Code.

Set your API key

Set the BRAINTRUST_API_KEY environment variable with your API key:

export BRAINTRUST_API_KEY="your-api-key-here"

Add the Braintrust MCP server

Add Braintrust MCP server with API key authentication:

claude mcp add --transport http braintrust \
  --header "Authorization: Bearer $YOUR_BRAINTRUST_API_KEY" \
  https://api.braintrust.dev/mcp

Alternatively, you can use OAuth authentication instead of an API key:

claude mcp add --transport http braintrust https://api.braintrust.dev/mcp

# Authenticate by typing /mcp
/mcp

Claude Desktop

Install Claude Desktop

If you haven’t already, download and install Claude Desktop.

Add the Braintrust MCP server

Follow the Claude Desktop documentation to create a custom connector with the following details:

Name: Braintrust
URL: https://api.braintrust.dev/mcp

Claude Desktop uses OAuth 2.0 for authentication. You don’t need to provide an API key in the connector configuration - you’ll authenticate when you first use the server.

Cursor

The Braintrust extension for Cursor automatically configures the MCP server for you. If you’ve installed that extension, you don’t need to configure MCP separately.

Install Cursor

If you haven’t already, download and install Cursor.

Add the Braintrust MCP server

Click to automatically add the Braintrust MCP server: Add to CursorOr manually add to .cursor/mcp.json:

{
  "mcpServers": {
    "braintrust": {
      "url": "https://api.braintrust.dev/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_BRAINTRUST_API_KEY"
      }
    }
  }
}

Replace YOUR_BRAINTRUST_API_KEY with your actual API key.Cursor also supports OAuth authentication. If you omit the headers field, Cursor will prompt you to authenticate via OAuth when you first use the server.

VS Code

Install VS Code

If you haven’t already, download and install Visual Studio Code.

Install an AI assistant extension

VS Code requires an AI assistant extension that supports the Model Context Protocol (MCP). Popular options include:

GitHub Copilot
Continue
Other MCP-compatible extensions

Install one of these extensions from the VS Code marketplace.

Add the Braintrust MCP server

Add the Braintrust MCP server to your VS Code settings, either in workspace settings or user settings:

Workspace settings - Create or edit .vscode/mcp.json in your project:

{
    "servers": {
        "braintrust": {
            "type": "http",
            "url": "https://api.braintrust.dev/mcp",
            "headers": {
                "Authorization": "Bearer YOUR_BRAINTRUST_API_KEY"
            }
        }
    }
}

User settings - Add to your VS Code user settings (Cmd+, / Ctrl+, → Search for “mcp”):

{
    "mcp.servers": {
        "braintrust": {
            "type": "http",
            "url": "https://api.braintrust.dev/mcp",
            "headers": {
                "Authorization": "Bearer YOUR_BRAINTRUST_API_KEY"
            }
        }
    }
}

Replace YOUR_BRAINTRUST_API_KEY with your actual API key.VSCode also supports OAuth authentication. If you omit the headers field, VSCode will prompt you to authenticate via OAuth when you first use the server.

Restart VS Code

Reload the VS Code window (Cmd+R / Ctrl+R) or restart VS Code to apply the configuration.

Windsurf

Install Windsurf

If you haven’t already, install Windsurf.

Add the Braintrust MCP server

Edit ~/.codeium/windsurf/mcp_config.json and add the Braintrust server:

{
  "mcpServers": {
    "braintrust": {
      "serverUrl": "https://api.braintrust.dev/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_BRAINTRUST_API_KEY"
      }
    }
  }
}

Replace YOUR_BRAINTRUST_API_KEY with your actual API key.

Restart Windsurf

Close and reopen Windsurf to load the new MCP server configuration.

Codex (OpenAI)

Install Codex

If you haven’t already, install Codex.

Set your API key

Set the BRAINTRUST_API_KEY environment variable with your API key:

export BRAINTRUST_API_KEY="your-api-key-here"

Add the Braintrust MCP server

Edit ~/.codex/config.toml and add the Braintrust MCP server configuration:

[mcp_servers.braintrust]
url = "https://api.braintrust.dev/mcp"
bearer_token_env_var = "BRAINTRUST_API_KEY"

This configures Codex to read your Braintrust API key from the BRAINTRUST_API_KEY environment variable.

Verify the setup

Launch Codex with the environment variable set:

codex

Run the /mcp command to verify Braintrust is installed and accessible.

OpenCode

For automatically tracing of OpenCode sessions, consider the Braintrust plugin for OpenCode.

Install OpenCode

If you haven’t already, install OpenCode.

Add the Braintrust MCP server

Edit your OpenCode configuration file and add the Braintrust MCP server:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "braintrust": {
      "type": "remote",
      "url": "https://api.braintrust.dev/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_BRAINTRUST_API_KEY"
      }
    }
  }
}

Replace YOUR_BRAINTRUST_API_KEY with your actual API key.

Restart OpenCode

Restart OpenCode to apply the configuration changes.

3. Prompt assistant

Ask your AI assistant to set up Braintrust in your project:

Install the Braintrust SDK and add tracing to my app.

Your assistant will read the docs://sdk-install resource, detect your programming language and frameworks, install the appropriate SDK, and configure auto-instrumentation. Once complete, it will run your app, verify traces are being logged, and provide a permalink to view them in Braintrust.

Troubleshoot

MCP authentication issues?

Invalid client errors: Verify the URL is exactly https://api.braintrust.dev/mcp (no trailing slash).Connection timeouts: Check internet connection. Corporate networks may need to allowlist api.braintrust.dev and *.braintrust.dev.MCP server not appearing: Restart your AI tool and verify JSON configuration syntax.

Need help?

Join our Discord
Email us at support@braintrust.dev
Use the Loop feature in the Braintrust UI

Automatically trace all LLM requests with minimal setup.

Works for Python, Ruby, and Go. For other languages, use AI or instrument manually.

If you’re new to Braintrust, sign up free at braintrust.dev.

2. Get API keys

Create API keys for:

Braintrust
Your AI provider or framework (OpenAI, Anthropic, Gemini, etc.)

Set them as environment variables:

export BRAINTRUST_API_KEY="<your-braintrust-api-key>"
export OPENAI_API_KEY="<your-openai-api-key>" # or ANTHROPIC_API_KEY, GEMINI_API_KEY, etc.

This quickstart uses OpenAI. For other providers, see Integrations.

3. Install SDKs

pip install braintrust openai

For additional auto-instrumentation methods:

4. Auto-instrument

Set the default project for auto-instrumentation:

export BRAINTRUST_DEFAULT_PROJECT="Tracing quickstart"

Create a simple AI application that answers questions.

Python: Call braintrust.auto_instrument() once at the start of your application to enable automatic tracing.
Ruby: With the Gemfile configuration from step 3, all LLM calls are automatically instrumented when your application loads.
Go: Using Orchestrion, all LLM calls are automatically instrumented at compile time.

quickstart.py

import os
import braintrust
from openai import OpenAI

# Enable automatic instrumentation - call this once at startup
braintrust.auto_instrument()

# Create OpenAI client - no wrapping needed!
client = OpenAI(api_key=os.environ.get("OPENAI_API_KEY"))

# All LLM calls are automatically traced
response = client.chat.completions.create(
    model="gpt-5-mini",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is machine learning?"}
    ]
)

print(response.choices[0].message.content)

Run this code:

python quickstart.py

All LLM calls are automatically logged to Braintrust - no manual wrapping required!

5. View traces

In the Braintrust UI, go to the “Tracing quickstart” project and select Logs. You’ll see a trace for each request.Click into any trace to see:

Complete input prompt and model output
Token counts, latency, and cost
Model configuration (temperature, max tokens, etc.)
Request and response metadata

This is the value of observability - you can see every request, identify issues, and understand how your application behaves in production.

Troubleshoot

Not seeing traces in the UI?

Check your API key:

echo $BRAINTRUST_API_KEY

Make sure it’s set and starts with sk-.Verify the project name: Check that BRAINTRUST_DEFAULT_PROJECT is set to “Tracing quickstart” and that you’re looking at the correct project in the UI.Look for errors: Check your console output for any error messages from Braintrust. Common issues:

Invalid API key
Network connectivity issues
Firewall blocking requests to api.braintrust.dev

Python auto-instrumentation not working?

Check braintrust.auto_instrument(): Ensure you call braintrust.auto_instrument() at the start of your application before any AI library imports or client creation.Environment variables: Verify BRAINTRUST_API_KEY and BRAINTRUST_DEFAULT_PROJECT are set in your environment.

Ruby auto-instrumentation not working?

Check Gemfile: Ensure you have gem "braintrust", require: "braintrust/setup" in your Gemfile (note the require: option).Bundler setup: Make sure your application loads Bundler with require 'bundler/setup' and Bundler.require. This is present by default in Rails applications, but may need to be added in Sinatra, Rack, or other frameworks.Environment variables: Verify BRAINTRUST_API_KEY and BRAINTRUST_DEFAULT_PROJECT are set in your environment.

Go auto-instrumentation not working?

Initialize Go module: Ensure you have a go.mod file in your project. If not, run:

go mod init your-project-name

Check Orchestrion installation:

orchestrion version

If this fails, reinstall with go install github.com/DataDog/orchestrion@latest.Verify orchestrion.tool.go: Ensure you have orchestrion.tool.go in your project root with the correct imports:

//go:build tools

package main

import (
	_ "github.com/DataDog/orchestrion"
	_ "github.com/braintrustdata/braintrust-sdk-go/trace/contrib/all"
)

Build with Orchestrion: You must build with orchestrion go build - regular go build won’t instrument your code.Environment variables: Verify BRAINTRUST_API_KEY and BRAINTRUST_DEFAULT_PROJECT are set in your environment.Go version: Requires Go 1.24 or later. Check with go version.

Need help?

Join our Discord
Email us at support@braintrust.dev
Use the Loop feature in the Braintrust UI

Wrap your AI client with Braintrust to trace all LLM requests. Maximum flexibility and control. Works with any integration.If you’re new to Braintrust, sign up free at braintrust.dev.

2. Get API keys

Create API keys for:

Braintrust
Your AI provider or framework (OpenAI, Anthropic, Gemini, etc.)

Set them as environment variables:

export BRAINTRUST_API_KEY="<your-braintrust-api-key>"
export OPENAI_API_KEY="<your-openai-api-key>" # or ANTHROPIC_API_KEY, GEMINI_API_KEY, etc.

This quickstart uses OpenAI. For other providers, see Integrations.

3. Install SDKs

Install the Braintrust SDK and AI provider SDK for your programming language:

# pnpm
pnpm add braintrust openai ts-node
# npm
npm install braintrust openai ts-node

4. Trace LLM calls

Make a simple LLM request and see it automatically traced in Braintrust. Initialize Braintrust and wrap your OpenAI client:

TypeScript & Python: Use wrapOpenAI / wrap_openai wrapper functions
Go: Use the tracing middleware with the OpenAI client
Ruby: Use Braintrust::Trace::OpenAI.wrap to wrap the OpenAI client
Java: Use the tracing interceptor with the OpenAI client
C#: Use BraintrustOpenAI.WrapOpenAI() to wrap the OpenAI client

quickstart.ts

import { initLogger, wrapOpenAI } from "braintrust";
import OpenAI from "openai";

// Initialize Braintrust logger
const logger = initLogger({ projectName: "Tracing quickstart" });
const client = wrapOpenAI(new OpenAI());

// All API calls are automatically logged
const result = await client.responses.create({
  model: "gpt-5-mini",
  input: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "What is machine learning?" },
  ],
});

console.log(result.output_text);

Run this code:

npx ts-node quickstart.ts

All API calls are automatically logged to Braintrust.

5. View traces

In the Braintrust UI, go to the “Tracing quickstart” project and select Logs. You’ll see a trace for each request.Click into any trace to see:

Complete input prompt and model output
Token counts, latency, and cost
Model configuration (temperature, max tokens, etc.)
Request and response metadata

This is the value of observability - you can see every request, identify issues, and understand how your application behaves in production.

Troubleshoot

Not seeing traces in the UI?

Check your API key:

echo $BRAINTRUST_API_KEY

Make sure it’s set and starts with sk-.Verify the project name: Check that you’re looking at the correct project in the UI.Look for errors: Check your console output for any error messages from Braintrust. Common issues:

Invalid API key
Network connectivity issues
Firewall blocking requests to api.braintrust.dev

Traces look incomplete or missing data?

Check wrapper coverage: Make sure you’re wrapping the client before making API calls. Calls made with an unwrapped client won’t be traced.Verify async/await: If using async functions, ensure you’re awaiting API calls properly. Unawaited promises may not be fully traced.Check for errors: If your LLM call throws an error, the trace may be incomplete. Check logs for error messages.

Need help?

Join our Discord
Email us at support@braintrust.dev
Use the Loop feature in the Braintrust UI

Next steps

Explore the full Braintrust workflow
Go deeper with tracing:
- Explore integrations with AI providers, SDKs, and developer tools
- Add custom tracing for application logic
- Capture user feedback like thumbs up/down
- Analyze logs for patterns and issues

Start

Instrument

Observe

Annotate

Evaluate

Deploy

Admin

Best practices

2. Configure MCP

3. Prompt assistant

Troubleshoot

2. Get API keys

3. Install SDKs

4. Auto-instrument

5. View traces

Troubleshoot

2. Get API keys

3. Install SDKs

4. Trace LLM calls

5. View traces

Troubleshoot

Next steps

Start

Instrument

Observe

Annotate

Evaluate

Deploy

Admin

Best practices

​1. Sign up

​2. Configure MCP

​3. Prompt assistant

​Troubleshoot

​1. Sign up

​2. Get API keys

​3. Install SDKs

​4. Auto-instrument

​5. View traces

​Troubleshoot

​1. Sign up

​2. Get API keys

​3. Install SDKs

​4. Trace LLM calls

​5. View traces

​Troubleshoot

​Next steps

1. Sign up

2. Configure MCP

3. Prompt assistant

Troubleshoot

1. Sign up

2. Get API keys

3. Install SDKs

4. Auto-instrument

5. View traces

Troubleshoot

1. Sign up

2. Get API keys

3. Install SDKs

4. Trace LLM calls

5. View traces

Troubleshoot

Next steps