LangSmith的Trace和Span是什么

2026/8/6 4:21:53

Span（跨度）

在LLM可观测 / OpenTelemetry / LangSmith / LangFuse 领域：
Trace：一次完整请求的整条链路（一条大树干）
Span：Trace里面的每一小段操作（树上的每一个节点/树枝）

1条Trace= 1次完整会话/一次Agent执行。
一条Trace由多个Span组成，Span之间有父子嵌套关系，形成树。

举个Agent例子：

Trace: 用户提问：帮我查北京天气 ├─ Span【Agent主chain】(总耗时 2.2s) ├─ Span【调用工具 search天气】(耗时0.8s) └─ Span【LLM生成回答】(耗时1.3s)

每一个方块就是一个Span。

Span里面记录什么信息

每个Span一定有：

span_id：自己唯一ID
parent_span_id：父Span的id；顶层Span父id=None
开始时间、结束时间 → 计算耗时
operation name：操作名字（llm.invoke、tool.search、graph_node:call_tool）
输入 inputs，输出 outputs
状态：成功 / error / cancelled（被取消）
元数据：token消耗、模型名称、异常堆栈

LangSmith里面叫Run，Run = Span，概念等价。
LangSmith术语：Trace是根Run，下面所有子Run就是子Span。

产品	整条链路	单元片段
LangSmith	Trace（根Run）	Run（等价Span）
LangFuse	Trace	Observation(Obs)，等价Span
OpenTelemetry	Trace	Span

LangSmith内部：Run对象就是Span；_CURRENT_RUNcontextvar存的就是当前正在执行的Span对象。

父子Span是怎么形成的（结合前面contextvars）

创建父Span（根Run），把它存入ContextVar。
执行子函数，@traceable/ callback 读取context拿到父Span。
创建子Span，把子Span的parent_span_id = 父span_id。
子Span执行完成，上报。

不需要手动传参，靠上下文隐式拿到父ID，自动嵌套。

三种Span结束状态

✅正常结束：拿到end回调，记录结束时间，完整上报。
❌异常报错：触发on_xxx_error回调，标记span状态为error，记录异常栈。
⚠️被取消（前端停止生成）：task.cancel()，协程抛出CancelledError。
- 不会走到end回调，也不会走到error回调
- Span只有start，没有end；UI看到一条“截断、未完成”的trace。

区分容易混淆名词

Trace：完整的一次业务请求链路（根）
Span：链路中每一个独立操作片段（子节点）
ContextVar：用来隐式传递当前span对象，方便自动设置parent_span_id
Callback：事件钩子，在业务节点执行的前后，触发创建/结束Span

极简伪代码模拟Span模型

@dataclassclassSpan:span_id:strparent_span_id:str|Nonename:strstart_time:floatend_time:float|Nonestatus:str# ok / error / cancelledinputs:dictoutputs:dict|None# 上下文变量保存当前正在运行的spancurrent_span:ContextVar[Span|None]=ContextVar("current_span")defstart_span(name):parent=current_span.get()span=Span(span_id=str(uuid.uuid4()),parent_span_id=parent.span_idifparentelseNone,name=name,start_time=time.time(),end_time=None,status="ok",inputs={},outputs=None)token=current_span.set(span)returnspan,tokendefend_span(span,token):span.end_time=time.time()report_span(span)# 上报到LangSmith/LangFusecurrent_span.reset(token)