🏠 总目录📚 本教程 17e · 请求追踪与脱敏日志 ← →

智能体工程 · 17e

一次重放请求,应当留下几次计费和哪些日志?

读完能做的判断:用追踪关联、准入单位与白名单导出解释事件和脱敏边界。

17e · 请求追踪与脱敏日志

⏱ 阅读约 30 分钟 · 动手实践另计

本章保留教学代码、路径说明与历史验证结论;完整实验工程和运行记录未随本站及公开仓库分发。命令用于说明调用方式,复现需自行准备对应实现、数据与环境。

一句话带走:先把事件归成独立请求,再统计一次准入和可信终态;日志里留下定位线索,问题正文、凭证和异常原文留在入口之外。

本节继续用虚构维修台和临时 SQLite,核对失败尝试、重放关联和缺失记录,不启动模型或网络服务。

入口规则见企业助手服务层实战,草稿状态见持久化审批与故障恢复。先看追踪代码(examples/knowledge-assistant/trace_lab.py)和契约测试(examples/knowledge-assistant/test_trace_lab.py)。本节把可观测性里的关联思路落到已有服务事件。

用演示核对请求计数

运行 demo,对照 event_count、request_count 和 charged_units,解释三个计数为什么分别是 32、14、9,再检查异常记录怎样隔离。

下面是原示例父项目目录内的两条命令。原环境可把 python 换成 examples/knowledge-assistant/.venv/Scripts/python.exe。

python -m unittest discover -s examples/knowledge-assistant -p test_trace_lab.py -v
python examples/knowledge-assistant/trace_lab.py demo

在示例 knowledge-assistant 目录内,对应命令为:

python -m unittest test_trace_lab -v
python trace_lab.py demo --output .runtime/trace-my-first-run

默认创建 .runtime/trace-时间编号,显式 --output 必须是新目录。运行生成 sanitized-events.json、summary.json、manifest.json;临时数据库结束后移除,不导出凭证表或业务正文。

一次请求会产生多个事件

真实 ProductService.audit() 已有服务端生成的 32 位十六进制 trace_id。一个直接搜索产生 admitted → completed。有只读传输夹具时,还会出现 transport_attempt,重试会增加尝试事件。认证失败只有 rejected,它没有准入。

同一 trace:admitted → attempt 1(429)→ attempt 2(200)→ completed
事件:4 条    请求:1 个    教学请求单位:1 个

图中 attempt 的真实 kind 是 transport_attempt。事件数是记录量,请求数是入口调用量;用事件数作失败率分母,重试产生的多行会稀释失败比例。

每组输出状态、事件数、尝试次数、终态耗时和固定诊断。问题相同或时间相近不能用来合并请求。

重放是关联,不是另一个子调用

同一业务编号再次进入服务,会得到新的服务器 trace。服务返回 request_repeated,审计用 original_trace_id 指向旧 trace。两条请求必须分开统计:原请求是一次准入,重放是一次拒绝,本次扣额为零。

聚合保留关联键,否则可能把新拒绝误算为旧请求的终态。若原 trace 在记录窗口外,也不能据此自动补齐旧事件。

草稿终态还可能有 64 位十六进制 workflow_run_id。它只用于受限状态定位,不输出标题、正文或审批人的个人字段。这个编号对应已有服务导出的运行摘要,不从用户问题或 token 重新生成可关联摘要。

请求 completed 与草稿 pending 可以同时成立:入口完成保存,草稿仍待审批。本节不调用 approve 或 execute,成功事件不能推出工单已执行。

一次准入只计一次单位

已有服务在准入、每次尝试和终态都可能写 charged_units=1。这个字段是累计扣额回执,不是每行新增扣额。上面的四行直接求和会得到 4,真实准入事实只有一次。

本聚合只从唯一的 admitted 取一个教学请求单位。没有准入的拒绝为零,准入后的失败或取消保留已扣的一。两次尝试不重复扣;多个 admitted 则是记录矛盾,不能随手取第一条装作正常。

请求记录 状态解释 可信计量
admitted 与唯一 completed 已完成入口工作 1 单位
admitted 与 failed / cancelled 准入后失败或取消 1 单位
单独 rejected 或准入前 cancelled 未准入的终态 0 单位
admitted 没有终态 incomplete 准入事实 1,完成结果未知
重复事件或矛盾终态 invalid,隔离整条 trace 不进入可信扣额与耗时合计

invalid 的零贡献表示记录不足以支持可信汇总,需要回权威账本核对,不意味着退款。教学请求单位不能替代模型 token 或金额。

白名单先于导出

summarize_audit(events) 只允许十个事件字段:event_id、trace_id、kind、error、charged_units、attempt、elapsed_ms、original_trace_id、workflow_run_id、created。额外字段即使叫 metadata、debug 或 harmless,也不保留。

任意嵌套 payload 都直接丢弃,不输出其中正文、凭证或内容摘要。

kind 只认服务的六种阶段,错误只认固定类型。未知字符串或对象变成 unknown_error。异常注入带有唯一虚构标记与测试凭证,导出没有原文;internal_failure 也不能单独解释具体根因。

字段值也要验证:trace 是规定长度的小写十六进制;时间有限非负且非 bool;attempt 是 1–5 整数。超大数隔离,不让转换异常打断分析。

演示在内存扫描拟导出文件,命中探针原文就阻止写出。它只证实本次夹具未泄漏;新增出口需要重新核对。

不完整和非法记录都要看见

本地审计的 event_id 是服务记录顺序。输入文件乱序时,聚合按它排序,同时留下 input_out_of_order。它不会按不同请求的墙钟时间拼装一条“端到端耗时”。created 只保留经过验证的记录时间。

event_id 须在 SQLite 整数范围 1–2^63−1;重复 ID 即使另一行 trace 非法,也隔离可关联请求。阶段错误矛盾、attempt 缺口、成功后继续 attempt、重复准入或矛盾终态都标 invalid,不猜结局。admitted/completed 无 error,cancelled 只能对应 cancelled。

只有 admitted 的 trace 标为 incomplete。可能是进程崩溃、截取窗口不完整或记录缺失;这三种原因仅凭当前文件无法区分。unknown_terminal_count 包括 incomplete 与 invalid,提醒读者有多少请求没有可信终态。

非法 trace 行计入 invalid_event_count,不输出原值或哈希,不伪造 trace。quarantined_event_count 是可关联 invalid trace 中被整体排除的行数;两者不能合成坏请求数。

原创 evaluation/trace-cases.json 显式标记 synthetic,包含缺终态、矛盾、重复、负耗时、非法 attempt、未知嵌套字段、乱序和缺终态耗时等边界。它用于解析契约;真实服务生成的事件另放在 validation demo 目录,不能互换标签。

耗时的分母写在数字旁边

每条请求只取唯一终态的 elapsed_ms。尝试耗时用于阶段定位,不与终态耗时相加,因为终态已经覆盖入口处理过程。只有尝试耗时没有终态耗时,不能据此补出一个端到端数字。

成功组为 completed,失败组为 failed、cancelled、rejected。两组的 count 只数实际终态耗时,缺失用 missing_terminal_elapsed_count 单列;无可信终态不进样本。

分位数采用最近秩:把 n 个耗时升序排列,位置为 ceil(p*n)-1,p50 的 p 是 0.50,p95 的 p 是 0.95。五个值为 1、2、3、4、100 时,p50 是 3,p95 是 100。没有样本时为 null,不把它写成零毫秒。

小样本可复算,不代表生产性能。失败与缺失仍在总表中,耗时样本可能少于请求数;不能删除失败后只报告成功 p95。

真实演示与同步并发

2026-10-11 审查修复后的实际 summary(examples/knowledge-assistant/validation/trace-demo-review-20261011/summary.json)来自真实 seed、凭证 API、ProductService.handle/audit。14 个请求产生 32 个事件,5 completed、5 rejected、3 failed、1 cancelled;可信准入 9,余额 30→21。

5 个拒绝分别覆盖认证、scope、参数、重复请求和零配额身份。3 个失败覆盖超时耗尽、503 耗尽及携带恶意异常字符串的内部失败。429 后 200 的请求最终 completed,尝试数是 2。草稿保存一次,状态 pending,实际 tickets 数为 0。

其中两个请求用 threading.Event 同步:第一个进入只读传输后停住,第二个在它释放前完成,再允许第一个继续。它们有两个独立 trace,聚合各自的准入、尝试和终态。实验依赖事件信号,没有靠 sleep 猜调度顺序。

本次交错没有误归组,未压测吞吐或长尾。429、503、超时和取消是受控注入;真实执行本地服务与 SQLite,没有供应商 HTTP 或模型调用。

manifest 保留环境、代码 SHA256 与测试命令。demo 不运行测试,21/21 限定 GREEN 单独保存。耗时与随机 trace 会变化。

走神救援

先打开 summary 的 state_counts,再挑一个 failed 的 trace,回到 sanitized-events 找同一编号。看 admitted、尝试次数和最终 error;不要把每行 charge 相加。若是 rejected 且有 original_trace_id,单独查看原请求,不把拒绝拼成旧终态。

看到 incomplete 或 invalid,先写“终态未知”并查记录完整性。看到 completed 草稿,检查 workflow 的 pending 状态。想追具体异常时,先设计受控诊断与访问权限,不能临时把 token、问题正文和异常原文塞进日志。

语雀对话日志分析提供关联与分类思路,转为原创实验。OpenTelemetry 日志概念供参照;本模块是自定义 JSON,未验收 SDK、后端、全出口或真实适配器。

折叠自查

检查点 1. 四条重试事件等于四个请求吗?

不等于。按服务器 trace_id 归组,一个请求可以有准入、两次尝试和终态四条事件。

检查点 2. 多行 charged_units=1 怎样统计?

唯一 admitted 计一次准入。attempt 与终态是累计回执,不再加扣。

检查点 3. original_trace_id 会把两次调用合并吗?

不会。重放有新的 trace,单独记为拒绝;original 只留下关联。

检查点 4. 异常字符串带凭证怎么办?

只输出固定错误枚举,未知值归 unknown_error;额外嵌套 payload 直接丢弃,不保留原文或内容摘要。

检查点 5. 只有 admitted 可以标成功吗?

不能。它标为 incomplete,准入事实可计一次,终态未知且不进入耗时样本。

检查点 6. completed 与 failed 同时出现取哪条?

不选。整条 trace 标 invalid 并隔离,保留矛盾诊断,另查权威记录。

检查点 7. p95 的缺耗时请求去哪了?

缺失数量单列,p95 只使用相应组的可信终态耗时;失败数量仍在状态总表。

检查点 8. 两个并发 trace 可以证明生产性能吗?

不能。这里只证明这次受控交错没有误归组;无生产 QPS、网络适配器或 OTel 后端验收。

打卡记录保存在你的浏览器里,首页能看到总进度