> ## Documentation Index
> Fetch the complete documentation index at: https://braintrust.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Install and instrument

> Install the Java SDK, set an API key, and configure tracing by hand.

<Note>To use an agent for automatic setup, see the [Quickstart](/sdks/java/quickstart).</Note>

## Sign up

If you don't have a Braintrust account, sign up for free at [braintrust.dev](https://www.braintrust.dev/signup).

## Install the SDK

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

<CodeGroup>
  ```groovy build.gradle theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  dependencies {
      implementation "dev.braintrust:braintrust-sdk-java:<version>"
  }
  ```

  ```xml pom.xml theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  <dependency>
      <groupId>dev.braintrust</groupId>
      <artifactId>braintrust-sdk-java</artifactId>
      <version>VERSION</version>
  </dependency>
  ```
</CodeGroup>

## 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](https://www.braintrust.dev/app/~/settings/api-keys) and set it as an environment variable, along with the project to log to:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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.

<Note>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](#supported-provider-versions).</Note>

<Tabs defaultTabIndex={0} sync={false} className="tabs-border">
  <Tab title="Auto-instrumentation">
    <Steps>
      <Step title="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`:

        ```groovy build.gradle theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        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}",
            ]
        }
        ```
      </Step>

      <Step title="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:

        ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        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.
      </Step>

      <Step title="Find your AI provider">
        To learn more about what gets traced, find your AI provider in [SDK integrations](/sdks/java/sdk-integrations).
      </Step>
    </Steps>
  </Tab>

  <Tab title="Manual instrumentation">
    <Steps>
      <Step title="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](/sdks/java/sdk-integrations).

        ```java theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        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);
            }
        }
        ```
      </Step>

      <Step title="Create custom spans">
        The Java SDK uses OpenTelemetry. Wrap application work in spans to nest traced AI calls under your own operations:

        ```java #skip-compile theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        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();
        }
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Verify tracing

Run your app and make an AI call. A trace will show up in your [Braintrust Logs](https://www.braintrust.dev/app/~/logs), usually within seconds.

<Check>If traces appear in Braintrust, you've successfully set up the SDK.</Check>

If your traces don't appear in Braintrust, see [Troubleshooting](/sdks/java/troubleshooting).

## Next steps

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

* [Instrument](/instrument) — trace LLM calls and application logic
* [Observe](/observe) — search and analyze production traces
* [Annotate](/annotate) — label traces and build datasets
* [Evaluate](/evaluate) — measure quality and catch regressions
* [Deploy](/deploy) — ship to production with the AI gateway