Datadog APM Auto-Instrumentation for LangChain Pipelines

简介

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 注入

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）

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

跟日志和指标关联

# 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 批处理异步发。只在热路径上测出回归才禁用。