智能体工程 · 17h
失败率升了,是业务变坏还是记录质量有问题?
读完能做的判断:先归并请求再分窗口,核对样本数、p95与告警复核条件。
17h · 监控窗口与告警复核
⏱ 阅读约 28 分钟 · 动手实践另计
本章保留教学代码、路径说明与历史验证结论;完整实验工程和运行记录未随本站及公开仓库分发。命令用于说明调用方式,复现需自行准备对应实现、数据与环境。
一句话带走:先归并完整请求,再按终态切窗口;失败率与延迟分别检查样本,记录有缺口时先复核数据质量。
本节沿用请求追踪与脱敏日志的净化事件,把“看到一个数字”推进到“能解释一次窗口判断”。服务入口见企业助手服务层实战,变更核对见模型版本清单与回滚预检。教学实现涉及监控代码(examples/knowledge-assistant/monitor_lab.py)与行为测试(examples/knowledge-assistant/test_monitor_lab.py)。
1 · 先跑一次,认出两类证据
运行 demo,核对 32、14、8 分别数什么,再修改窗口观察各计数的变化。
以下是原示例父项目目录内的主环境命令。最后一行的目录必须尚不存在,再次运行请改编号。
examples/knowledge-assistant/.venv/Scripts/python.exe -X utf8 examples/knowledge-assistant/monitor_lab.py demo --output examples/knowledge-assistant/.runtime/monitor-first
在示例 knowledge-assistant 目录内,对应命令为 python monitor_lab.py demo --output .runtime/monitor-first。默认生成带 UTC 时间与随机后缀的新目录。已有空目录也会拒绝。
| 文件 | 用来回答什么 |
|---|---|
| summary.json | 两类结果、预期与机械检查 |
| manifest.json | 环境、代码与输入哈希、参数 |
| actual-trace/sanitized-events.json | 真实本地服务产生的净化输入 |
| synthetic-inputs.json | 原创受控场景,明确标记 synthetic_replay |
actual_local 调用一次已有追踪 demo,使用真实临时 SQLite 和 ProductService、受控传输,零网络和生成模型。数据库位于专用临时目录,结束后删除;不接告警服务,不执行扩容、熔断或回滚。
检查点 1:合成场景全部通过,能推出线上响应速度吗?
不能。合成回放验证窗口规则,本机耗时描述本次运行,都没有测线上容量。
2 · 归并在前,窗口在后
一次准入、两次传输尝试、一次完成共四行,只有一个服务请求。调用 trace_lab.summarize_audit 对整个有界列表归并,再以可信终态的 created 选择窗口,避免重试扩张分母。
窗口是 [start,end):终态等于 start 时纳入,等于 end 时排除。准入在窗外、完成在窗内仍纳入。先裁原始行会丢失准入,把完整请求误判为缺准入。
例如窗口 10 到 11:准入 1、完成 10 的请求纳入一次;准入 9、失败 11 的请求排除。
时间参数必须与源事件使用同一时钟域。API 不证明多机器同步或日志收全;把终态选窗口径用于自己的服务前,应取得团队共识。
走神救援: 只盯最后一条可信终态,问“它在哪个窗口”,然后回头确认准入仍在完整输入里。不要把尝试时刻当成请求完成时刻。
检查点 2:准入在窗外、完成在窗内,能先删掉准入吗?
不能。先归并全批才能验证请求完整性。窗口只决定可信终态是否参与本次业务指标。
3 · 失败率先说清分母
服务失败率为 failed 除以 completed 加 failed。service_request_count 就是这两个状态的请求数,不能用事件数、尝试数或所有入口请求替代。
本次真实演示共 32 条事件、14 个请求:completed 五个、failed 三个、rejected 五个、cancelled 一个。服务请求数八个,失败率为三除以八,即 0.375。失败夹具是故意安排的,不能据此推断产品在真实用户中的故障概率。
认证、权限、额度或重复编号造成的拒绝,以及取消都另计,不混为后端错误。failed 前即使有五次尝试,仍贡献一个分母和一个失败。
error_rate.sample_count 同样使用这八个服务请求;window_state_counts 单列每种状态。
阈值比较使用大于或等于。四个 completed 加一个 failed,失败率恰好 0.2,达到固定教学阈值。下一步应复核失败分类、夹具说明和影响范围。
检查点 3:五次拒绝应加入本节失败率分母吗?
不加入。分母只有 completed 和 failed;要衡量入口可用性,应另行说明指标定义。
4 · p95 与最低样本数分别核对
延迟只取 completed 的终态 elapsed_ms。传输尝试耗时、failed 耗时和 rejected 耗时都不进入这个成功延迟指标。先排序,再使用 nearest rank:数组下标为 ceil(0.95*n)-1。没有成功耗时样本时,值为 null;null 表示没有可算数据,不能当成零毫秒。
二十个成功样本为 1 到 20 毫秒时,p95 为 19 毫秒,不做插值。只有五个样本时,p95 就是最大值,因此应一起看样本数量。
失败率样本数与延迟样本数各自比较 min_samples,默认五。四个成功加一个失败时,失败率已经有五个样本,成功延迟却只有四个:前者 ready,后者 insufficient_data。两者都低于阈值仍不能把窗口标绿;没有足够延迟证据。
| 可用状态 | overall |
|---|---|
| 任一 ready 指标达到阈值 | alert |
| 两个指标都 ready 且均未达到阈值 | ok |
| 没有 ready 告警,至少一个指标样本不足 | insufficient_data |
| 数据质量阻断 | quality_blocked,优先于业务判断 |
本次成功 p95 为 94 毫秒、样本五个,换运行可能不同。失败率已命中,overall 仍是 alert。五样本、0.2 与 1000 毫秒都是演示参数,不能作为生产推荐。
检查点 4:失败率样本五个、成功延迟样本四个且都未命中,overall 是什么?
是 insufficient_data。两个指标都 ready 且都未命中才得到 ok。
5 · 记录质量先于业务告警
数据不能信时,先做质量复核。整批中任意非法事件、invalid 请求、incomplete 请求,或者同 trace 按 event_id 排列后 created 倒退,都会使本次 quality_blocked。即使坏行看起来位于窗口之外,也不能把无法可靠分配窗口的记录悄悄丢弃。
这是保守的整批隔离约定。业务数量与指标数值、ready 仍保存,但 threshold_hit 为 null,状态阻断,暂停正常或异常业务结论。
| quality 字段 | 含义 |
|---|---|
| invalid_event_count | 原聚合发现的非法事件条数 |
| invalid_request_count | 生命周期或字段矛盾的请求数 |
| incomplete_request_count | 有请求记录但没有可信终态 |
| clock_reversal_request_count | 按事件编号检查后时间倒退的请求数 |
| missing_completed_elapsed_count | 窗内 completed 缺少终态耗时 |
质量计数可能重叠,不能相加当作独立故障总数。窗内完成缺耗时会阻断;窗外正常完成缺耗时已能可靠排除,不影响本窗。输入乱序但时间按 event_id 不倒退,也不等于逆时钟。
给健康输入追加一条坏事件,overall 变成 quality_blocked。先修输入来源,不能把阻断画成正常或后端故障。
检查点 5:窗外只有 admitted 的请求能静默忽略吗?
不能。incomplete 没有可信终态,不能可靠分配窗口,因此整批阻断。
6 · 读取结果,再调整输入
下面代码在仓库根运行 Python,读取第一节产生的汇总,不修改输入。跨窗场景里准入在 9、完成在 10,窗口从 10 开始,仍数一次;min_samples 为一,仅用来演示单请求规则。
import json
from pathlib import Path
p = Path("examples/knowledge-assistant/.runtime/monitor-first/summary.json")
summary = json.loads(p.read_text(encoding="utf-8"))
print(summary["actual_local"]["assessment"]["service_request_count"])
print(summary["synthetic_replay"]["mechanical_failed"])
结果是八个服务请求、零个机械失败。自行调用 assess_window 时,start 等于 end 会抛出 ValueError;空窗得到 insufficient_data;窗内完成缺耗时会阻断;负耗时由原聚合判定非法。
接口接受最多一万条的 list;start/end 有限非负且前者小于后者;min_samples 是一到一万的整数,bool 不能冒充。失败率阈值在零到一,p95 阈值有限为正。JSON 读取拒绝重复键、非有限常量、错误顶层形状与超过八 MiB 的输入。
检查点 6:min_samples=True 为什么不是“一条样本”?
Python 的 bool 可以参与部分整数运算,但这里明确拒绝它,避免配置误写后悄悄降低最低样本门槛。
7 · 用受控回放验证判断边界
真实输入的窗口覆盖全部源事件,固定使用五样本门槛。前后输入哈希相同说明本次分析没有改变文件;代码与数据哈希方便复查版本,但不构成数字签名,也不能抵抗目录被他人并发替换。演示假定调用者可信且拥有专用输出目录。
十六个合成场景逐项记录参数、预期与实际结果,覆盖边界等值、两类告警、缺数、空窗、坏事件、不完整、逆时钟、缺耗时、跨窗和重试。真实耗时不作固定预期,合成耗时验证分位数。
先看 case 的 checks,再看 assessment。低样本预期 insufficient_data,得到这个状态就是测试成功;坏事件正确阻断同理,不能为了全绿改为 ok。
CLI 输入、JSON 或 IO 问题输出固定 JSON、退出二;内部异常或机械失败退出一。alert、quality_blocked、insufficient_data 本身不导致程序失败。下一轮仍用新目录保留证据。
检查点 7:合成坏事件正确得到 quality_blocked,CLI 应自动失败吗?
不应。它满足该场景的机械预期。只有机械结果不符或内部程序异常才属于退出一的失败路径。
8 · 把一次结果放回持续复核
一次告警是复核入口。先确认时间范围、质量与样本,再核对失败分类和夹具影响;保留参数,按可比较口径重跑。不同窗口长度、分母或样本数的数字不能直接解释成改善。
长窗口积累样本,也可能掩盖集中故障;短窗口更快但更容易缺数。门槛应结合业务损失与历史分布。本节没有实现 SLO burn-rate、多窗口关联或线上通知。
监控汇总不会回显 trace IDs、问题正文、凭证或异常原文。受限净化事件文件仍含关联编号,应按既有诊断输入管理权限;读者看到安全汇总,不能推出所有日志出口都已脱敏。这里也没有证明采样无丢失、全链路覆盖或身份认证服务可靠。
走神救援: 先问分母是谁、样本够不够、质量可信不可信,再谈阈值。能区分 alert 和 quality_blocked 的下一步,就完成最小目标。
检查点 8:一次本机窗口 alert 是否授权自动回滚?
没有。应先复核数据与影响范围,任何实际回滚还需要对应发布契约、权限与独立证据。本实验没有执行回滚或任何自动治理动作。