Install and instrument

To use an agent for automatic setup, see the Quickstart.

If you don’t have a Braintrust account, sign up for free at braintrust.dev.

Install the SDK

The Braintrust Java SDK requires Java 17 or later. Add the SDK to your build:

dependencies {
    implementation "dev.braintrust:braintrust-sdk-java:<version>"
}

Supported provider versions

Braintrust instruments each AI provider’s official Java client. Add the client your app uses at one of these minimum versions. If you use an earlier version, the client is not instrumented: your calls still run, but no spans are produced. This applies to both auto-instrumentation and the manual wrappers.

Provider	Client	Minimum version
OpenAI	`com.openai:openai-java`	2.15.0
Anthropic	`com.anthropic:anthropic-java`	2.2.0
Google GenAI (Gemini)	`com.google.genai:google-genai`	1.18.0
LangChain4j	`dev.langchain4j:langchain4j`	1.8.0
AWS Bedrock	`software.amazon.awssdk:bedrockruntime`	2.42.36
Spring AI	`org.springframework.ai:spring-ai-*`	1.0.0 (up to 2.0.0)

Set an API key

Create an API key in API key settings and set it as an environment variable, along with the project to log to:

BRAINTRUST_API_KEY="your-api-key"
BRAINTRUST_DEFAULT_PROJECT_NAME="My project"

The SDK reads BRAINTRUST_API_KEY from the environment. Keep it out of version control.

Configure tracing

There are two ways to instrument your app:

Auto-instrumentation (recommended): Attach the Braintrust Java Agent at JVM startup to trace supported AI clients with no code changes.
Manual instrumentation: Initialize Braintrust yourself and wrap specific provider clients. Use this approach if you need precise control or custom spans.

Instrumentation only applies to supported provider client versions. If your client is older than the minimum, your calls still run but produce no spans. See Supported provider versions.

Auto-instrumentation
Manual instrumentation

Add the Braintrust Java Agent

The agent is a separate artifact from the SDK. Add it as its own dependency configuration so you can reference its JAR path. This Spring Boot and Gradle example wires it into bootRun:

build.gradle

configurations {
    btAgent
}
dependencies {
    btAgent "dev.braintrust:braintrust-java-agent:<version>"
}
bootRun {
    jvmArgs = [
        // If you run with other Java agents, add the Braintrust agent last.
        "-javaagent:${configurations.btAgent.singleFile.absolutePath}",
    ]
}

Run your app with the agent

Auto-instrumentation only works when the agent is attached via the -javaagent JVM flag. Wire it into the launch path your team and CI use, for example:

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

The agent instruments supported AI clients and frameworks at startup, so no code changes are required.

Find your AI provider

To learn more about what gets traced, find your AI provider in SDK integrations.

Initialize Braintrust and wrap your client

Initialize Braintrust, create an OpenTelemetry instance, and wrap your provider client. The example below uses OpenAI; for other providers, see SDK integrations.

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

class OpenAITracing {
    public static void main(String[] args) {
        var braintrust = Braintrust.get();
        var openTelemetry = braintrust.openTelemetryCreate();

        // Wrap the OpenAI client with Braintrust instrumentation
        OpenAIClient client = BraintrustOpenAI.wrapOpenAI(openTelemetry, OpenAIOkHttpClient.fromEnv());

        // All API calls are automatically logged
        var request = ChatCompletionCreateParams.builder()
            .model(ChatModel.GPT_4O_MINI)
            .addSystemMessage("You are a helpful assistant.")
            .addUserMessage("What is machine learning?")
            .temperature(0.0)
            .build();

        var result = client.chat().completions().create(request);
    }
}

Create custom spans

The Java SDK uses OpenTelemetry. Wrap application work in spans to nest traced AI calls under your own operations:

#skip-compile

var tracer = openTelemetry.getTracer("my-app");
var span = tracer.spanBuilder("process-request").startSpan();
try (var scope = span.makeCurrent()) {
    span.setAttribute("user.id", userId);
    var output = answerQuestion("Write a haiku about evals");
    span.setAttribute("app.output", output);
} finally {
    span.end();
}

Verify tracing

Run your app and make an AI call. A trace will show up in your Braintrust Logs, usually within seconds.

If traces appear in Braintrust, you’ve successfully set up the SDK.

If your traces don’t appear in Braintrust, see Troubleshooting.

Next steps

Learn more about using the SDK to observe, evaluate, and improve your AI application:

Instrument — trace LLM calls and application logic
Observe — search and analyze production traces
Annotate — label traces and build datasets
Evaluate — measure quality and catch regressions
Deploy — ship to production with the AI gateway

​Sign up

​Install the SDK

​Supported provider versions

​Set an API key

​Configure tracing

​Verify tracing

​Next steps

Sign up

Install the SDK

Supported provider versions

Set an API key

Configure tracing

Verify tracing

Next steps