第 22 章 可观测性：LangSmith Tracing
22.1 可观测性价值与 LangSmith 定位
Agent 系统由多步推理、多工具调用、多 Agent 协作组成，故障不再是单一异常栈而可能表现为"答非所问"、"工具死循环"、"成本飙升"等隐性问题。可观测性（Observability）需要回答三类问题：某次请求为什么失败（Trace，追踪）、系统整体健康度如何（Metrics，指标）、哪些 prompt/模型版本效果下降（Evaluation，评估）。
LangSmith 是 LangChain 官方提供的 Tracing/Monitoring/Evaluation 一体化平台，对 LangGraph 提供原生集成：图中每个节点、每次 LLM 调用、每次工具执行、每个 checkpoint 写入都会自动生成 Run 节点，无需手动埋点。部署形态包括云端 SaaS（https://smith.langchain.com）和 Self-hosted（自托管）版本，后者适合数据不能出域的合规场景。
接入依赖四个环境变量与 SDK：
# pip install langsmith
import os
os.environ["LANGSMITH_API_KEY"] = os.getenv("LANGSMITH_API_KEY", "")
os.environ["LANGSMITH_TRACING"] = "true"
os.environ["LANGSMITH_PROJECT"] = "agent-handbook"
os.environ["LANGSMITH_ENDPOINT"] = "https://api.smith.langchain.com" # 自托管替换为内网地址22.2 Trace 结构与 UI 视图
LangSmith 中一次图执行对应一棵 Run Tree（运行树）。每次节点执行、LLM 调用、工具调用、Retriever 调用都是一个 Run，通过 run_id 与 parent_run_id 构成父子关系：Graph Run 为根，其下包含各个 Node Run，Node Run 下再嵌套 LLM Run 与 Tool Run。每个 Run 记录 name、run_type、inputs、outputs、start/end time、token usage、error、tags、metadata 等字段。
核心 UI 视图：Projects 按项目隔离环境与业务线，支持按时间、标签、错误状态筛选；Traces 展示单次运行的时间线树，可逐层查看每一步输入、输出、耗时、token 消耗，展开 LLM Run 可见完整 prompt 与 completion；Threads 按 thread_id 聚合多轮对话轨迹，便于复盘完整会话；Monitor 看板以图表形式呈现延迟分位、错误率、token 用量、成本趋势；Datasets/Prompts/Playground/Evals 则覆盖数据集管理、提示词版本化、Prompt 对比 Playground 与评估任务。
Tags 与 Metadata 用于注入业务维度：
config = {
"tags": ["production", "v1.2.0", "checkout-agent"],
"metadata": {"user_id": "u123", "tenant": "acme", "region": "cn-hangzhou"},
}
agent.invoke({"messages": [("user", "查询订单")]}, config=config)自定义埋点通过 @traceable 装饰器包装业务函数，函数内部可使用 trace.get_current_span() 记录自定义事件或附加 KV：
from langsmith import traceable
from langsmith import trace as ls_trace
@traceable(name="risk_check")
def risk_check(order_id: str) -> dict:
span = ls_trace.get_current_span()
span.add_event("rule_loaded", {"rule_version": "2026-09"})
return {"level": "low"}反馈收集通过 LangSmith SDK 的 create_feedback 或 UI 上的 thumbs up/down、星级、评论完成，为后续评估与数据集构建提供标注来源。LangSmith 还支持将 Trace 通过 OpenTelemetry 协议导出到 Grafana、Jaeger、Datadog 等通用可观测平台，满足统一监控需求。
22.3 接入示例、替代方案与治理
一个接入 LangSmith 的最小 ReAct Agent 示例：
from langgraph.prebuilt import create_react_agent
from langchain_openai import ChatOpenAI
from langchain_core.tools import tool
@tool
def search_order(order_id: str) -> str:
return f"订单 {order_id} 已发货"
llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)
agent = create_react_agent(llm, [search_order])
cfg = {"tags": ["prod"], "metadata": {"env": "prod"}}
agent.invoke({"messages": [("user", "查一下 o888 的订单")]}, config=cfg)排查线上问题时在 Traces 页按 metadata.user_id 或 metadata.trace_id 过滤即可定位单次请求。
可观测方案对比如表：
| 维度 | LangSmith | LangFuse | Helicone | Arize Phoenix | Braintrust |
|---|---|---|---|---|---|
| 开源 | 云+自托管 | 开源+云 | 云 | 开源 | 云 |
| LangGraph 原生 | 是 | 社区集成 | 通过代理 | 社区 | 社区 |
| 评估能力 | 强 | 中 | 弱 | 中 | 强 |
| 成本追踪 | 是 | 是 | 是 | 是 | 是 |
| 自托管复杂度 | 中（K8s+PG+CH） | 低（Docker） | 低 | 低 | 无 |
本章小结：LangSmith 通过 Run Tree 自动记录图执行全过程，UI 视图覆盖追踪、指标、评估三大场景，tags/metadata 与自定义 traceable 节点提供业务维度注入能力，OpenTelemetry 导出打通通用监控栈。
常见错误：LANGSMITH_TRACING 默认未开启导致无 trace 产生；API Key 错误时 LangSmith 采用静默失败策略——主流程不受影响但无任何数据，排查期容易误判为"功能异常"；用户身份证号、手机号等 PII 直接进入 messages 字段造成泄露，需通过 mask_secrets/redaction 钩子或输入过滤提前脱敏；tags 使用无规范取值造成维度爆炸，丧失筛选价值。
生产建议：所有生产环境必须接入 Tracing，不能因担心性能跳过；高流量场景配置采样率（通过 LANGSMITH_TRACING_SAMPLE_RATE 或自定义采样器），错误请求 100% 采样、正常请求按比例采样；PII 脱敏在工具入口与图入口双重拦截；按租户/版本/地域打 tag，故障定位时能快速收敛到变更范围；自托管部署需提前规划 Postgres 与 ClickHouse 容量，历史 trace 默认保留周期按合规要求设置。