LangChain and LangGraph
Trace LangChain and LangGraph graphs, chains, model calls, and tool steps, with a callback handler in TypeScript or OpenTelemetry in Python.
In TypeScript, the @telemetry-dev/langchain callback handler records LangChain.js and LangGraph.js runs. You add it where you build a graph or a chain, and your agent code does not change. In Python, add an OpenTelemetry instrumentation for LangChain, such as OpenLLMetry, and point its exporter at telemetry.dev.
Graph nodes, chains, model calls, and tool steps arrive as spans, and telemetry.dev computes cost from the token usage on model spans.
TypeScript
The TypeScript setup was checked with @telemetry-dev/langchain 0.1.0, @langchain/core 1.3.5, @langchain/langgraph 1.7.2, langchain 1.6.3, and @langchain/anthropic 1.6.1.
Install
npm install @telemetry-dev/sdk @telemetry-dev/langchainpnpm add @telemetry-dev/sdk @telemetry-dev/langchainyarn add @telemetry-dev/sdk @telemetry-dev/langchainbun add @telemetry-dev/sdk @telemetry-dev/langchain@telemetry-dev/langchain needs @langchain/core 1.x. @telemetry-dev/sdk needs Node.js 20.19.0 or later.
Set the API key
Create a project at telemetry.dev, then create an API key on the project’s Setup page:
export TELEMETRY_DEV_API_KEY="td_live_..."
export OTEL_SERVICE_NAME="support-agent"
Without an API key, init() does nothing and the handler records nothing. Your runs continue as usual.
Trace an agent
Call init() once at startup, then give a TelemetryDevCallbackHandler to the run. LangChain hands the handler down to each child run: graph nodes, model calls, and tools.
This example sends real requests to Anthropic, so Anthropic charges apply. It needs langchain, @langchain/anthropic, zod, and ANTHROPIC_API_KEY:
import { createAgent, tool } from "langchain";
import * as z from "zod";
import { init, shutdown } from "@telemetry-dev/sdk";
import { TelemetryDevCallbackHandler } from "@telemetry-dev/langchain";
init({ serviceName: "langchain-create-agent" });
const getWeather = tool(({ city }) => `It is 21°C and sunny in ${city}.`, {
name: "get_weather",
description: "Get the weather for a city",
schema: z.object({ city: z.string() }),
});
const agent = createAgent({
model: "anthropic:claude-sonnet-4-6",
tools: [getWeather],
systemPrompt: "You are a helpful assistant.",
});
const result = await agent.invoke(
{ messages: [{ role: "user", content: "What is the weather in Accra?" }] },
{
callbacks: [new TelemetryDevCallbackHandler()],
configurable: { thread_id: "thread-1" },
metadata: { userId: "user-1" },
},
);
console.log(result.messages.at(-1)?.text);
await shutdown();
await shutdown() sends the last spans before a short script exits. A long-running server does not need it.
Add the handler to a graph or chain you have
To trace each run of a compiled graph, attach the handler one time:
const agent = graph.compile().withConfig({
callbacks: [new TelemetryDevCallbackHandler()],
});
To trace one run, pass the handler in the config of that run, as in the example above. The same handler operates on chains, for example prompt.pipe(model), and on single model or tool calls.
Check the trace
Open your telemetry.dev project and find the trace. The agent example produces these spans:
| Span | What it is |
|---|---|
invoke_agent LangGraph |
The graph run, with operation invoke_agent and agent name LangGraph |
model_request, tools |
The nodes of the graph |
chat claude-sonnet-4-6 |
Each model call, with model names, provider, messages, finish reason, token usage, and the names of the bound tools |
execute_tool get_weather |
The tool call, with its arguments, call ID, and result |
RunnableLambda |
The routing function of the graph, which picks the next node |
LangChain marks some internal runs as hidden, such as the __start__ step of LangGraph. The handler does not record them, and their child runs go under the nearest recorded run.
If the state of a graph has a messages list, the output of the graph span is the last message, which is the answer of the agent. The trace list shows that answer as the output of the trace.
Each span has langchain.run.id, the ID of its LangChain run. telemetry.dev uses it to show the trace as a LangChain trace.
Sessions, users, and metadata
The handler reads these keys from the metadata of a run:
| Metadata key | Span attribute |
|---|---|
thread_id, sessionId, session_id, or conversation_id |
gen_ai.conversation.id |
userId or user_id |
user.id |
| Any other key from your app | td.metadata.<key>, on the top span only |
LangGraph copies configurable.thread_id into the metadata of each run, so a graph with a checkpointer gets one session for each thread. The handler ignores the metadata keys that LangChain and LangGraph add, such as ls_*, langgraph_*, and checkpoint_ns.
propagateAttributes() from @telemetry-dev/sdk also sets the user and the session. Metadata keys on the run take priority.
Streaming
Model calls that stream, for example through agent.stream(input, { streamMode: "messages" }), also record the time to the first chunk and the time between chunks.
Control captured content
The captureInput, captureOutput, mask, and maxAttributeLength options of init() apply to the messages, inputs, and outputs that the handler records. With capture off, spans keep the span names, models, token usage, and errors. The run names, the tool names, the names of the bound tools, and the metadata of your app are still sent.
Use it next to LangSmith
LangSmith tracing and the telemetry.dev handler are two separate LangChain callback handlers. You can keep LANGSMITH_TRACING=true and add the handler to compare the two products on the same runs.
Do not also instrument the model client
LangChain makes its model calls through the provider SDKs. If you also call instrumentAnthropic() or instrumentOpenAI(), or wrap the client that LangChain uses, each model call is recorded twice: once in the LangChain trace and once as a separate chat trace. The token usage and cost of the project then count these calls two times. Use the handler for LangChain calls, and the provider integrations for model calls outside LangChain.
Spans that other code starts during a LangChain run, such as spans of a wrapped client, do not go under the LangChain spans. They go under the active span of your app, or start their own trace when there is none.
Python
This setup uses OpenLLMetry. It was checked with traceloop-sdk 0.62.4, langchain 1.4.6, langchain-openai 1.7.2, and langgraph.
Install
Use Python 3.10 or later. Install the packages in a virtual environment:
python3 -m venv .venv
. .venv/bin/activate
python -m pip install traceloop-sdk langchain langchain-openai
You do not need a Traceloop account.
Set the API key and exporter
Get a project API key from telemetry.dev. Then set the keys and the OpenLLMetry exporter configuration:
export TELEMETRY_DEV_API_KEY="td_live_..."
export OPENAI_API_KEY="your-openai-api-key"
export TRACELOOP_BASE_URL="https://api.telemetry.dev"
export TRACELOOP_HEADERS="Authorization=Bearer%20$TELEMETRY_DEV_API_KEY"
OpenLLMetry sends traces to https://api.telemetry.dev/v1/traces, and metrics to /v1/metrics. The %20 is the space in Bearer <key>; header values in this variable are URL-encoded. Keep these keys out of version control.
Trace a chain
This example sends one real request to OpenAI, so OpenAI charges apply. Save it as first_trace.py. Call Traceloop.init() before you build the chain:
from traceloop.sdk import Traceloop
from traceloop.sdk.instruments import Instruments
Traceloop.init(
app_name="langchain-first-trace",
resource_attributes={"deployment.environment.name": "development"},
instruments={Instruments.LANGCHAIN},
disable_batch=True,
telemetry_enabled=False,
)
from langchain_core.prompts import ChatPromptTemplate
from langchain_openai import ChatOpenAI
prompt = ChatPromptTemplate.from_messages([("human", "{question}")])
chain = prompt | ChatOpenAI(model="gpt-4o-mini", max_tokens=100)
response = chain.invoke(
{"question": "What is OTLP?"},
config={"run_name": "first-chain"},
)
print(response.content)
Run it:
python first_trace.py
The Traceloop.init() arguments do the following:
app_namebecomes the service name.instruments={Instruments.LANGCHAIN}turns on only the LangChain instrumentation. Leave it out to let OpenLLMetry instrument every library it supports.disable_batch=Truesends each span as it ends, so a short script does not exit before its spans are sent. Leave it out in long-running apps.telemetry_enabled=Falseturns off OpenLLMetry’s anonymous usage reporting to Traceloop. It does not change what your traces contain.
For other settings, see the OpenLLMetry configuration guide.
Trace a LangGraph graph
LangGraph runs on LangChain’s callback system, so the same setup traces graphs. Initialize OpenLLMetry the same way, then build and run the graph:
from typing import TypedDict
from langchain_openai import ChatOpenAI
from langgraph.graph import END, START, StateGraph
class State(TypedDict):
question: str
answer: str
llm = ChatOpenAI(model="gpt-4o-mini")
def answer(state: State) -> dict:
return {"answer": llm.invoke(state["question"]).content}
graph = StateGraph(State)
graph.add_node("answer", answer)
graph.add_edge(START, "answer")
graph.add_edge("answer", END)
print(graph.compile().invoke({"question": "What is OTLP?"}))
Install langgraph first with python -m pip install langgraph.
Check the trace
Open your telemetry.dev project, select the development environment, and find the trace from langchain-first-trace. The chain example produces three spans:
| Span | What it is |
|---|---|
first-chain.workflow |
The chain run, with operation invoke_agent |
execute_task ChatPromptTemplate |
The prompt step |
ChatOpenAI.chat |
The model call, with model names, messages, finish reason, and token usage |
A graph run shows LangGraph.workflow and invoke_agent LangGraph spans, one execute_task span per node, and the model spans inside the nodes.
telemetry.dev computes cost for each model span from its token counts and the model’s price. The workflow and task spans carry no token usage, so they add nothing to the trace’s token or cost totals.
Control captured content
By default, OpenLLMetry records prompts, completions, and chain inputs and outputs in span attributes. To stop recording them, set this variable before you start the app:
export TRACELOOP_TRACE_CONTENT=false
With content off, model spans keep token usage, model names, and other metadata. This is not a general redaction control: chain and tool names, model parameters, and any metadata your app attaches are still exported. To turn content back on for selected calls, see the OpenLLMetry privacy guide.
Send from an existing OpenTelemetry setup
If your app already emits LangChain spans through the OpenTelemetry SDK, point its OTLP/HTTP exporter at telemetry.dev:
export OTEL_EXPORTER_OTLP_ENDPOINT="https://api.telemetry.dev"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer%20$TELEMETRY_DEV_API_KEY"
export OTEL_SERVICE_NAME="your-service-name"
export OTEL_RESOURCE_ATTRIBUTES="deployment.environment.name=production"
These variables configure an exporter only. They do not install or start any LangChain instrumentation. For a new Python app, use the OpenLLMetry setup above.
What telemetry.dev reads
telemetry.dev reads the OpenTelemetry GenAI attributes that @telemetry-dev/langchain and the Python instrumentations send:
- Spans that have a
langchain.run.idattribute, which@telemetry-dev/langchainsets, or whose instrumentation scope name containslangchain, are marked as LangChain spans. - Token usage comes from
gen_ai.usage.input_tokensandgen_ai.usage.output_tokens, or the oldergen_ai.usage.prompt_tokensandgen_ai.usage.completion_tokens. - The model comes from
gen_ai.request.modelandgen_ai.response.model, and the provider fromgen_ai.provider.nameorgen_ai.system. - Messages come from
gen_ai.input.messagesandgen_ai.output.messages, the older indexedgen_ai.prompt.*andgen_ai.completion.*attributes, ortraceloop.entity.inputandtraceloop.entity.output.
For the full list, see span attributes.
Troubleshooting
TypeScript:
- No trace appears. Check that
TELEMETRY_DEV_API_KEYis set in the process that runs the graph and thatinit()runs before the first run. A short script mustawait shutdown()orawait flush()before it exits. - Some runs are missing. The handler records only the runs that have it in their callbacks. Attach it with
withConfig()on each graph or chain that your app starts, or pass it in the config of each run. - Model calls appear twice. Remove
instrumentAnthropic(),instrumentOpenAI(), or the wrapper from the client that LangChain uses. See Do not also instrument the model client.
Python:
- No trace appears. Check that
TRACELOOP_HEADERScontains your key and thatTraceloop.init()runs before LangChain builds the chain. A short script withoutdisable_batch=Truecan exit before its spans are sent. - The trace has no token usage or cost. OpenLLMetry records usage only when the provider response includes it. Cost also needs a model that telemetry.dev has pricing for.
- Using the telemetry.dev OpenAI wrapper instead. Use OpenLLMetry for LangChain. In a test with
langchain-openai1.7.2,instrument_openai()fromtelemetry-dev-openairecorded each request but not the response or token usage of calls made throughChatOpenAI.