Trace LLM calls

Braintrust traces your LLM calls with auto-instrumentation. In most languages, you enable tracing once at startup and every request to a supported AI provider or framework is logged — inputs, outputs, model parameters, latency, token usage, and costs — with no per-call code changes. For languages that don’t yet support auto-instrumentation, you can wrap each client instance to get the same coverage. The examples on this page use OpenAI, but Braintrust supports many providers and frameworks.

Braintrust’s CLI and MCP server can help you instrument your code.

Auto-instrumentation

Auto-instrumentation patches supported AI libraries at startup so every LLM call is captured without wrapping individual clients. This is the recommended way to set up tracing. If you’re using Java or .NET, or if auto-instrumentation isn’t working in your environment, try wrap functions instead.

TypeScript
Python
Ruby
Go

Install the dependencies:

npm install braintrust openai

This example traces a single OpenAI call:

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

// Call once at startup — all LLM calls are traced automatically
initLogger({
  apiKey: process.env.BRAINTRUST_API_KEY,
  projectName: "My Project (TypeScript)",
});

const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
const response = await client.responses.create({
  model: "gpt-5-mini",
  input: "What is the capital of France?",
});

Run with the --import flag to enable auto-instrumentation:

node --import braintrust/hook.mjs app.js

Using a bundler?

If you’re using a bundler (Vite, Webpack, esbuild, Rollup) or a framework that uses one (Next.js, Nuxt, SvelteKit), use the appropriate bundler plugin (included in Braintrust’s JavaScript SDK) instead of the --import flag.

Node.js version requirements

Requires Node.js 18.19.0+ or 20.6.0+ for --import flag support. Check with node --version.

Install the dependencies:

pip install braintrust openai

This example traces a single OpenAI call:

import os
import braintrust
from openai import OpenAI

# Call once at startup — all LLM calls are traced automatically
braintrust.auto_instrument()
braintrust.init_logger(
    api_key=os.environ["BRAINTRUST_API_KEY"],
    project="My Project (Python)",
)

client = OpenAI(api_key=os.environ.get("OPENAI_API_KEY"))
response = client.responses.create(
    model="gpt-5-mini",
    input="What is the capital of France?",
)

Add the Braintrust gem to your Gemfile, using the braintrust/setup require to enable auto-instrumentation on load:

# Gemfile
gem "braintrust", require: "braintrust/setup"
gem "ruby-openai"

Install the dependencies:

bundle install

This example traces a single OpenAI call:

require 'bundler/setup'
Bundler.require

Braintrust.init(
  api_key: ENV['BRAINTRUST_API_KEY'],
  default_project: 'My Project (Ruby)'
)

client = OpenAI::Client.new(access_token: ENV['OPENAI_API_KEY'])
response = client.responses.create(
  parameters: {
    model: 'gpt-5-mini',
    input: 'What is the capital of France?'
  }
)

Go uses Orchestrion for compile-time auto-instrumentation:

go install github.com/DataDog/orchestrion@latest

Create orchestrion.tool.go in your project root:

//go:build tools

package main

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

This example traces a single OpenAI call. The Go SDK sends traces to Braintrust via OpenTelemetry, so you create a TracerProvider and pass it to Braintrust:

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/braintrustdata/braintrust-sdk-go"
	"github.com/openai/openai-go"
	"github.com/openai/openai-go/option"
	"github.com/openai/openai-go/responses"
	"go.opentelemetry.io/otel"
	sdktrace "go.opentelemetry.io/otel/sdk/trace"
)

func main() {
	tp := sdktrace.NewTracerProvider()
	defer tp.Shutdown(context.Background())
	otel.SetTracerProvider(tp)

	_, err := braintrust.New(tp,
		braintrust.WithProject("My Project (Go)"),
		braintrust.WithAPIKey(os.Getenv("BRAINTRUST_API_KEY")),
	)
	if err != nil {
		log.Fatal(err)
	}

	client := openai.NewClient(option.WithAPIKey(os.Getenv("OPENAI_API_KEY")))

	response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
		Model: "gpt-5-mini",
		Input: responses.ResponseNewParamsInputUnion{OfString: openai.String("What is the capital of France?")},
	})
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(response.OutputText())
}

Resolve dependencies and build with Orchestrion to enable auto-instrumentation:

go mod tidy
orchestrion go build -o myapp
./myapp

Run your app and check Braintrust — your LLM calls will appear in the project logs.

Streaming responses are fully supported — Braintrust automatically collects streamed chunks and logs the complete response as a single span.

Wrap functions

Wrap functions let you explicitly instrument individual client instances. This is an alternative to auto-instrumentation, useful if you prefer explicit control or if auto-instrumentation isn’t supported by the libraries you’re using. Unlike auto-instrumentation, you need to wrap each client instance in your application.

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

initLogger({
  apiKey: process.env.BRAINTRUST_API_KEY,
  projectName: "My Project (TypeScript)",
});

// Wrap the OpenAI client to trace all calls
const client = wrapOpenAI(new OpenAI({ apiKey: process.env.OPENAI_API_KEY }));
const response = await client.responses.create({
  model: "gpt-5-mini",
  input: "What is the capital of France?",
});

import os
import braintrust
from braintrust import wrap_openai
from openai import OpenAI

braintrust.init_logger(
    api_key=os.environ["BRAINTRUST_API_KEY"],
    project="My Project (Python)",
)

# Wrap the OpenAI client to trace all calls
client = wrap_openai(OpenAI(api_key=os.environ.get("OPENAI_API_KEY")))
response = client.responses.create(
    model="gpt-5-mini",
    input="What is the capital of France?",
)

Use Braintrust.instrument! with a target: to instrument a specific client instance:

require 'braintrust'
require 'openai'

Braintrust.init(
  api_key: ENV['BRAINTRUST_API_KEY'],
  default_project: 'My Project (Ruby)',
  auto_instrument: false
)

# Wrap a specific OpenAI client to trace all calls
client = OpenAI::Client.new(access_token: ENV['OPENAI_API_KEY'])
Braintrust.instrument!(:ruby_openai, target: client)

response = client.responses.create(
  parameters: {
    model: 'gpt-5-mini',
    input: 'What is the capital of France?'
  }
)

Use :openai if you’re using the openai gem, or :ruby_openai for the ruby-openai gem.

The Go SDK provides tracing middleware that you pass to your AI provider’s client constructor:

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/braintrustdata/braintrust-sdk-go"
	traceopenai "github.com/braintrustdata/braintrust-sdk-go/trace/contrib/openai"
	"github.com/openai/openai-go"
	"github.com/openai/openai-go/option"
	"github.com/openai/openai-go/responses"
	"go.opentelemetry.io/otel"
	sdktrace "go.opentelemetry.io/otel/sdk/trace"
)

func main() {
	tp := sdktrace.NewTracerProvider()
	defer tp.Shutdown(context.Background())
	otel.SetTracerProvider(tp)

	_, err := braintrust.New(tp,
		braintrust.WithProject("My Project (Go)"),
		braintrust.WithAPIKey(os.Getenv("BRAINTRUST_API_KEY")),
	)
	if err != nil {
		log.Fatal(err)
	}

	// Create an OpenAI client with tracing middleware
	client := openai.NewClient(
		option.WithAPIKey(os.Getenv("OPENAI_API_KEY")),
		option.WithMiddleware(traceopenai.NewMiddleware()),
	)

	response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{
		Model: "gpt-5-mini",
		Input: responses.ResponseNewParamsInputUnion{OfString: openai.String("What is the capital of France?")},
	})
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(response.OutputText())
}

# build.gradle
dependencies {
    implementation 'dev.braintrust:braintrust-sdk-java:+'
    implementation 'com.openai:openai-java:+'
}

import dev.braintrust.Braintrust;
import dev.braintrust.config.BraintrustConfig;
import dev.braintrust.instrumentation.openai.BraintrustOpenAI;
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.chat.completions.ChatCompletionCreateParams;
import com.openai.models.chat.completions.ChatCompletionUserMessageParam;

var config = BraintrustConfig.builder()
    .apiKey(System.getenv("BRAINTRUST_API_KEY"))
    .defaultProjectName("My Project (Java)")
    .build();
var braintrust = Braintrust.get(config);
var openTelemetry = braintrust.openTelemetryCreate();

// Wrap the OpenAI client to trace all calls
OpenAIClient openaiClient = OpenAIOkHttpClient.builder()
    .apiKey(System.getenv("OPENAI_API_KEY"))
    .build();
OpenAIClient client = BraintrustOpenAI.wrapOpenAI(openTelemetry, openaiClient);

var params = ChatCompletionCreateParams.builder()
    .model("gpt-5-mini")
    .addMessage(ChatCompletionUserMessageParam.builder()
        .content("What is the capital of France?")
        .build())
    .build();
var response = client.chat().completions().create(params);

dotnet add package Braintrust.Sdk
dotnet add package Braintrust.Sdk.OpenAI
dotnet add package OpenAI

using System;
using Braintrust.Sdk;
using Braintrust.Sdk.Config;
using Braintrust.Sdk.OpenAI;
using OpenAI;
using OpenAI.Chat;

var config = BraintrustConfig.Of(
    ("BRAINTRUST_API_KEY", Environment.GetEnvironmentVariable("BRAINTRUST_API_KEY")),
    ("BRAINTRUST_DEFAULT_PROJECT_NAME", "My Project (.NET)"));
var braintrust = Braintrust.Sdk.Braintrust.Get(config);
var activitySource = braintrust.GetActivitySource();

// Wrap the OpenAI client to trace all calls
var openAIClient = BraintrustOpenAI.WrapOpenAI(
    activitySource, Environment.GetEnvironmentVariable("OPENAI_API_KEY"));

var chatClient = openAIClient.GetChatClient("gpt-5-mini");
var response = await chatClient.CompleteChatAsync(
    new ChatMessage[]
    {
        new UserChatMessage("What is the capital of France?")
    });

Braintrust gateway

The Braintrust gateway provides a unified OpenAI-compatible API for accessing models from many providers. When you call a model through the gateway, your requests are automatically traced — no SDK instrumentation or wrap functions needed. The gateway also provides automatic caching and observability across providers.

Supported libraries

To help you log traces, Braintrust’s SDKs support auto-instrumentation and wrap functions for many common libraries. Select a language to get started.

Library	Min. library version	Setup guide
openai	4.0.0	OpenAI
@anthropic-ai/sdk	0.60.0	Anthropic
@google/genai	1.0.0	Gemini
ai (Vercel AI SDK)	3.0.0	Vercel AI SDK
@anthropic-ai/claude-agent-sdk	0.1.0	Claude Agent SDK
@openrouter/sdk	0.9.11	—

Library	Min. library version	Setup guide
openai	1.71.0	OpenAI
anthropic	0.48.0	Anthropic
google-genai	—	Gemini
claude-agent-sdk	0.1.10	Claude Agent SDK
litellm	1.74.0	LiteLLM
google-adk	1.14.1	Google ADK
pydantic-ai	0.1.9	Pydantic AI
agno	2.1.0	Agno
dspy	—	DSPy

Library	Min. library version	Setup guide
openai	0.1.0	OpenAI
ruby-openai	7.0.0	OpenAI
anthropic	0.3.0	Anthropic
ruby_llm	1.8.0	RubyLLM

Library	Min. library version	Setup guide
github.com/openai/openai-go	1.12.0	OpenAI
github.com/anthropics/anthropic-sdk-go	1.4.0	Anthropic
google.golang.org/genai	1.40.0	Gemini
google.golang.org/adk	0.4.0	Google ADK
github.com/tmc/langchaingo	0.1.13	LangChain
github.com/sashabaranov/go-openai	1.41.2	OpenAI

Library	Min. library version	Setup guide
com.openai:openai-java	2.8.0	OpenAI
com.anthropic:anthropic-java	2.2.0	Anthropic
com.google.genai:google-genai	1.18.0	Gemini
dev.langchain4j:langchain4j	1.8.0	LangChain

Library	Min. library version	Setup guide
OpenAI	2.6.0	OpenAI
Anthropic	12.5.0	Anthropic

Braintrust also integrates with frameworks like LangChain, LangGraph, CrewAI, LlamaIndex, Mastra, and OpenTelemetry, which require framework-specific setup such as callback handlers or OpenTelemetry configuration. See Integrations.

Next steps

Trace application logic to trace non-LLM code like data retrieval, tool calls, and business logic
Advanced tracing for distributed tracing, custom rendering, and more
Explore integrations with AI providers, SDKs, and developer tools

Start

Instrument

Observe

Annotate

Evaluate

Deploy

Admin

Best practices

Auto-instrumentation

Wrap functions

Braintrust gateway

Supported libraries

Next steps

Start

Instrument

Observe

Annotate

Evaluate

Deploy

Admin

Best practices

​Auto-instrumentation

​Wrap functions

​Braintrust gateway

​Supported libraries

​Next steps

Auto-instrumentation

Wrap functions

Braintrust gateway

Supported libraries

Next steps