> ## Documentation Index > Fetch the complete documentation index at: https://docs.braintrust.dev/llms.txt > Use this file to discover all available pages before exploring further. # LangChain4j > Trace LangChain4j calls in Braintrust to debug prompts, evaluate models, and monitor production usage [LangChain4j](https://docs.langchain4j.dev/) is a library for building LLM-powered applications in Java. It is an independent project designed around Java conventions, not a port of Python LangChain. Braintrust traces LangChain4j applications that call OpenAI, including the OpenAI Responses API. **Java** ## Setup Install the Braintrust Java SDK alongside LangChain4j and its OpenAI module, then configure your API keys. > [!NOTE] > > 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. **1. Install packages** ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} # add to build.gradle dependencies{} block implementation 'dev.braintrust:braintrust-sdk-java:' # LangChain4j and its OpenAI module implementation 'dev.langchain4j:langchain4j:' implementation 'dev.langchain4j:langchain4j-open-ai:' ``` **2. Set environment variables** ```bash title=".env" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} OPENAI_API_KEY= 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= ``` ## Auto-instrumentation To trace LangChain4j calls without modifying your application code, attach the [`braintrust-java-agent`](https://docs.braintrust.dev/instrument/trace-llm-calls#auto-instrumentation) at JVM startup. The agent intercepts every LangChain4j OpenAI model build and applies Braintrust instrumentation automatically. **1. Add the agent dependency** The agent is a separate artifact from the SDK. Add it as its own dependency configuration: ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} # build.gradle configurations { braintrustAgent } dependencies { braintrustAgent 'dev.braintrust:braintrust-java-agent:+' } tasks.withType(JavaExec).configureEach { jvmArgs "-javaagent:${configurations.braintrustAgent.asPath}" } ``` **2. Run your app** ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} ./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. ```java Java #skip-compile theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} 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. > [!NOTE] > > 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. ```java Java #skip-compile theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} 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 `.` (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 `.`, 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. ## Resources * [Braintrust Java SDK](https://github.com/braintrustdata/braintrust-sdk-java) * [LangChain4j examples](https://github.com/braintrustdata/braintrust-sdk-java/tree/main/examples) * [LangChain4j documentation](https://docs.langchain4j.dev/) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.