Agent开发 10|可观测性:怎样追踪一次任务并定位故障?

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 时间,方便关联其他记录。

本例用一个栈维护父子关系,只适用于单进程同步执行。并发线程或异步任务需要正确的上下文隔离与传播,不能共享这个栈直接运行。

六、排障时,沿着证据逐步缩小范围

假设收到"查错订单"的反馈,可以按以下顺序检查:

  1. 找到任务与对应执行 Trace,确认当时使用的模型、Prompt 与工具版本。
  2. 查看模型提出的订单号是否正确。如果请求已经错了,检查上下文与参数提取。
  3. 请求正确,再看后端实际调用与返回是否匹配。
  4. 返回错误,确认结果校验是否拦截,是否误回填给模型。
  5. 返回正确但回答错误,再检查第二轮上下文是否丢失或错配结果,以及模型生成是否忠实。

不同分支对应不同修复方向。结果适配器把订单号拼错时,继续调整提示词往往解决不了问题。

复现需要版本和输入条件,但不意味着必须把所有敏感原文长期写入通用日志。可以用脱敏样本、受限证据存储和必要配置重建问题。对于随机模型行为,还需要允许多次运行,不能承诺每次都得到完全一样的文本。

七、观测数据本身也需要边界

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:模型调用超时,用量怎么记录?

保留未知状态和调用标识,区分已报告用量与待核对部分,结合供应商记录补全。不能把缺失用量直接算成零而不披露。

试着回答:

  1. 根 Span 是 OK,但 outcome 是 NEEDS_REVIEW,能否计为业务成功?
  2. 工具执行没有报错,为什么还需要结果校验 Span?
  3. 如果只保留失败 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|安全与可靠性:怎样验证执行边界?

相关推荐
J船长16 分钟前
Agent开发 06|状态与恢复:任务中断后如何继续?
agent
J船长16 分钟前
Agent开发 09|Model Gateway:怎么选模型、做降级、算成本?
agent
J船长18 分钟前
Agent开发·阶段总结(二)|从上下文到评测,串起 Agent 的信息与质量管理
agent
J船长1 小时前
Agent开发 05|Context Engineering:如何构建高质量的模型上下文?
agent
J船长1 小时前
Agent开发·阶段总结(一)|从工具调用到协作审批,串起 Agent 的执行过程
agent
J船长2 小时前
Agent开发 04|协作与审批:怎样分工、何时让人确认?
agent
江屿风3 小时前
AI Agent架构全解析:从规划到记忆的智能跃迁
人工智能·笔记·架构·agent·c/s·mcp工作流
J船长5 小时前
Agent开发 03|架构选型:不同模式怎么选?
agent
J船长6 小时前
Agent开发 02|Agent Loop:任务如何持续执行?
agent