Agent开发 10|可观测性:怎样追踪一次任务并定位故障?
《Agent开发》系列 · 第 10 篇
用户反馈:"我问的是订单 1001,助手回答的却像是另一张订单。"
后端日志里有几行"模型调用成功""工具调用成功",没有异常堆栈。应该先改提示词、换模型,还是检查查询接口?如果不知道每一步实际发生了什么,排障很容易变成猜测。
Agent 的一次任务可能经历多轮模型调用、知识检索、工具执行、审批等待与恢复。我们需要把这些步骤关联起来,观察输入从哪里来、结果流向哪里、耗时花在哪里,以及错误发生在哪个边界。这就是 Observability(可观测性) 在 Agent 系统中的核心用途。
本篇用同一个订单查询任务,分别制造"工具超时"和"结果对应错误订单"两类故障。先看怎样定位,再解释 Trace、Span、日志与指标分别提供什么信息。
一、为什么"有日志"还不够?
1.1 单条成功记录只能证明局部情况
工具调用成功,可能只表示函数没有抛异常。它不一定证明结果属于用户请求的订单,也不证明模型正确理解了返回值。
模型服务返回成功,可能只是 HTTP 请求完成;生成内容仍可能缺少必要事实。任务最后返回一句回答,也不等于用户的业务请求已经完成。
因此,需要同时观察不同层次:
| 层次 | 关注的问题 |
|---|---|
| 请求与任务 | 处理哪项请求,最终是回答、等待、拒绝还是失败? |
| 模型调用 | 使用哪个版本,调用了几轮,用量与停止原因是什么? |
| 检索 | 搜索了哪版语料,选入哪些证据? |
| 工具执行 | 请求哪个工具,校验是否通过,结果是否匹配? |
| 业务结果 | 是否实际完成写入,审批范围与账务结果是否一致? |
可观测性让这些信息可以被关联和解释。它不会自动修复错误,但能把问题缩小到可验证的位置。
1.2 不要只记录最后一次异常
假设模型循环了五轮,最后因预算耗尽停止。最终日志只写"预算不足",就无法判断之前是不是一直查询相同订单,还是工具结果没有正确回填,导致模型重复请求。
排查需要看到过程中的关键决策与结果,而不是仅仅保存一个终态。记录工具请求、实际返回、校验结论与下一步状态,通常比试图获取模型完整内部推理更有工程价值。
二、Trace 与 Span:把一次执行拆成可以关联的步骤
2.1 Trace 是一条执行链,Span 是其中一个工作单元
Trace 将一次端到端执行中的相关步骤关联起来。Span 表示其中一段有开始、结束、耗时和属性的工作,比如一次模型调用或一次订单查询。
可以把本篇任务表示为:
text
task.run
├─ context.build
├─ retrieval.search
├─ model.generate
├─ tool.execute
├─ tool.validate_result
└─ model.generate
每个 Span 有自己的 span_id,通过 parent_span_id 指向父步骤,并共享 trace_id。这样可以知道某次查询属于哪个任务,而不是靠相邻日志行猜测。OpenTelemetry Trace 概念
2.2 任务 ID 和 Trace ID 为什么都需要?
任务可能等待审批几小时,之后在另一台机器恢复。一个业务任务可以关联多段执行 Trace;一次用户会话也可能创建多个任务。
task_id 用于长期关联同一任务,trace_id 用于关联某次执行链。审批申请号、业务操作号和模型供应商请求号也各有用途,不能把它们混成一个万能 ID。
长时间等待不一定要让一个 Span 一直保持打开。可以结束当前执行,保存任务与关联信息;恢复时创建新的 Trace,并通过任务标识或支持的 Span Link 关联之前的执行。Span Link 用于表达相关执行之间的联系,不要求它们是直接的父子关系。
2.3 跨服务时,需要传播关联信息
如果 Runtime 调用独立的模型网关、检索服务与业务接口,只在各自服务内生成随机 ID,链路仍然会断开。
服务之间需要按协议传播 Trace 上下文,消息队列与异步任务也要保存必要的关联信息。关联信息只用于观测,不能当成访问授权;外部传入的标识也需要格式与长度限制。
本篇只实现单进程同步关系,不实现跨服务传播。后续采用 OpenTelemetry SDK 时,应使用其上下文传播机制,而不是把教学字典直接当作标准 Trace 协议。
三、日志、指标和 Trace 怎样配合?
3.1 结构化日志:把关键事件写成可查询字段
普通文本"订单查询失败"难以汇总。结构化日志可以记录事件类型、时间、任务与链路标识、错误类别,以及必要的配置版本。
例如,结果校验发现不匹配时,记录:
json
{
"event": "tool_result_rejected",
"task_id": "task-demo",
"tool": "get_order_status",
"reason": "ORDER_MISMATCH",
"next_state": "NEEDS_REVIEW"
}
这里不必把另一张订单的完整内容复制到日志里。错误类别和受控的证据引用足以帮助定位,进一步调查可以通过受权限保护的系统完成。
3.2 Metrics:观察总体趋势
Metrics(指标)关注一段时间内的聚合情况,例如模型错误率、任务转人工比例、工具延迟和输入用量。它帮助发现系统是否整体恶化,再通过 Trace 查看具体样本。OpenTelemetry Metrics 概念
| 需要观察什么 | 示例指标 |
|---|---|
| 是否越来越慢 | 任务与各组件耗时分布、排队时间 |
| 是否频繁失败 | 模型错误率、工具错误率、校验失败率 |
| 是否增加无效工作 | 每任务模型调用次数、重复工具调用次数 |
| 是否更昂贵 | 已确认用量、未知用量次数、单任务成本 |
| 是否完成业务 | 任务成功率、等待审批比例、人工接管比例 |
任务成功率的定义应与评测一致。不能线上把"HTTP 200"当成功,离线却按业务完成判分,再把两个数字直接比较。
3.3 平均值会掩盖长尾
平均耗时很低,也可能有一部分请求等很久。P95 延迟表示大约 95% 的观测值不高于该值,适合观察长尾,但需要足够样本和明确时间窗口。
不同步骤并行时,不能简单把所有子 Span 耗时相加,当作端到端耗时;它们可能重叠。重试等待、队列等待和人工审批等待也应分开,否则很难判断需要优化哪个环节。
不要把任务号、订单号等近乎每次都不同的值作为指标标签。它们会产生大量时间序列,增加存储与查询成本。高基数标识更适合放入受控日志或 Trace,而指标通常按服务、操作、版本和有限状态分类。
四、模型、检索和工具,分别记录什么?
4.1 模型调用:一次逻辑调用可能包含多次尝试
建议记录实际模型版本、Prompt 配置版本、调用序号、开始结束时间、停止原因和用量状态。网关发生重试或切换时,每次尝试应能区分,避免只记录最终成功而漏掉前面的费用与等待。
用量未知时,应明确标记未知,不能用零掩盖;不同计量来源也需要区分。本篇示例的 Token 数是固定 Mock 数据,不代表真实 Tokenizer 或模型账单。
4.2 检索:需要知道哪些证据真的进入了上下文
仅记录"检索成功,返回 10 条",无法判断正确文档是否被重排淘汰。更完整的链路可以关联查询版本、语料版本、候选片段 ID、最终选入片段以及过滤原因。
搜索文本和原始文档可能敏感,未必适合直接记录。可以保存受控的引用和必要摘要,按数据管理规则决定是否允许保留原文及其期限。
4.3 工具:区分请求、执行与校验
工具请求记录模型想做什么;工具执行记录后端实际调用了什么;结果校验记录返回内容是否满足任务与协议要求。
在订单助手里,请求订单 1001,却得到订单 1002 的结果,即使工具本身没有报错,也必须拒绝回填给模型。把结果校验作为单独步骤记录,有助于明确故障发生在业务接口、适配器还是模型侧。
业务写入还要关联审批申请与幂等操作标识。Trace 说明代码走过哪些步骤,账务系统记录才是资金或资产实际变化的依据。
五、代码实践:定位两种不同的错误
5.1 示例做了什么?
配套文件为 demo/10-observability/trace_demo.py,完整代码见附录。Python 3.10+,无第三方依赖。
它用上下文管理器记录 Span 的父子关系、开始时间、耗时、状态和受控属性,并输出一棵执行树。模型、检索和工具均为 Mock,没有接入 OpenTelemetry 或远程观测平台。
代码里的 OK 与 ERROR 是教学状态约定,不是完整实现 OpenTelemetry 的状态语义,也不是可直接导入其后端的标准导出格式。
5.2 场景一:接口成功,结果却不属于当前订单
保存附录为 trace_demo.py,在文件所在目录运行:
bash
python3 trace_demo.py --scenario mismatch
执行树为:
text
task.run OK
context.build OK
retrieval.search OK
model.generate OK
tool.execute OK
tool.validate_result ERROR
Mock 工具返回了另一张订单的数据。查询函数没有抛异常,所以 tool.execute 是 OK;结果校验发现订单不一致,tool.validate_result 标为 ERROR。
后端捕获这个已知问题,将业务结果设为 NEEDS_REVIEW,并且不再调用第二次模型。根步骤的 OK 表示异常已经按预定路径处理,不代表用户问题已经解决。
技术 Span 状态与业务 outcome 必须分开看。 否则只看根 Span 就会把转人工误算成任务完成。
5.3 场景二:工具没有及时返回
bash
python3 trace_demo.py --scenario timeout
这次错误出现在 tool.execute,错误类型为 TimeoutError,不会进入结果校验或第二次模型调用。
这个异常由 Mock 直接抛出,不是实际等待了网络超时。示例验证的是故障被关联到哪个步骤及后续是否停止,而不是网络客户端的超时实现。
5.4 正常路径与持久化输出
bash
python3 trace_demo.py --scenario ok
python3 trace_demo.py --scenario mismatch --out trace.jsonl
正常路径包含两次模型调用,汇总的 Mock 输入 Token 为 300,输出 Token 为 65,业务结果为 ANSWERED。这仅表示生成了本例的查询回答,不代表执行过补发。
JSONL 文件每行保存一个 Span,便于逐条读取。Trace ID、时间和本地耗时每次会变化;实际测量的是这段本地教学代码的耗时,不能用来评价模型响应速度。
5.5 核心记录逻辑
每进入一个 Span,记录当前父步骤。发生异常时标记错误并重新抛出,让业务代码决定如何处理;在退出时记录耗时并收集结果:
python
try:
yield record["attributes"]
except Exception as error:
record["status"] = "ERROR"
record["attributes"]["error_type"] = type(error).__name__
raise
finally:
record["duration_ms"] = round((self.clock()-started)*1000, 3)
record["attributes"] = safe_attributes(record["attributes"])
self.stack.pop()
self.records.append(record)
耗时使用单调时钟,避免系统时间调整影响持续时间计算。开始时间使用 UTC 时间,方便关联其他记录。
本例用一个栈维护父子关系,只适用于单进程同步执行。并发线程或异步任务需要正确的上下文隔离与传播,不能共享这个栈直接运行。
六、排障时,沿着证据逐步缩小范围
假设收到"查错订单"的反馈,可以按以下顺序检查:
- 找到任务与对应执行 Trace,确认当时使用的模型、Prompt 与工具版本。
- 查看模型提出的订单号是否正确。如果请求已经错了,检查上下文与参数提取。
- 请求正确,再看后端实际调用与返回是否匹配。
- 返回错误,确认结果校验是否拦截,是否误回填给模型。
- 返回正确但回答错误,再检查第二轮上下文是否丢失或错配结果,以及模型生成是否忠实。
不同分支对应不同修复方向。结果适配器把订单号拼错时,继续调整提示词往往解决不了问题。
复现需要版本和输入条件,但不意味着必须把所有敏感原文长期写入通用日志。可以用脱敏样本、受限证据存储和必要配置重建问题。对于随机模型行为,还需要允许多次运行,不能承诺每次都得到完全一样的文本。
七、观测数据本身也需要边界
7.1 不要默认记录完整 Prompt、工具结果和异常文本
这些内容可能包含个人信息、企业资料、凭证或资产数据。异常字符串也可能附带请求头和响应正文。
本例只记录允许列表中的受控标量字段,不记录工具原文、Prompt 和异常文本;异常只保留类型。调用方修改属性后,导出前再次过滤。
但字段允许列表不是通用脱敏器。如果把密钥错误地塞进允许的 model_version 字段,它仍可能被记录。应在调用点只传入可信元数据,并结合分类、脱敏、访问控制与保留期限。
7.2 Trace 不能替代审计和业务账本
Trace 可能被采样、丢失或延迟导出。审批记录、幂等账务和关键业务审计不能仅依赖普通调试链路。
需要明确哪些记录必须持久化、谁可以访问、保留多久、如何发现写入失败。观测平台故障也应有处理策略,避免日志阻塞拖垮所有业务请求;但必需的业务审计又不能无声丢弃。
7.3 采样要知道自己漏掉了什么
高流量下可以只保留部分 Trace。按错误或慢请求保留更多样本有助于排障,但这批样本的错误率不能直接代表全部请求的错误率。
总体指标与 Trace 采样策略需要分别设计。关键故障应提高可追查性,同时控制敏感内容暴露和存储成本。
八、OpenTelemetry 与观测平台怎样接入?
OpenTelemetry 提供跨语言的观测接口、SDK 和传播与导出机制,帮助应用生成和传递 Trace、Metrics、Logs 等数据。它本身不是完整的业务监控界面。OpenTelemetry 概念文档
接入时,可以保留本篇建立的步骤边界,将本地 Span 替换成 SDK 的 Span,再将数据导出到合适的后端。使用 Langfuse 等面向 LLM 的观测平台时,也需要核对它记录的模型、工具、成本及评测字段,确认数据权限和保留策略。
不要因为安装了 SDK,就认为业务成功率和订单一致性会自动出现。SDK 能记录调用关系,但业务 outcome、审批范围、语料版本和结果校验仍需应用主动补充。
本篇没有安装这些平台或声称完成真实集成。生产选型应结合部署条件、数据要求、查询能力和维护成本验证。
九、怎样检查观测代码本身?
在配套目录运行:
bash
python3 -m unittest -v test_trace_demo.py
测试覆盖父子关系、错误定位、异常重新抛出、栈清理、未知用量计数、字段过滤以及错误结果后停止第二次模型调用。
这里还有一个经常遗漏的点:如果日志说"120 个输入 Token",就要知道它来自真实返回、估算还是 Mock。缺少用量的调用应该独立统计,而不是在求和时默认为零后不作说明。
测试通过说明示例在这些场景下能正确记录,不代表没有采集开销、不会丢数据或已经满足所有隐私要求。
十、面试与自查
Q:Trace、Span、日志与指标有什么区别?
Trace 关联一次执行链,Span 描述其中一段工作;日志记录具体事件与细节,指标描述一段时间内的聚合趋势。它们通过任务与链路标识配合:指标发现异常,Trace 缩小范围,日志和业务证据解释具体原因。
Q:如何定位 Agent 回答错误?
先区分输入、检索、工具、回填和生成。沿链路确认模型请求、真实执行与结果校验,再检查给模型的上下文。不要只因为最后输出来自模型,就把所有错误归因于模型。
Q:模型调用超时,用量怎么记录?
保留未知状态和调用标识,区分已报告用量与待核对部分,结合供应商记录补全。不能把缺失用量直接算成零而不披露。
试着回答:
- 根 Span 是 OK,但 outcome 是 NEEDS_REVIEW,能否计为业务成功?
- 工具执行没有报错,为什么还需要结果校验 Span?
- 如果只保留失败 Trace,能否用它们计算全量错误率?
参考思路:需要按业务成功定义判定;无异常不证明结果属于当前任务;错误采样有选择偏差,应使用全量指标或适当的统计方法。
十一、总结
可观测性把"Agent 好像出错了"拆成可以检查的问题:哪个步骤、哪个版本、什么输入条件、怎样处理错误、最终发生了什么。
记录的目的不是积累最多日志,而是让链路有足够证据,同时不把敏感数据和业务授权混入调试系统。Trace、指标、日志与业务记录各司其职,才能在问题出现时快速判断修复方向。
参考资料
附录:完整可运行代码
文件名:trace_demo.py,与配套文件一致。
python
"""单进程同步链路教学;无 OpenTelemetry SDK、真实模型或业务接口。"""
import argparse
from contextlib import contextmanager
from datetime import datetime, timezone
import json
import time
import uuid
ALLOWED_ATTRIBUTES = {
"model_version", "prompt_version", "corpus_version", "input_tokens", "output_tokens",
"usage_kind", "tool", "retrieved_count", "result_order_matches", "outcome", "error_type",
}
def safe_attributes(attributes):
# 只允许受控标量元数据;不接收 Prompt、工具原文、异常文本和密钥。
return {key: value for key, value in attributes.items()
if key in ALLOWED_ATTRIBUTES and type(value) in (str, int, bool, float)
and (not isinstance(value, str) or len(value) <= 120)}
class Tracer:
def __init__(self, task_id="task-demo", clock=time.perf_counter):
self.trace_id = uuid.uuid4().hex
self.task_id = task_id
self.clock = clock
self.stack = []
self.records = []
self.sequence = 0
@contextmanager
def span(self, name, **attributes):
self.sequence += 1
record = {
"trace_id": self.trace_id, "task_id": self.task_id,
"span_id": uuid.uuid4().hex[:16],
"parent_span_id": self.stack[-1]["span_id"] if self.stack else None,
"sequence": self.sequence, "name": name,
"started_at": datetime.now(timezone.utc).isoformat(),
"status": "OK", "attributes": safe_attributes(attributes),
}
started = self.clock()
self.stack.append(record)
try:
yield record["attributes"]
except Exception as error:
record["status"] = "ERROR"
record["attributes"]["error_type"] = type(error).__name__
raise
finally:
record["duration_ms"] = round((self.clock()-started)*1000, 3)
# 调用方只允许向 attributes 加入受控元数据,再次过滤。
record["attributes"] = safe_attributes(record["attributes"])
self.stack.pop()
self.records.append(record)
def export(self):
return sorted(self.records, key=lambda record: record["sequence"])
class ResultMismatch(ValueError):
pass
def mock_tool(scenario):
if scenario == "timeout":
raise TimeoutError("示例异常可能含敏感响应内容,不应直接写入日志")
return {"order_id": "1002" if scenario == "mismatch" else "1001", "paid": True}
def run_task(scenario="mismatch"):
if scenario not in {"ok", "mismatch", "timeout"}:
raise ValueError("未知场景")
tracer = Tracer()
outcome = "UNKNOWN"
with tracer.span("task.run") as root:
with tracer.span("context.build", prompt_version="orders-v1"):
pass
with tracer.span("retrieval.search", corpus_version="rules-v2", retrieved_count=2):
pass
with tracer.span("model.generate", model_version="mock-v1", usage_kind="mock",
input_tokens=120, output_tokens=30):
requested_order = "1001"
try:
with tracer.span("tool.execute", tool="get_order_status"):
result = mock_tool(scenario)
with tracer.span("tool.validate_result") as attrs:
attrs["result_order_matches"] = result["order_id"] == requested_order
if not attrs["result_order_matches"]:
raise ResultMismatch("结果不属于请求订单,禁止回填给模型")
except (ResultMismatch, TimeoutError):
outcome = "NEEDS_REVIEW"
else:
with tracer.span("model.generate", model_version="mock-v1", usage_kind="mock",
input_tokens=180, output_tokens=35):
outcome = "ANSWERED"
root["outcome"] = outcome
return tracer.export(), outcome
def diagnose(records):
by_id = {record["span_id"]: record for record in records}
if len(by_id) != len(records):
raise ValueError("Span ID 重复")
trace_ids = {record["trace_id"] for record in records}
if len(trace_ids) != 1:
raise ValueError("本例只分析单条 Trace")
for record in records:
parent = record["parent_span_id"]
if parent is not None and parent not in by_id:
raise ValueError("存在缺失的父 Span")
return [{"span": r["name"], "error_type": r["attributes"].get("error_type")}
for r in records if r["status"] == "ERROR"]
def summarize(records):
attempts = [r for r in records if r["name"] == "model.generate"]
known = [r for r in attempts if r["attributes"].get("usage_kind") == "mock"
and all(type(r["attributes"].get(k)) is int and r["attributes"][k] >= 0
for k in ("input_tokens", "output_tokens"))]
root = next(r for r in records if r["parent_span_id"] is None)
return {
"outcome": root["attributes"].get("outcome"),
"model_calls": len(attempts),
"reported_mock_input_tokens": sum(r["attributes"].get("input_tokens", 0) for r in known),
"reported_mock_output_tokens": sum(r["attributes"].get("output_tokens", 0) for r in known),
"unknown_usage_calls": len(attempts)-len(known),
"error_spans": diagnose(records),
}
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--scenario", choices=["ok", "mismatch", "timeout"], default="mismatch")
parser.add_argument("--out", help="可选 JSONL 文件路径")
args = parser.parse_args()
records, _ = run_task(args.scenario)
if args.out:
with open(args.out, "w", encoding="utf-8") as file:
for record in records:
file.write(json.dumps(record, ensure_ascii=False)+"\n")
print(json.dumps(summarize(records), ensure_ascii=False, indent=2))
print("Trace:", records[0]["trace_id"])
by_id = {r["span_id"]: r for r in records}
for record in records:
depth = 0
parent = record["parent_span_id"]
while parent:
depth += 1
parent = by_id[parent]["parent_span_id"]
print(" "*depth + record["name"] + " " + record["status"])
if __name__ == "__main__":
main()
可以先不看场景名称,只看两份执行树,尝试判断一次是工具没有返回,还是返回后被校验拦截。能够依据链路解释问题发生的位置,才算把 Trace 用到了排障过程里。
接下来,我们会主动构造越权、恶意文档、审批篡改与重复事件,检查系统是否守住执行规则。下一篇:Agent开发 11|安全与可靠性:怎样验证执行边界?