# Datadog APM Auto-Instrumentation for LangChain Pipelines

> ddtrace auto-instruments LangChain chains, agents, tools — every step gets a span, parent-child preserved, latency and tokens recorded.

## Install

Save as a script file and run:

## Quick Use

1. `pip install ddtrace>=2.10`
2. `from ddtrace import patch_all; patch_all(langchain=True)` before imports
3. Set DD_LLMOBS_ENABLED=1, DD_LLMOBS_ML_APP, DD_API_KEY

---

## Intro

Datadog's ddtrace SDK auto-instruments LangChain — every chain run, agent step, retriever call, and tool execution becomes a span in your service flame graph with proper parent-child relationships. You see exactly which retrieval step took 800ms, which tool returned an error, which prompt template hit the model. Best for: LangChain or LlamaIndex pipelines you can't easily decompose; debugging slow agents; surfacing the long tail of agent failures. Works with: ddtrace ≥ 2.10 patched against LangChain ≥ 0.1, LlamaIndex ≥ 0.10. Setup time: 5 minutes.

---

### Enable LangChain instrumentation

```python
import os
from ddtrace import patch_all
patch_all(langchain=True)

os.environ["DD_LLMOBS_ENABLED"] = "1"
os.environ["DD_LLMOBS_ML_APP"] = "my-langchain-rag"
os.environ["DD_API_KEY"] = "..."

# Now LangChain runs are auto-traced
from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate

prompt = ChatPromptTemplate.from_messages([
    ("system", "You are a helpful assistant"),
    ("user", "{question}"),
])
chain = prompt | ChatOpenAI(model="gpt-4o")
chain.invoke({"question": "Explain BERT in 50 words"})
```

### Multi-step agent (RAG + tools)

```python
from langchain.agents import AgentExecutor, create_tool_calling_agent
from langchain_community.tools import TavilySearchResults

tools = [TavilySearchResults(max_results=3)]
agent = create_tool_calling_agent(ChatOpenAI(model="gpt-4o"), tools, prompt)
executor = AgentExecutor(agent=agent, tools=tools)
executor.invoke({"question": "What's the latest GPT release?"})
# Datadog flame graph shows: agent → tool(tavily_search) → llm(gpt-4o) → llm(gpt-4o, final)
```

### Span hierarchy in Datadog

```
agent.run               (1.8s, total)
├─ retrieve.documents   (320ms)
├─ tool.tavily_search   (640ms)
└─ llm.openai           (820ms, 1247 tokens, $0.012)
    ├─ prompt.template  (12ms)
    └─ http.request     (798ms)
```

### Attributes captured per span

- `langchain.request.type` — chain | agent | retriever | tool | llm
- `langchain.request.model_name` — gpt-4o, claude-3-5-sonnet, etc.
- `langchain.tokens.prompt`, `langchain.tokens.completion`
- `langchain.cost.usd`
- `error.type`, `error.message` if the step failed

### Combine with logs and metrics

```yaml
# datadog.yaml log → trace correlation
logs_enabled: true
apm_config:
  trace_id_injection: true
```

Now any log line emitted during a chain step joins the trace in the LLM Observability view — search "session_id:abc-123" and see logs + spans in one timeline.

---

### FAQ

**Q: Does LangGraph work too?**
A: Yes — ddtrace ≥ 2.18 instruments LangGraph node executions. Each graph node becomes a span; the supergraph run is the parent. Cycle detection keeps repeated nodes distinct.

**Q: What if I use LangServe?**
A: LangServe runs over FastAPI; ddtrace's `patch(fastapi=True)` plus `patch(langchain=True)` gives you HTTP request → chain run → LLM call as one continuous trace. Drop both `patch_all`'d together.

**Q: Performance overhead?**
A: Tiny — ddtrace's hooks add <1% latency on tested LangChain workloads. The exporter batches and ships async. Disable on hot paths only if you hit measured regressions.

---

## Source & Thanks

> Built by [Datadog](https://github.com/DataDog). LangChain integration in [DataDog/dd-trace-py](https://github.com/DataDog/dd-trace-py).
>
> Apache-2.0 + Datadog API ToS

---

<!-- ZH -->

## 快速使用

1. `pip install ddtrace>=2.10`
2. import 之前 `from ddtrace import patch_all; patch_all(langchain=True)`
3. 设 DD_LLMOBS_ENABLED=1、DD_LLMOBS_ML_APP、DD_API_KEY

---

## 简介

Datadog 的 ddtrace SDK 自动注入 LangChain —— 每次 chain 运行、agent 步骤、retriever 调用、tool 执行都变成服务火焰图里的一个 span，父子关系保留正确。能精确看到哪个 retrieval 步骤花了 800ms、哪个 tool 返回错误、哪个 prompt 模板打到模型。适合不容易拆解的 LangChain 或 LlamaIndex 流水线、调试慢 agent、把 agent 失败的长尾暴露出来。兼容 ddtrace ≥ 2.10，LangChain ≥ 0.1、LlamaIndex ≥ 0.10。装机时间 5 分钟。

---

### 启用 LangChain 注入

```python
import os
from ddtrace import patch_all
patch_all(langchain=True)

os.environ["DD_LLMOBS_ENABLED"] = "1"
os.environ["DD_LLMOBS_ML_APP"] = "my-langchain-rag"
os.environ["DD_API_KEY"] = "..."

# 之后 LangChain 运行自动 trace
from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate

prompt = ChatPromptTemplate.from_messages([
    ("system", "你是个有帮助的助手"),
    ("user", "{question}"),
])
chain = prompt | ChatOpenAI(model="gpt-4o")
chain.invoke({"question": "用 50 字解释 BERT"})
```

### 多步 agent（RAG + tools）

```python
from langchain.agents import AgentExecutor, create_tool_calling_agent
from langchain_community.tools import TavilySearchResults

tools = [TavilySearchResults(max_results=3)]
agent = create_tool_calling_agent(ChatOpenAI(model="gpt-4o"), tools, prompt)
executor = AgentExecutor(agent=agent, tools=tools)
executor.invoke({"question": "GPT 最新发布是什么？"})
# Datadog 火焰图：agent → tool(tavily_search) → llm(gpt-4o) → llm(gpt-4o, final)
```

### Datadog 里的 span 层级

```
agent.run               (1.8s 总计)
├─ retrieve.documents   (320ms)
├─ tool.tavily_search   (640ms)
└─ llm.openai           (820ms、1247 tokens、$0.012)
    ├─ prompt.template  (12ms)
    └─ http.request     (798ms)
```

### 每 span 捕获的属性

- `langchain.request.type` —— chain / agent / retriever / tool / llm
- `langchain.request.model_name` —— gpt-4o、claude-3-5-sonnet 等
- `langchain.tokens.prompt`、`langchain.tokens.completion`
- `langchain.cost.usd`
- 步骤失败时 `error.type`、`error.message`

### 跟日志和指标关联

```yaml
# datadog.yaml log → trace 关联
logs_enabled: true
apm_config:
  trace_id_injection: true
```

之后 chain 步骤发出的任何日志行都加入 LLM Observability 视图的 trace —— 搜 "session_id:abc-123" 就能在一个时间线上看到日志 + span。

---

### FAQ

**Q: LangGraph 也能用吗？**
A: 能 —— ddtrace ≥ 2.18 注入 LangGraph 节点执行。每个 graph 节点变 span，supergraph 运行是父。循环检测让重复节点保持区分。

**Q: 用 LangServe 怎么办？**
A: LangServe 跑在 FastAPI 上；ddtrace 的 `patch(fastapi=True)` 加 `patch(langchain=True)` 让 HTTP 请求 → chain 运行 → LLM 调用 形成一条连续 trace。两个 `patch_all` 一起开。

**Q: 性能开销？**
A: 小 —— 测过的 LangChain 负载上 ddtrace hook 加 <1% 延迟。Exporter 批处理异步发。只在热路径上测出回归才禁用。

---

## 来源与感谢

> Built by [Datadog](https://github.com/DataDog). LangChain integration in [DataDog/dd-trace-py](https://github.com/DataDog/dd-trace-py).
>
> Apache-2.0 + Datadog API ToS


---
Source: https://tokrepo.com/en/workflows/datadog-apm-auto-instrumentation-for-langchain-pipelines
Author: Datadog