LangChain (tracing) | Respan Docs

LangChain is a framework for building applications with language models. It provides chains, agents, tools, retrievers, and provider integrations. Respan gives you full observability over every chain run, agent step, retriever call, tool call, and LLM generation — and gateway routing through the OpenAI-compatible Respan endpoint.

Set up Respan

Create an account at platform.respan.ai and grab an API key.

Run npx @respan/cli setup to set up with your coding agent.

Use Respan Gateway

See LangChain gateway setup to route this integration through the Respan gateway.

Example projects

Example projects

Setup

Install packages

$ pip install respan-tracing respan-instrumentation-langchain langchain langchain-openai python-dotenv

Set environment variables

$ export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"
$ export RESPAN_BASE_URL="https://api.respan.ai/api"

RESPAN_API_KEY is used to export traces to Respan. Set OPENAI_API_KEY too when your LangChain run uses a provider-backed model instead of a fake/local model.

Initialize and run

Attach the Respan LangChain callback to the runnable config for each chain, model, tool, retriever, or agent run you want traced.

1 import os
2 from contextlib import suppress
3 
4 from langchain_core.language_models.fake_chat_models import FakeListChatModel
5 from langchain_core.messages import HumanMessage, SystemMessage
6 from respan_instrumentation_langchain import add_respan_callback
7 from respan_tracing import RespanTelemetry
8 
9 telemetry = RespanTelemetry(
10     app_name="langchain-quickstart",
11     api_key=os.environ["RESPAN_API_KEY"],
12     base_url=os.getenv("RESPAN_BASE_URL", "https://api.respan.ai/api"),
13     is_auto_instrument=False,
14     is_batching_enabled=False,
15 )
16 
17 model = FakeListChatModel(responses=["Hello from a traced LangChain run."])
18 
19 try:
20     response = model.invoke(
21         [
22             SystemMessage(content="Reply in one short sentence."),
23             HumanMessage(content="Say hello to Respan tracing."),
24         ],
25         config=add_respan_callback(
26             {
27                 "run_name": "hello_world",
28                 "tags": ["respan-langchain-example", "quickstart"],
29                 "metadata": {"example": "quickstart"},
30             }
31         ),
32     )
33     print(response.content)
34 finally:
35     with suppress(Exception):
36         telemetry.flush()

For a provider-backed model, keep the same callback config and swap in your model:

1 from langchain_openai import ChatOpenAI
2 from respan_instrumentation_langchain import add_respan_callback
3 
4 llm = ChatOpenAI(model="gpt-4.1-nano")
5 response = llm.invoke(
6     "Say hello in three languages.",
7     config=add_respan_callback(
8         {
9             "run_name": "hello_langchain",
10             "tags": ["langchain", "quickstart"],
11             "metadata": {"framework": "langchain"},
12         }
13     ),
14 )
15 print(response.content)

View your trace

Open the Traces page to see your LangChain workflow with chain runs, LLM calls, retriever spans, and tool calls.

Configuration

Parameter	Type	Default	Description
`api_key`	`str \| None`	`None`	Falls back to `RESPAN_API_KEY` env var.
`base_url`	`str \| None`	`None`	Falls back to `RESPAN_BASE_URL` env var.
`instrumentations`	`list`	`[]`	Plugin instrumentations to activate, e.g. `LangChainInstrumentor()`.
`include_content`	`bool`	`True`	Includes inputs and outputs on LangChain spans.
`include_metadata`	`bool`	`True`	Includes LangChain tags, metadata, and serialized runnable details.
`customer_identifier`	`str \| None`	`None`	Default customer identifier for all spans.
`metadata`	`dict \| None`	`None`	Default metadata attached to all spans.
`environment`	`str \| None`	`None`	Environment tag, e.g. `"production"`.

Attributes

In Respan()

Set defaults at initialization — these apply to all spans.

1 from respan import Respan
2 from respan_instrumentation_langchain import LangChainInstrumentor
3 
4 respan = Respan(
5     instrumentations=[LangChainInstrumentor()],
6     customer_identifier="user_123",
7     metadata={"service": "langchain-api", "version": "1.0.0"},
8 )

With propagate_attributes

Override per-request using a context scope.

1 from langchain_openai import ChatOpenAI
2 from respan import Respan, propagate_attributes
3 from respan_instrumentation_langchain import (
4     LangChainInstrumentor,
5     add_respan_callback,
6 )
7 
8 respan = Respan(instrumentations=[LangChainInstrumentor()])
9 llm = ChatOpenAI(model="gpt-4.1-nano")
10 
11 def handle_request(user_id: str, question: str):
12     with propagate_attributes(
13         customer_identifier=user_id,
14         thread_identifier="conv_abc_123",
15         metadata={"plan": "pro"},
16     ):
17         response = llm.invoke(
18             question,
19             config=add_respan_callback({"run_name": "user_question"}),
20         )
21         print(response.content)

Attribute	Type	Description
`customer_identifier`	`str`	Identifies the end user in Respan analytics.
`thread_identifier`	`str`	Groups related messages into a conversation.
`metadata`	`dict`	Custom key-value pairs. Merged with default metadata.

Decorators (optional)

Decorators are not required. LangChain callback spans are emitted when you attach the Respan callback config. Use @workflow and @task (Python) or withWorkflow and withTask (TypeScript) to add structure when you want to group related runs into a named workflow with nested tasks.

1 from langchain_openai import ChatOpenAI
2 from respan import Respan, workflow, task
3 from respan_instrumentation_langchain import (
4     LangChainInstrumentor,
5     add_respan_callback,
6 )
7 
8 respan = Respan(instrumentations=[LangChainInstrumentor()])
9 llm = ChatOpenAI(model="gpt-4.1-nano")
10 
11 @task(name="generate_outline")
12 def outline(topic: str) -> str:
13     return llm.invoke(
14         f"Create a brief outline about: {topic}",
15         config=add_respan_callback({"run_name": "outline_model"}),
16     ).content
17 
18 @workflow(name="content_pipeline")
19 def pipeline(topic: str):
20     plan = outline(topic)
21     response = llm.invoke(
22         f"Write content from this outline: {plan}",
23         config=add_respan_callback({"run_name": "draft_model"}),
24     )
25     print(response.content)
26 
27 pipeline("Benefits of API gateways")
28 respan.flush()

Examples

Chains

Chains are traced as workflow/task spans with nested LLM and tool spans.

1 from langchain_core.output_parsers import StrOutputParser
2 from langchain_core.prompts import ChatPromptTemplate
3 from langchain_openai import ChatOpenAI
4 from respan_instrumentation_langchain import add_respan_callback
5 
6 prompt = ChatPromptTemplate.from_messages([
7     ("system", "Translate the user text to {language}."),
8     ("human", "{text}"),
9 ])
10 chain = prompt | ChatOpenAI(model="gpt-4.1-nano") | StrOutputParser()
11 
12 result = chain.invoke(
13     {"language": "French", "text": "Hello, Respan."},
14     config=add_respan_callback({"run_name": "translation_chain"}),
15 )
16 print(result)

Tools

Tool calls are captured with tool name, arguments, result, and timing.

1 from langchain_core.tools import tool
2 from respan_instrumentation_langchain import add_respan_callback
3 
4 @tool
5 def get_weather(city: str) -> str:
6     """Get the weather for a city."""
7     return f"It is sunny in {city}."
8 
9 result = get_weather.invoke(
10     {"city": "San Francisco"},
11     config=add_respan_callback({"run_name": "weather_tool"}),
12 )
13 print(result)

Streaming

Streaming responses are traced like regular calls.

1 for chunk in llm.stream(
2     "Write a haiku about Python.",
3     config=add_respan_callback({"run_name": "streaming_model"}),
4 ):
5     print(chunk.content, end="", flush=True)