LangChain

Setup

Install Braintrust alongside the LangChain JS packages.

pnpm add braintrust @langchain/core@^1 @langchain/openai@^1

npm install braintrust @langchain/core@^1 @langchain/openai@^1

Auto-instrumentation

To trace LangChain calls without modifying your application code, initialize Braintrust normally, then run your app with Braintrust’s import hook to patch @langchain/core at runtime. Requires @langchain/core v0.3.42 or later. The same hook traces LangGraph graphs, which run through the LangChain callback path.

Initialize Braintrust and call LangChain

import { initLogger } from "braintrust";
import { ChatOpenAI } from "@langchain/openai";

initLogger({
  projectName: "My Project",
  apiKey: process.env.BRAINTRUST_API_KEY,
});

const model = new ChatOpenAI({ model: "gpt-5-mini" });

const response = await model.invoke("What is the capital of France?");
console.log(response.content);

Run with the import hook

node --import braintrust/hook.mjs trace-langchain-auto.js

The auto-instrumentation example uses plain JavaScript so node --import can run the file directly. The Braintrust APIs work the same in TypeScript projects. Compile your TypeScript to JavaScript and run the compiled file with the import hook, or run TypeScript directly with a TypeScript loader.

If you’re using a bundler, see Trace LLM calls for plugin and loader setup.

Manual instrumentation

To trace LangChain calls manually, attach BraintrustLangChainCallbackHandler to each call’s callbacks option yourself.

import { ChatOpenAI } from "@langchain/openai";
import { BraintrustLangChainCallbackHandler, initLogger } from "braintrust";

initLogger({
  projectName: "My Project",
  apiKey: process.env.BRAINTRUST_API_KEY,
});

const handler = new BraintrustLangChainCallbackHandler();

async function main() {
  const model = new ChatOpenAI({ modelName: "gpt-5-mini" });

  await model.invoke("What is the capital of France?", {
    callbacks: [handler],
  });
}

main();

Run it:

npx ts-node trace-langchain.ts

Capture controls

LangChain spans record chain inputs and outputs, model inputs and outputs, and token usage by default. Capture controls omit any of these from LangChain and LangGraph spans. Spans, timing (including time_to_first_token), errors, and metadata such as the model name are still recorded. Requires braintrust v3.44.0 or later.Each option defaults to true. Set an option to false to omit that data:

Option	Omits
`captureChainInputs`	Chain inputs, recorded as span input when a chain starts and repeated in span metadata when it ends or fails
`captureChainOutputs`	Chain outputs, including the tool calls an agent decides to make
`captureModelInputs`	Prompts and chat messages sent to LLM and chat model calls
`captureModelOutputs`	LLM and chat model results
`captureModelTokenUsage`	Token usage metrics, including cached and reasoning tokens

With auto-instrumentation, pass the options as langchain to configureInstrumentation(). Import configureInstrumentation() from braintrust/instrumentation and call it in a separate file:

capture-config.mjs

import { configureInstrumentation } from "braintrust/instrumentation";

configureInstrumentation({
  langchain: {
    captureModelInputs: false,
    captureModelOutputs: false,
  },
});

Load the file before the hook:

node --import ./capture-config.mjs --import braintrust/hook.mjs trace-langchain-auto.js

With manual instrumentation, pass the same options to the handler:

const handler = new BraintrustLangChainCallbackHandler({
  captureModelInputs: false,
  captureModelOutputs: false,
});

Capture controls apply only to LangChain and LangGraph spans. If you also trace the model provider, such as with OpenAI or Anthropic auto-instrumentation, the provider’s spans nested under the LangChain spans still record model inputs, outputs, and token usage.

What Braintrust traces

Braintrust captures:

LLM and chat model calls, chains, agents, tools, and retrievers as separate spans, with inputs and outputs preserved
Token usage on LLM spans (prompt_tokens, completion_tokens, total_tokens, prompt_cached_tokens, prompt_cache_creation_tokens, completion_reasoning_tokens)
time_to_first_token on streaming responses, captured on the first new-token callback
Model name and serialized invocation parameters in span metadata
Service tiers on LLM spans, as requested_service_tier metadata when the invocation parameters set a tier and served_service_tier metadata when the model response reports one
Errors from any callback captured on the span

AI providers

SDKs

Developer tools

Runtime environments

Setup

Auto-instrumentation

Manual instrumentation

Capture controls

What Braintrust traces

Tracing resources