DSPy

Setup

Install the Braintrust and DSPy packages, then set your API keys. Requires dspy v2.6.0 or later.

Install packages

uv add braintrust dspy

pip install braintrust dspy

Set environment variables

.env

BRAINTRUST_API_KEY=<your-braintrust-api-key>
OPENAI_API_KEY=<your-openai-api-key>

Auto-instrumentation

To trace DSPy runs without modifying your application code, call braintrust.auto_instrument() before you configure DSPy. It patches dspy.configure() so Braintrust’s DSPy callback is attached automatically.

import os

import braintrust

braintrust.auto_instrument()
braintrust.init_logger(
    api_key=os.environ["BRAINTRUST_API_KEY"],
    project="dspy-example",  # Replace with your project name
)

import dspy

lm = dspy.LM("openai/gpt-5-mini")
dspy.configure(lm=lm)

cot = dspy.ChainOfThought("question -> answer")
result = cot(question="What is the capital of France?")
print(result.answer)

To patch only DSPy instead of enabling all supported Python integrations, use patch_dspy().

import os

from braintrust import init_logger
from braintrust.integrations.dspy import patch_dspy

init_logger(
    api_key=os.environ["BRAINTRUST_API_KEY"],
    project="dspy-example",  # Replace with your project name
)
patch_dspy()

import dspy

lm = dspy.LM("openai/gpt-5-mini")
dspy.configure(lm=lm)

predict = dspy.Predict("question -> answer")
result = predict(question="What is 2 + 2?")
print(result.answer)

Manual instrumentation

To trace DSPy runs manually, attach BraintrustDSpyCallback() yourself when you configure DSPy. For detailed LiteLLM token and cost spans, patch LiteLLM before importing DSPy.

import os

from braintrust import init_logger
from braintrust.integrations.dspy import BraintrustDSpyCallback
from braintrust.integrations.litellm import patch_litellm

patch_litellm()

import dspy

init_logger(
    api_key=os.environ["BRAINTRUST_API_KEY"],
    project="dspy-example",  # Replace with your project name
)

# Disable DSPy's disk cache if you want every LiteLLM call to be traced.
dspy.configure_cache(enable_disk_cache=False, enable_memory_cache=True)

lm = dspy.LM("openai/gpt-5-mini")
dspy.configure(lm=lm, callbacks=[BraintrustDSpyCallback()])

cot = dspy.ChainOfThought("question -> answer")
result = cot(question="What is the capital of France?")
print(result.answer)

What Braintrust traces

A DSPy execution appears as a parent module span with child spans for adapter work and model calls:

trace-dspy-auto
└── dspy.module.ChainOfThought
    ├── dspy.adapter.format
    ├── dspy.lm
    └── dspy.adapter.parse

Braintrust captures:

Module spans (dspy.module.Predict, dspy.module.ChainOfThought, and other module classes), with module inputs, the module class, and outputs.
Adapter formatting and parsing spans (dspy.adapter.format and dspy.adapter.parse), with inputs, the adapter class, and outputs.
LLM call spans (dspy.lm), with inputs, the model and provider, request parameters (temperature, max_tokens, top_p, top_k, stop), outputs, and latency.
Tool spans (named after the invoked tool), with tool inputs and outputs.
Evaluation spans (dspy.evaluate), with evaluation inputs, the metric name, thread count, outputs, and score metrics (accuracy, score, total, correct).
Additional LiteLLM completion spans (Completion), with token usage and latency metrics, when you patch LiteLLM.

AI providers

SDKs

Developer tools

Setup

Auto-instrumentation

Manual instrumentation

What Braintrust traces

Resources

​Setup

​Auto-instrumentation

​Manual instrumentation

​What Braintrust traces

​Resources

Setup

Auto-instrumentation

Manual instrumentation

What Braintrust traces

Resources