Skip to content
telemetry.dev
Esc
↑↓navigate↵open⌘Jpreview
On this page

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/langchain
pnpm add @telemetry-dev/sdk @telemetry-dev/langchain
yarn add @telemetry-dev/sdk @telemetry-dev/langchain
bun 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_name becomes 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=True sends 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=False turns 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.id attribute, which @telemetry-dev/langchain sets, or whose instrumentation scope name contains langchain, are marked as LangChain spans.
  • Token usage comes from gen_ai.usage.input_tokens and gen_ai.usage.output_tokens, or the older gen_ai.usage.prompt_tokens and gen_ai.usage.completion_tokens.
  • The model comes from gen_ai.request.model and gen_ai.response.model, and the provider from gen_ai.provider.name or gen_ai.system.
  • Messages come from gen_ai.input.messages and gen_ai.output.messages, the older indexed gen_ai.prompt.* and gen_ai.completion.* attributes, or traceloop.entity.input and traceloop.entity.output.

For the full list, see span attributes.

Troubleshooting

TypeScript:

  • No trace appears. Check that TELEMETRY_DEV_API_KEY is set in the process that runs the graph and that init() runs before the first run. A short script must await shutdown() or await 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_HEADERS contains your key and that Traceloop.init() runs before LangChain builds the chain. A short script without disable_batch=True can 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-openai 1.7.2, instrument_openai() from telemetry-dev-openai recorded each request but not the response or token usage of calls made through ChatOpenAI.

Last updated on November 7, 2026

Was this page helpful?