第 2.12.2 节：用 Trace、Span 和成本字段复盘一次请求
Trace、Span 与成本追踪不能只停留在口头约定，还需要落实为字段、校验和失败处理。完成本节后，你应该能够把 Trace、Span 与成本追踪落成字段表、校验规则、错误处理和验收样例。
核心概念四层解释法
本节按“四层解释法”讲核心概念：人话解释、项目位置、工程动作、面试说法。
Logs（日志）
人话解释：logs（日志）是系统留下的文字化记录，用来回答“发生了什么”。它像客服工作台的流水账：用户发起请求，系统检索了资料，模型调用了几次，工具是否成功，错误原因是什么。
项目位置：在客服工作台里，日志分布在用户入口、RAG（检索增强生成）、模型调用、工具网关、审批中心、安全护栏和最终回答记录里。
工程动作：日志要结构化，至少包含 trace_id（追踪编号）、session_id（会话编号）、user_id（用户编号）、tenant_id（租户编号）、事件类型、状态、耗时、错误码和摘要。不要把完整身份证、手机号、地址、API Key（接口密钥）和系统提示词原文写进日志。
面试说法：我不会只记录最终回答，而是记录 Agent（智能体）从输入、检索、模型、工具、审批到输出的关键事件。日志要能复盘，也要脱敏，不能让日志本身变成泄露源。
Tracing（调用链追踪）
人话解释：tracing（调用链追踪）是把一次请求拆成多个步骤，并用同一个 trace_id（追踪编号）串起来。每个步骤可以有自己的 span_id（片段编号），比如“检索知识库”“调用模型”“查订单工具”“输出护栏”。
项目位置：当用户问“我的退款什么时候到”，一次请求可能经过身份识别、会话加载、知识库检索、订单工具、模型总结、审批状态查询和最终回答。Tracing（调用链追踪）能告诉你每一步用了多久、是否失败、前后关系是什么。
工程动作：为每次用户请求生成 trace_id（追踪编号），为每个关键节点生成 span_id（片段编号），记录 parent_span_id（父片段编号）、开始时间、结束时间、状态、错误码和关键摘要。工具调用、模型调用和检索调用都要继承同一个 trace_id（追踪编号）。
面试说法：Agent 排障不能只看单条日志。我会用 trace_id（追踪编号）串起用户请求、RAG、模型、工具和审批，定位到底是检索慢、模型慢、工具失败还是安全护栏拦截。
Metrics（指标）
人话解释：metrics（指标）是可以持续统计的数字，用来回答“整体趋势怎么样”。日志适合查某一次具体事件，指标适合看一段时间内系统是否健康。
项目位置：客服工作台要看平均延迟、失败率、检索无命中率、工具调用成功率、审批超时率、Token（文本计量单位）消耗、成本、限流次数和安全事件数量。
工程动作：把关键事件转成可聚合指标。比如按模型统计平均 latency_ms（延迟毫秒），按租户统计 cost_estimate（成本估算），按工具统计失败率，按知识库统计 retrieval_hits（检索命中），按审批状态统计卡住数量。
面试说法：日志解决单次复盘，指标解决上线运营。我会同时设计技术指标和业务指标，例如模型延迟、工具失败率、检索无命中率、每租户成本和人工审批积压。
Cost Tracking（成本追踪）
人话解释：cost tracking（成本追踪）是记录每次模型、Embedding（嵌入向量）、检索、工具和第三方服务大概花了多少钱，用来回答“钱花在哪里”。
项目位置：客服 Agent 成本主要来自输入 Token（文本计量单位）、输出 Token（文本计量单位）、Embedding（嵌入向量）、向量数据库、模型调用、外部工具、短信邮件和服务器资源。
工程动作：每次模型调用记录 model_name（模型名称）、input_tokens（输入文本计量）、output_tokens（输出文本计量）和 cost_estimate（成本估算）。成本要能按 tenant_id（租户编号）、user_id（用户编号）、session_id（会话编号）、工具、模型和业务流程汇总。
面试说法：我会把成本当成产品能力设计。没有成本追踪，就无法判断哪个租户亏损、哪个流程太贵、应该用什么套餐报价，也无法设置预算和限流。
Rate Limit（限流）
人话解释：rate limit（限流）是限制某个用户、租户、工具或模型在一段时间内可以使用多少资源，避免系统被刷爆、成本失控或高风险动作被滥用。
项目位置：客服工作台里，普通用户不能一分钟连续问几百次；单个租户不能无限消耗 Token（文本计量单位）；退款审批工具不能被频繁提交；短信工具不能被 Agent 连续触发。
工程动作：设计按用户、租户、IP（网络地址）、会话、模型、工具和风险等级的限流规则。记录 rate_limit_status（限流状态），例如正常、接近阈值、已降级、已阻断。超限后要给用户可理解提示，并给内部记录原因。
面试说法：限流不是只防攻击，也是在保护模型预算和企业客户之间的公平性。我会按用户、租户、工具和风险等级做分层限流，并把超限事件接入告警和成本看板。
Alert（告警）
人话解释：alert（告警）是在系统出现异常趋势时主动通知相关人员，而不是等用户投诉。
项目位置：客服工作台需要对模型错误率上升、工具失败率上升、检索无命中率上升、成本突增、审批积压、安全事件增加、限流频繁触发等情况告警。
工程动作：每个告警要有触发条件、alert_level（告警等级）、影响范围、负责人、处置建议和恢复条件。不要所有告警都打到同一个群，也不要把低价值噪音变成告警疲劳。
面试说法：我会把告警按业务影响分级。模型调用失败、成本异常、安全事件和高风险工具异常要进入不同告警路径，并附带 trace_id（追踪编号）和 dashboard（看板）链接，方便快速定位。
Dashboard（看板）
人话解释：dashboard（看板）是把指标、趋势和异常用可读方式展示出来，让不同角色快速判断系统状态。
项目位置：工程师看错误率和延迟；客服主管看转人工、满意度、工单积压；运营看检索无命中、热门问题、知识库缺口；老板和销售看租户成本、毛利和套餐使用量。
工程动作：不要做一个所有人都看不懂的大屏。按角色设计看板：工程看板、质量看板、成本看板、安全看板、商业看板。每个指标都要能继续下钻到 trace_id（追踪编号）或样例。
面试说法：我的 dashboard（看板）不是装饰图表，而是把 Agent 上线后的质量、成本和风险变成可运营数据。它能帮助排障、优化知识库、控制成本和支撑报价。
Replay（复盘）
人话解释：replay（复盘）是还原一次 Agent 处理过程，用来回答“当时系统为什么这么做”。它不是让模型重新随机回答，而是查看当时的输入摘要、检索命中、模型版本、工具结果、审批状态、护栏判断和最终回答。
项目位置：客服主管处理投诉时，需要复盘某次对话为什么答错；工程师排查工具失败时，需要复盘工具参数和错误码；安全同事调查越权尝试时，需要复盘权限决策和护栏事件。
工程动作：为复盘保存必要证据：trace_id（追踪编号）、关键 span（片段）、引用资料编号、模型名称、Token（文本计量单位）统计、工具调用结果、权限决策、审批状态、最终回答和用户反馈。敏感内容要脱敏，复盘权限要受控。
面试说法：我会把 replay（复盘）设计成客服质检和工程排障工具。它能解释一次回答的来源、工具结果和安全决策，但不会无限保存用户隐私原文。
本章在客服工作台中的位置
可观测性可以理解为客服 Agent 工作台的运行控制面。它不直接回答用户问题，但它让每个回答、每次工具调用和每笔成本都可追踪。
| 工作台层级 | 本章负责什么 | 典型观测点 |
|---|---|---|
| 用户入口层 | 请求、身份、租户、限流 | session_id（会话编号）、user_id（用户编号）、tenant_id（租户编号）、rate_limit_status（限流状态）。 |
| 会话状态层 | 多轮对话和任务状态 | 当前意图、需要用户补充的字段、审批状态、转人工状态。 |
| RAG 层 | 检索质量和资料命中 | retrieval_hits（检索命中）、source_id（来源编号）、无命中率、权限过滤结果。 |
| 模型调用层 | 模型成本、延迟和错误 | model_name（模型名称）、input_tokens（输入文本计量）、output_tokens（输出文本计量）、latency_ms（延迟毫秒）。 |
| 工具调用层 | 工具成功率和业务动作 | tool_call_count（工具调用次数）、tool_name（工具名称）、错误码、幂等结果。 |
| 审批与安全层 | 审批卡点和安全事件 | approval_status（审批状态）、alert_level（告警等级）、error_code（错误码）、安全事件类型。 |
| 看板与复盘层 | 运营、排障、报价 | 成本看板、质量看板、告警记录、replay（复盘）入口。 |
如果第 1.6 章 Tool Calling（工具调用）让 Agent 能办事，第 2.13 章安全让 Agent 在允许范围内办事，那么本章就是让团队看见：它到底办了什么事、花了多少钱、哪里出错、谁需要处理。
系统流程图
这张图有 4 个重点：
读图重点：先读上组：入口生成 trace_id、记录请求并决定是否限流；再读下组：检索、模型和工具各自留下 span，失败进入兜底，最终回答统一更新指标、成本和看板，并按阈值告警或等待 replay。
- trace_id（追踪编号）必须从入口贯穿到检索、模型、工具、护栏和最终回答。
- 每个关键节点都要能记录耗时、状态、错误和成本。
- 限流、告警和复盘不是额外功能，而是上线后控制风险的基础能力。
- 可观测性最终要服务排障、质检、成本控制和商业报价。
模块拆分
可观测性可以拆成 10 个模块。它们不一定都要独立服务，但职责要清楚。
| 模块 | 职责 | 输入 | 输出 |
|---|---|---|---|
| Trace（追踪） Context（上下文） | 生成和传递 trace_id（追踪编号）、span_id（片段编号） | 用户请求、会话、内部调用 | 可贯穿全链路的追踪上下文。 |
| Event Logger（事件日志器） | 记录结构化业务事件 | 请求、检索、模型、工具、审批、护栏结果 | 可检索日志。 |
| Span Recorder（片段记录器） | 记录每个节点的开始、结束、耗时和状态 | 检索、模型、工具、审批节点 | 调用链追踪数据。 |
| Metrics Collector（指标采集器） | 聚合延迟、失败率、命中率和限流次数 | 日志和调用链事件 | 指标数据。 |
| Cost Ledger（成本账本） | 估算并归因模型和工具成本 | 模型名称、Token（文本计量单位）、租户、工具 | 成本明细和汇总。 |
| Rate Limit Manager（限流管理器） | 判断是否允许继续调用 | 用户、租户、模型、工具、预算、时间窗口 | allow（允许）、warn（预警）、block（阻断）、degrade（降级）。 |
| Alert Router（告警路由器） | 根据规则发送告警 | 指标、错误、成本、安全事件 | 告警记录和通知。 |
| Dashboard Service（服务层） | 展示趋势、异常和下钻入口 | 指标、成本、日志摘要 | 工程、质量、成本、安全和商业看板。 |
| Replay Store（复盘存储） | 保存可复盘证据 | trace（追踪链路）、引用、工具结果、回答 | 质检和事故复盘材料。 |
| Data Governance（数据治理） | 管理脱敏、访问权限、保留周期 | 日志内容、用户角色、合规策略 | 安全可用的观测数据。 |
这些模块的共同原则是：观测数据要能串起来、能聚合、能下钻、能脱敏、能用于决策。