1. 一次真实告警的解剖：502不只是“坏了”，它是运行时发出的数据包

先看一条我昨天半夜收到的报错，原封不动贴在这里：

获取首页数据失败: exception: 伺服器错误 502: <!doctype html><html lang=

如果你只是瞄一眼，这大概就是一句“首页接口挂了”的告警。但把它当成工具运行时里的一份数据来读，信息量其实很密：报错来自“获取首页数据”这个动作；异常类型是“伺服器错误 502”；响应体把一整个HTML页面的开头也透传出来了。最后那一截被截断的<!doctype html><html lang=，说明上游网关根本没有按接口协议返回JSON，而是把一整张错误页当成了响应体扔回来。

这就是我在这套“P04 工具运行时”系列里想系统讲清楚的一件事：失败不是异常状态，失败是一种数据。它和请求耗时、成功量、QPS一样，是运行时持续产生的信号，只不过我们过去习惯把它当成“要消灭的东西”，而不是“要分析的东西”。

传统思路下，接到这种报警，第一反应是登录服务器，看日志，重启服务，糊一个临时修复，然后祈祷别再发生。而数据思路下，同样的失败会被记成一个结构化事件：发生在什么时间、哪个模块、对应哪个上游、失败码是什么、响应里带了什么线索、跟哪个trace关联。这些字段聚合起来，我们可以回答“这个失败是小概率杂音还是系统恶化信号”，而不是每次都被它牵着鼻子走。

今天这篇就以工具运行时的视角，把我这几年把“失败”当数据来建设的完整经验写出来。适合正在做工具链、自动化平台、内部服务集成，或者一个人维护一堆脚本但经常被报错邮件骚扰的开发者。这套思路不需要很重的基建，很多环节用一个脚本加一张表就能起步，但方向对了，后面平台化是水到渠成的事。

先说清楚“失败是数据”和“异常捕获”的区别：异常捕获是单点动作，抓到就算完；失败是数据则要求你为失败“建模”。从开始到落地，大概要经过采集、分类、存储、分析、告警、沉淀六步，每一步都有容易踩的坑。下面按这条线展开。

2. 为什么“失败是数据”值得当成工程方法来建设

2.1 现代工具运行时里的失败密度，远比你想象的高

很多人对“失败率”的直觉是错的。单个接口看，成功率99.9%很漂亮；但当你运行的是一个会连续调用几十个接口的批量工具，情况就完全变了。

举个例子：一个自动发布工具，从触发到完成要依次完成代码拉取、依赖安装、静态检查、构建、镜像推送、环境更新六个环节。假设每个环节的失败率只有1%，六步全部成功的概率是0.99^6 ≈ 94.1%，也就是说每跑二十次就会有一次整体失败。如果某些环节依赖第三方服务，单步失败率到5%也不奇怪，那整体成功率会掉到73%左右。失败不是黑天鹅，它是系统里的常规构成。

所以很多工具运行时的维护者会有一个错觉：“我写的工具大多数时候是正常的”。但把失败当成数据去统计之后会发现，失败是一个稳定的流量来源，而不是偶发事件。既然它不是偶发，就必须有系统化的处理方式，靠人工盯是盯不过来的。

2.2 可观测性的下一层：从“错误日志”到“错误数据”

“日志”和“数据”的区别，不只在于格式。日志是给人读的，数据是给系统算的。

一条传统错误日志什么样？[ERROR] 2025-01-15 02:33:11 fetch index failed: 502。人看到能大概明白，但机器没法从这条文本里拆出“失败类型”“关联请求ID”“影响模块”这些维度。只有当失败被转成有字段、有类型、有标签的结构化事件，它才能进入统计、聚合、同比环比、异常检测这些流水线。

用生活类比来说：旧方式像你手写一张便签“牛奶喝完了”，贴冰箱上，只有你路过才看得到；数据方式是超市的进销存系统，每次拿走一瓶都扫码，系统自动知道什么商品消耗得快、什么时间容易断货。面对工具运行时，只有后者才能支撑起“预测失败”“提前干预”这类动作。

2.3 这套方法论对小团队尤其友好

提到可观测性平台，大部分人想到的是“要上一套庞大的监控系统”，于是望而却步。但“失败是数据”更准确的定位是一套思维方法，它优先解决的是“对失败的认识”，其次才是工具选型。

小团队完全可以这么做：捕获层写一个统一的错误封装函数，存储层就是一个日志文件或者一张数据库表，分析层每天跑一个简单的聚合脚本，告警层一个月后自然知道阈值该设在哪。这套跑通了，再谈引入更重的平台。反过来，一开始就上重平台而没有思想框架，结局往往是采集了一堆数据却不知道拿它们干什么。

3. 把失败变成数据的具体做法：一条完整的事件管线

我会按一条真实会跑的事件管线来讲，每一步都会给出可以“抄作业”的设计。这里的场景假设是：你手上有一个工具运行时，它可能是定时脚本、内部平台后端、或者集成调度器，下面这套东西可以直接套。

3.1 第一步：拦截所有失败，统一结构化

第一个动作是让所有失败走同一个出口。很多代码库里try...catch散落得到处都是，有的打日志，有的直接吞掉，有的弹窗提示，导致失败无法聚合。正确的做法是封装一个统一的captureError(event)入口，把散落的捕获收敛起来。

一个失败事件最少要包含下面这些字段，建议做成结构化的接口：

以开头那条502为例，结构化之后大概是：

time: 2025-01-15T02:33:11+08:00 src: fetcher.index_page op: get_homepage_data type: HttpError code: "502" message: "upstream returned 502 with html body" context: {"url": "https://api.internal/homepage", "resp_prefix": "<!doctype html><html lang="} trace_id: "ab12ef" env: prod

这样处理之后，“失败”这件事才第一次获得了被统计的资格。你会发现，真正重要的往往不是那个错误码，而是context里透传出来的蛛丝马迹。

3.2 第二步：错误分类体系——别急着修，先归因

把失败采集回来之后，不是立刻去修，而是先分类。没有分类的数据是杂物，分类之后才变成资产。

我常用的是三个维度的分类：

按失败位置分，失败发生在你控制的代码里，还是依赖的上游接口里，还是网络链路的某个中间节点？这条决定了“我能不能修”“该找谁修”。

按失败性质分，瞬时性的还是持续性的？网络抖动、单次超时往往是瞬时的；接口逻辑变更、证书过期、磁盘写满往往是持续性的。

按可恢复性分，失败之后重试有没有意义？超时重试有意义；404重试没意义；421、502这种要根据上游状态决定是否重试。

把这三个维度编码进事件的标签里，比如loc=upstream、intermittent=true、retryable=false，后面分析时就能很快筛选出“需要人工介入的失败”和“仅仅是运行时噪声的失败”。很多团队在失败处理上最大的浪费，就是在不可恢复的失败上反复重试，在做不到的事上消耗大量注意力。

3.3 第三步：存储与产出——失败数据的冷热分离

存储不求复杂，但要想清楚“热数据”和“冷数据”的分工。

热数据指最近几个小时内的原始失败事件，主要用于实时定位问题，查询要快。比如查“过去10分钟里get_homepage_data的失败样本”，你希望秒回。这个直接放ES或者ClickHouse都行，没有这些的话，Redis里存一个滚动窗口也不是不行。

冷数据指按小时或按天聚合之后的统计结果，比如“每小时的请求量、失败量、失败率、按错误码聚合的Top N”。这些数据量小得多，放MySQL或者SQLite都足够。分析的日常操作都在冷数据上做，避免每次统计都扫一个巨大的原始表。

一个比较稳的管线设计是：运行时事件 → 本地缓存/消息队列 → 异步落库 → 定时任务做聚合。如果量不大，甚至可以直接在进程里塞一个队列，每攒满50条就批量写入一次，不要在热路径上同步写库。失败数据本身是诊断系统用的，不要让诊断系统拖垮业务本身。

3.4 第四步：让失败数据说话：分析与告警

有了分类模型和数据底座，接下来才谈得上告警。

我强烈不建议“每条失败都发一条告警”的做法。失败是数据意味着它是连续信号，信号应该用趋势、分布、偏差来刻画，而不是逐条报警。否则，凌晨三点你会被一条毫无意义的瞬时超时弄醒，而真正的大规模故障反而被淹没在告警洪流里。

更合理的做法是：

按失败率而不是失败次数告警。绝对次数小但成功率很高的系统，可能是正常波动；而次数不大但占比从1%跳到30%的情况，才是真问题。

按维度组合告警。比如只看全局失败率可能没事，但按src + error_code组合看，某个模块的失败率已经爆表。这就是降维视角的价值。

按“变化量”告警。失败率的绝对值不重要，重要的是它相对于基线的偏移。周环比、天环比，这类偏差才是可行动的信号。基线的计算可以用前七天同时段的数据，对周期性负载的系统尤其有效。

这样配完之后，告警从“事后的惊叫”变成了“事中的数据摘要”。你每天醒来不用看几十条告警，只需看几条必要的摘要，这个体验谁用谁知道。

4. 围绕“失败数据”最常见的三类分析，以及我从实际问题里学到的判断

数据建设不是终点，关键是用它回答实际问题。下面三类分析是最容易见效的，同时也是最容易暴露设计缺陷的。

4.1 把502错误信息透传成HTML这件事的启示

回到开头那条报警。当时我把上下文里透传的HTML片段摊开看了一眼，发现一个有趣的事实：网关在返回502的时候，把一整张错误页当成响应体返回给调用方了。调用方代码直接按字符串截断存进字段，于是数据库里出现了一条半截的HTML。

这件事在“失败是数据”的思路下，至少有三层可挖：

第一层，上游并没有遵守“接口只返回JSON”的协议约定。这个失败不是简单的网络抖动，而是协议边界的击穿。光看错误码根本发现不了这一点，只有把失败当数据、带上context字段记录响应内容，才能真正归因到根子上。

第二层，这说明失败事件里不能只存错误码和message，必须保留一段原始上下文的快照。否则问题复现的时候，你手里只有“502”这个结论，没有任何现场物证。

第三层，这种错误其实提示了一个设计缺口：工具运行时在解析上游响应时，缺少一道“内容黑白名单检查”。你可以在失败数据里加一个启发式规则：上游响应体如果是HTML开头，而接口声明的是JSON，那就不该走常规解析流程，直接标记为protocol_violation。这类规则写进分析层之后，等于让失败数据自己拥有“发现新问题”的能力。

4.2 安全连接失败那类问题：失效原因本身也是一种数据

“建立安全连接失败 由于不能验证所收到的数据是否可信”这句报错，出现在很多网络异常的上下文里。单独看它，感觉像一句很含糊的废话，但落到失败数据的维度上，它指向的其实是三个完全不同的可能：证书链不可信、证书过期、或者本地系统时间不对。

这三种原因在运行时层面需要完全不同的处理方式——证书链不可信可能要更新CA库；证书过期要检查上游的证书签发和你的更新策略；系统时间不对那问题根本不在网络上。

这就是“失败是数据”极有说服力的一个场景：相同的一句话，背后的数据维度完全不同。如果你只把报错文本当成字符串存下来，那它就是一堆“不可验证”的杂物。但如果你在采集时把TLS层的参数、证书的签发和到期时间、本机时间偏移量一并记录，失败就变成了有归因能力的证据链。

所以设计失败事件字段时，对这类“复合型报错”，要预留detail列表，把底层库暴露的参数原样塞进去，而不是只用一句话概括掉。

4.3 从失败数据里找“升级信号”和“恢复信号”

同一种失败码，在不同时间、不同负载下的意义截然不同。

举个例子：某接口在业务高峰时段出现连接超时，这个现象如果与并发量曲线强相关，那它大概率是容量问题，是“升级信号”，意味着你该扩容或者做限流了。但如果同样的失败出现在凌晨低峰，那反而是个异数，值得立刻深挖——可能是上游在发版，可能是网络配置变更。

坏事和好事有时候藏在同一种失败code里。之前我做过一个工具链的失败率分析，发现某失败码的周环比上升了50%，本来以为是上游变差了，结果细分时段之后发现，所有增长都集中在一个特定的查询模式下。那不是失败，是上游完善了校验逻辑，返回了一个更明确的错误码，而我们的工具没适配。没有失败数据的时间维度分析，我们会把这个升级信号误判成故障。反过来说，“恢复信号”也可以从数据里看：一个持续很久的高失败率，开始阶梯式下降，往往是对应的修复版本灰度到了某个比例。从失败数据里能看到系统的自愈过程和干预效果，这是单独看日志完全不具备的视角。

5. 我踩过的坑：失败数据建设的四件事

这一节是实打实的经验沉淀。理念听上去都挺对，但落地过程中的细节会疯狂打脸，下面是我踩过之后觉得最应该被提前讲清楚的四件事。

5.1 时间戳必须带上时区和来源时钟

看起来最基础的字段，恰恰是最容易埋雷的。当时跑批任务报失败，我按时间排查，发现同一批任务里有两条样本，一个时间戳是23:01:02，另一个是15:01:02。一开始还以为是跑批逻辑的并发问题，结果查下去发现，第二个样本来自一台时区没校准的容器，它记录的UTC时间被当成北京时间用。

从这之后，我要求所有失败事件里时间戳必须显式带时区，而且采集端一律用UTC存储，展示端再做本地化。还有更隐蔽的坑：某些运行环境里time()和time_ns()混用，精度不一致会导致排序错乱。统一用同一种单位纳秒或毫秒记录，不做隐式转换，这是惨痛教训换来的规矩。

5.2 维度组合是基数爆炸的源头，要做降维与抽样

失败的维度多到一定程度，“按维度聚合统计”这件事会变得极其昂贵。比如src字段如果记录了包含用户ID的URL，那每个失败事件基本上都是独一无二的维度组合，聚合结果会碎成一地，根本没法看。

后来我定了一个规则：上下文细节可以记，但参与分析的维度必须是有限枚举值。URL这类高基数字段，要么去掉查询参数做归一化，要么单独存进context里不参与聚合。分析只针对src、type、code、env这些有限维度。如果某些场景实在需要高基数分析，就做采样，保留每类失败的前N条明细用于下钻，而不是全量参与计算。这个设计能保证你的失败数据越用越顺手，而不是越存越卡。

5.3 错误码设计：宁可丑但稳定，不要频繁变

失败数据要发挥长期价值，核心依赖错误码的稳定性。但实际工作中，上游服务的错误码经常变：今天BAD_GATEWAY，明天upstream_error，后天变成502_GW_TIMEOUT。如果你在归一化规则里频繁调整映射，前一天能按码聚合的数据，第二天就断档了，同比环比全部失去意义。

我的建议是：建议在自己的工具侧做一层稳定的内部错误码，上游的千变万化都映射到这几个内部码上。内部码宁可粗糙一点、丑一点，也不要跟着上游改。页面级的PAGE_FETCH_FAILED、PAGE_PARSE_FAILED、PAGE_TIMEOUT、PAGE_AUTH_FAILED，这几个颗粒度的码够用几个月。等数据积累多了，发现某个内部码的样本量爆炸了，再考虑拆分。先稳定，后精细，顺序不能反。

5.4 去重永远放在分析之前，不然“失败是数据”会变成“失败是海洋”

工具运行时有个很常见的现象：一个上游故障会带来级联雪崩，同一个根因在几分钟内以同样模式重复几百上千次。如果分析层直接拿原始事件统计，失败率会严重失真，你会以为系统已经全挂了，实际只是源头一个环节在抖。

所以所有失败数据在进入分析层之前，必须有一个去重步骤。去重的粒度按场景定：单机单进程内，同一trace_id + type只算一次；跨节点级联的场景，同一error_code + context_hash在窗口期内只算一次。这个规则要写清楚，不然统计时“失败次数”远大于“失败影响面”，一种失败会掩盖另一种失败，数据越多越糊涂。

我还踩过一个反方向的坑：去重做得太激进，把同一时段里不同机器上的真实独立失败也合并了。所以去重最好基于一个能唯一定位“根因”的字段联合——宁可保守一点，保留一定重复，也不要误合并导致丢掉真实信号。

6. 从失败数据里长出来的“运行时免疫力”

把失败当成数据经营了一段时间之后，最明显的变化不是系统不再失败，而是你对失败的感知变成了“读趋势”而不是“被刺痛”。

以前每次收到报警，第一反应是“为什么又出问题”，然后是手忙脚乱上服务器查日志、重启、给上游提工单。现在同样的场景，我打开失败数据的聚合面板，先看失败率曲线、维度分布、变化趋势，再决定是重试、降级、提工单还是直接修复。后者的决策质量高很多，因为它建立在结构化的事实之上，而不是基于一次随机样本的情绪反应。

这套“失败数据”体系的另一大好处是可以积累出运行时的“经验库”。某类失败第一次出现，你需要人工分析归因；当同样的失败模式第二次、第三次出现时，分析层就能凭借历史数据直接给出检查清单和候选修复方案——被标注过的失败类型会自动沉淀。这个过程中最让我感慨的是：过去我们用“避免失败”来追求稳定，现在反过来，用“拥抱失败的数据”来获得稳定；后者才是真正可持续的工程路径。

最后分享两个小技巧：第一，失败数据的字段宁可多存，不可少存，因为历史事件不可再生——事后补不了当时缺失的现场信息。第二，至少每季度要回过头看一次“失败样本全集”，不要只看聚合统计，偶尔翻翻原始上下文快照，你会发现聚合挡住了很多没被建模进维度的新问题。这两个动作不花时间，但能保持系统对“未知失败”的灵敏度，这是整个体系里最容易遗漏、却最值得坚持的部分。