LangChain4j

Setup

Install the Braintrust Java SDK alongside LangChain4j and its OpenAI module, then configure your API keys.

Braintrust instruments LangChain4j 1.8.0 or later and requires Java 17 or later. The OpenAI Responses API models (OpenAiResponsesChatModel, OpenAiResponsesStreamingChatModel) require LangChain4j 1.14.0 or later.

Install packages

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

# LangChain4j and its OpenAI module
implementation 'dev.langchain4j:langchain4j:<version-goes-here>'
implementation 'dev.langchain4j:langchain4j-open-ai:<version-goes-here>'

Set environment variables

.env

OPENAI_API_KEY=<your-openai-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>

Auto-instrumentation

To trace LangChain4j calls without modifying your application code, attach the braintrust-java-agent at JVM startup. The agent intercepts every LangChain4j OpenAI 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

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

Manual instrumentation

To trace LangChain4j calls manually, get an OpenTelemetry instance from Braintrust, then wrap your OpenAI model with BraintrustLangchain.wrap(). The wrap instruments the model in place and returns it, so every call emits a span.

import dev.braintrust.Braintrust;
import dev.braintrust.instrumentation.langchain.v1_14_0.BraintrustLangchain;
import dev.langchain4j.data.message.UserMessage;
import dev.langchain4j.model.chat.ChatModel;
import dev.langchain4j.model.openai.OpenAiChatModel;
import io.opentelemetry.api.OpenTelemetry;

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

        // Build the OpenAI model and instrument it in place
        ChatModel model = BraintrustLangchain.wrap(
            openTelemetry,
            OpenAiChatModel.builder()
                .apiKey(System.getenv("OPENAI_API_KEY"))
                .modelName("gpt-5-mini"));

        // Every chat() call is now traced
        var response = model.chat(UserMessage.from("What is the capital of France?"));
        System.out.println(response.aiMessage().text());
    }
}

OpenAiStreamingChatModel, OpenAiResponsesChatModel, and OpenAiResponsesStreamingChatModel are instrumented the same way: build the model, then pass it (or its builder) to BraintrustLangchain.wrap(). The Responses API models require LangChain4j 1.14.0 or later.

For LangChain4j 1.8.0 through 1.13.x, import dev.braintrust.instrumentation.langchain.v1_8_0.BraintrustLangchain instead. That module traces OpenAiChatModel and OpenAiStreamingChatModel, but not the Responses API models, which do not exist before 1.14.0.

AiServices agents and tools

Pass an AiServices builder to BraintrustLangchain.wrap() to trace a declarative agent. Braintrust instruments the underlying model, every @Tool method, and each service method call, and keeps concurrent tool calls linked to the parent trace.

import dev.braintrust.Braintrust;
import dev.braintrust.instrumentation.langchain.v1_14_0.BraintrustLangchain;
import dev.langchain4j.agent.tool.Tool;
import dev.langchain4j.model.openai.OpenAiResponsesChatModel;
import dev.langchain4j.service.AiServices;
import io.opentelemetry.api.OpenTelemetry;

class LangchainAgentTracing {
    interface Assistant {
        String chat(String userMessage);
    }

    static class WeatherTools {
        @Tool("Get current weather for a location")
        public String getWeather(String location) {
            return String.format("The weather in %s is sunny with 72°F.", location);
        }
    }

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

        // Wrap the AiServices builder: the service, its tools, and the model are all traced
        Assistant assistant = BraintrustLangchain.wrap(
            openTelemetry,
            AiServices.builder(Assistant.class)
                .chatModel(OpenAiResponsesChatModel.builder()
                    .apiKey(System.getenv("OPENAI_API_KEY"))
                    .modelName("gpt-5-mini")
                    .build())
                .tools(new WeatherTools())
                .executeToolsConcurrently());

        System.out.println(assistant.chat("What is the weather in Paris?"));
    }
}

Each service method call is traced as a span named <Interface>.<method> (for example, Assistant.chat), with a child LLM span for the model call and a tool span for each @Tool invocation.

What Braintrust traces

Braintrust traces LangChain4j OpenAI models: OpenAiChatModel and OpenAiStreamingChatModel, plus OpenAiResponsesChatModel and OpenAiResponsesStreamingChatModel on LangChain4j 1.14.0 or later.Braintrust captures:

LLM calls as separate spans, with request messages (or the Responses API input), model name, and serialized generation parameters in span metadata.
Response content, reconstructed by accumulating chunks on streaming calls.
Token usage on LLM spans (prompt_tokens, completion_tokens, tokens, prompt_cached_tokens, completion_reasoning_tokens).
time_to_first_token on streaming responses, measured from the first chunk that carries generated output.
The OpenAI request ID (x-request-id) from the response headers and the response object ID (response_id), so you can correlate a span with OpenAI’s API logs.
AiServices method calls as spans named <Interface>.<method>, with each @Tool invocation as a nested tool span that records its arguments and result.
Server-side tool calls in the Responses API (web search, file search, code interpreter, and MCP) as nested tool spans.
Errors captured on the span.

AI providers

SDKs

Developer tools

Runtime environments

Setup

Auto-instrumentation

Manual instrumentation

AiServices agents and tools

What Braintrust traces

Resources

​Setup

​Auto-instrumentation

​Manual instrumentation

​AiServices agents and tools

​What Braintrust traces

​Resources

Setup

Auto-instrumentation

Manual instrumentation

AiServices agents and tools

What Braintrust traces

Resources