Troubleshooting - Braintrust

Traces are missing or provider calls are not traced

Issue: Your application runs successfully, but LLM calls do not appear in Braintrust.Cause: auto_instrument() must run after init_logger() and before creating AI provider clients. Clients created first may not be patched for tracing.Fix: Initialize Braintrust as early as possible during application startup, then create your provider clients.

import braintrust
from openai import OpenAI

logger = braintrust.init_logger(project="My Project")
braintrust.auto_instrument()

client = OpenAI()

Events are missing from short-lived scripts or jobs

Issue: A script, notebook cell, background job, or CLI finishes but some events never appear in Braintrust.Cause: The SDK buffers logs before sending them. A short-lived process can exit before the buffer flushes.Fix: Call logger.flush() before the process exits.

import braintrust

logger = braintrust.init_logger(project="My Project")
braintrust.auto_instrument()

# Run your work here.

logger.flush()

API key is not picked up

Issue: Logging fails with an authentication error, or traces do not appear in the expected organization.Cause: BRAINTRUST_API_KEY is missing from the environment of the process that runs your Python code.Fix: Set BRAINTRUST_API_KEY in the same shell, service, notebook, container, or deployment environment that starts your app.

export BRAINTRUST_API_KEY="your-api-key"
python app.py

Traces are empty, incomplete, or stuck in progress

Issue: A trace appears but is missing final values, or a manually-created span never finishes.Cause: A process can exit before logs flush, or an exception can bypass the end of a manually-created span.Fix: Prefer traced, which handles span lifecycle for you. If you create spans manually, make sure they are ended and flushed even when an exception occurs.

import braintrust

logger = braintrust.init_logger(project="My Project")

@braintrust.traced
def classify_text(text: str) -> str:
    return "positive"

classify_text("Great result")
logger.flush()