Spring AI

Tracing

To trace Spring AI with Braintrust’s Java SDK, use auto-instrumentation or manual instrumentation. Auto-instrumentation is the recommended path for most users.

Auto-instrumentation
Manual instrumentation

The Braintrust Java agent instruments Spring AI chat models at JVM startup, so no changes to your application code are required.

Setup

Install the Braintrust Java SDK alongside the Spring AI module for each provider you use, then configure your API keys.

Braintrust instruments Spring AI 1.0.0 to 2.0.0 and requires Java 17 or later. Calls made with an unsupported Spring AI version still run, but produce no spans.

Install packages

# add to build.gradle dependencies{} block
implementation 'dev.braintrust:braintrust-sdk-java:<version-goes-here>'

# add the Spring AI module for each provider you use
implementation 'org.springframework.ai:spring-ai-openai:<version-goes-here>'
implementation 'org.springframework.ai:spring-ai-anthropic:<version-goes-here>'

Set environment variables

.env

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

# For organizations on the EU data plane, use https://api-eu.braintrust.dev
# For self-hosted deployments, use your data plane URL
# BRAINTRUST_API_URL=<your-braintrust-api-url>

Trace your application

To trace Spring AI calls without modifying your application code, attach the braintrust-java-agent at JVM startup. The agent intercepts every Spring AI chat model build and applies Braintrust instrumentation automatically.

Add the agent dependency

The agent is a separate artifact from the SDK. Add it as its own dependency configuration:

# build.gradle
configurations {
    braintrustAgent
}

dependencies {
    braintrustAgent 'dev.braintrust:braintrust-java-agent:+'
}

tasks.withType(JavaExec).configureEach {
    jvmArgs "-javaagent:${configurations.braintrustAgent.asPath}"
}

Run your app

./gradlew run

Spring AI chat model builds in your application code are now intercepted automatically. No call to BraintrustSpringAI.wrap() is required. For Spring Boot, use ./gradlew bootRun instead.

What Braintrust traces

Braintrust traces each Spring AI chat model call that routes to a supported provider backend. Spring AI 2.x delegates HTTP to the official OpenAI and Anthropic Java SDKs, so spans carry the same fields as those integrations.Braintrust captures:

Chat model call spans for OpenAiChatModel (OpenAI backend) and AnthropicChatModel (Anthropic backend), with the request messages, model, and parameters.
Response content for each call.
Token usage metrics, including prompt and completion tokens.

Tracing resources

To trace Spring AI calls yourself, wrap a built chat model with BraintrustSpringAI.wrap(). Once wrapped, every call() on that model emits a span.

Setup

Install the Braintrust Java SDK alongside the Spring AI module for each provider you use, then configure your API keys.

Braintrust instruments Spring AI 1.0.0 to 2.0.0 and requires Java 17 or later. Calls made with an unsupported Spring AI version still run, but produce no spans.

Install packages

# add to build.gradle dependencies{} block
implementation 'dev.braintrust:braintrust-sdk-java:<version-goes-here>'

# add the Spring AI module for each provider you use
implementation 'org.springframework.ai:spring-ai-openai:<version-goes-here>'
implementation 'org.springframework.ai:spring-ai-anthropic:<version-goes-here>'

Set environment variables

.env

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

# For organizations on the EU data plane, use https://api-eu.braintrust.dev
# For self-hosted deployments, use your data plane URL
# BRAINTRUST_API_URL=<your-braintrust-api-url>

Trace your application

To trace Spring AI calls manually, build your chat model as usual, then wrap it with BraintrustSpringAI.wrap(), which instruments the model in place and returns it so every call() emits a span.

import dev.braintrust.Braintrust;
import dev.braintrust.instrumentation.springai.v2_0_0.BraintrustSpringAI;
import io.opentelemetry.api.OpenTelemetry;
import org.springframework.ai.chat.prompt.Prompt;
import org.springframework.ai.openai.OpenAiChatModel;
import org.springframework.ai.openai.OpenAiChatOptions;

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

        // Build your Spring AI chat model as usual
        var chatModel = OpenAiChatModel.builder()
            .options(OpenAiChatOptions.builder()
                .apiKey(System.getenv("OPENAI_API_KEY"))
                .model("gpt-5-mini")
                .build())
            .build();

        // Instrument the chat model in place
        var model = BraintrustSpringAI.wrap(openTelemetry, chatModel);

        // Every call() is now traced
        var response = model.call(new Prompt("What is machine learning?"));
    }
}

AnthropicChatModel is instrumented the same way: build it, then pass it to BraintrustSpringAI.wrap().

Spring AI 2.x builds its provider client inside build(), so you wrap the finished chat model. For Spring AI 1.x, import dev.braintrust.instrumentation.springai.v1_0_0.BraintrustSpringAI and wrap the builder before calling .build() instead.

Async and streaming calls are traced, and each LLM span is parented to the caller’s active span even when the request runs on a different thread. BraintrustSpringAI.wrap() is idempotent and returns the same model instance. Only OpenAiChatModel and AnthropicChatModel are instrumented; other Spring AI chat models are logged and skipped.

What Braintrust traces

Chat model call spans for OpenAiChatModel (OpenAI backend) and AnthropicChatModel (Anthropic backend), with the request messages, model, and parameters.
Response content for each call.
Token usage metrics, including prompt and completion tokens.

AI providers

SDKs

Developer tools

Tracing

Setup

Trace your application

What Braintrust traces

Tracing resources

Setup

Trace your application

What Braintrust traces

Tracing resources

​Tracing

​Setup

​Trace your application

​What Braintrust traces

​Tracing resources

​Setup

​Trace your application

​What Braintrust traces

​Tracing resources

Tracing

Setup

Trace your application

What Braintrust traces

Tracing resources

Setup

Trace your application

What Braintrust traces

Tracing resources