Troubleshooting - Braintrust

No traces appear in Braintrust

For manual instrumentation, initialize Braintrust with Braintrust.get() and openTelemetryCreate() before you create your provider client, and make calls on the wrapped client returned by the wrap method:

#skip-compile

var braintrust = Braintrust.get();
var openTelemetry = braintrust.openTelemetryCreate();

// Trace calls on `client`, not on a separately constructed client
OpenAIClient client = BraintrustOpenAI.wrapOpenAI(openTelemetry, OpenAIOkHttpClient.fromEnv());

For auto-instrumentation, confirm the Java Agent is attached at startup (see below).

Auto-instrumentation isn't tracing anything

The Java Agent only instruments when it’s attached via the -javaagent JVM flag at startup. Verify the flag is on the command (or jvmArgs) that actually launches your app.If you run with other Java agents, add the Braintrust agent last in the argument list:

java -javaagent:/path/to/other-agent.jar -javaagent:/path/to/braintrust-java-agent.jar -jar app.jar

Traces are written to the wrong project

Spans route to BRAINTRUST_DEFAULT_PROJECT_NAME, which defaults to default-java-project when unset. Set the project in the environment:

BRAINTRUST_DEFAULT_PROJECT_NAME="My project"

Or pass it through configuration:

#skip-compile

var config = BraintrustConfig.builder()
    .defaultProjectName("My project")
    .build();
var braintrust = Braintrust.get(config);

BRAINTRUST_API_KEY is required error

The SDK reads your API key from the BRAINTRUST_API_KEY environment variable, or from an API key set on the config builder. Set the variable:

BRAINTRUST_API_KEY="your-api-key"

Or provide it explicitly:

#skip-compile

var config = BraintrustConfig.builder()
    .apiKey(System.getenv("BRAINTRUST_API_KEY"))
    .build();
var braintrust = Braintrust.get(config);

Debug setup and API errors

The SDK logs to the dev.braintrust namespace through SLF4J. Enable debug logging to surface configuration and export issues. With slf4j-simple, set:

-Dorg.slf4j.simpleLogger.log.dev.braintrust=DEBUG

You can also enable SDK debug mode and console trace logging via environment variables:

BRAINTRUST_DEBUG=true
BRAINTRUST_ENABLE_TRACE_CONSOLE_LOG=true