# 错误跟踪系统建设的必要性与路径分析

- 版本：v1.0（终稿）
- 更新日期：2026-10-07
- 讨论组：Claude（主持 Sonnet 5 ×2、核验 Opus 5.5）、Codex（gpt-6.1-sol，质疑席）、Antigravity（gemini-3.8-flash-high，顾问席）

## 一、结论

1. **错误跟踪的价值不在“采集异常”，而在“管理缺陷”。** 日志、APM、OpenTelemetry（OTel）都能采集异常；错误跟踪系统提供的是另一层能力：按指纹聚合去重、识别首次出现与回归、关联发布版本与可疑提交、还原压缩或混淆后的堆栈（Source Map、dSYM、ProGuard），以及指派、状态流转和修复验证。
2. **已有 APM 不等于不需要，但也不等于要另建一套。** 是否建设看缺口，而不看“有没有 APM”：
   - 现有 APM 已含错误跟踪模块，且覆盖实际终端（后端、Web、移动端）→ 先启用并验证该模块，不另建；
   - 有 Web、移动端、小程序等客户端，而现有体系没有对应的崩溃采集与符号化能力 → 需要补建，这是最硬的理由；
   - 只有 Trace/日志检索、缺少聚合与缺陷工作流，且发布频繁、多团队协作 → 需要补建。
3. **路径：** 按“现有 APM 错误模块 → SaaS → 自托管”的顺序评估，不从零自研；先小范围试点并用指标决定是否推广。负责人、分诊时限、发布关联和数据脱敏是成败关键，缺了这些，系统只会变成没人处理的告警池。
4. **决策层级要区分。** 单个产品团队可直接按上述条件选型；平台级标准化还须统一 SDK 规范、脱敏基线、权限和费用分摊，组织成本明显更高，宜先由一两个团队试点再推广。

“错误跟踪不如 APM 普及”目前只是观察，讨论组没有找到可靠的普及率统计，不作为论据。

## 二、能力边界

| 能力 | 错误跟踪 | APM / Trace | 日志 | OTel 规范 |
|---|---|---|---|---|
| 异常采集 | 有 | 有（Span 状态、异常事件） | 有 | 定义异常属性 |
| 指纹聚合、问题生命周期、回归识别 | 核心能力 | 部分产品内置 | 无 | 未定义 |
| 发布版本、可疑提交关联 | 有 | 部分产品内置 | 无 | 无工作流 |
| 客户端崩溃与堆栈符号化 | 核心能力 | 依产品而定（RUM/移动模块） | 无 | 无 |
| 延迟、拓扑、容量 | 无 | 核心能力 | 辅助 | 定义信号 |

要点：

- **OTel 只规范采集。** 其异常语义约定定义了 `exception.type`、`exception.message`、`exception.stacktrace`，并提示异常消息可能含敏感信息；没有定义问题聚合与生命周期[1]。因此“已接入 OTel 就不需要错误跟踪”不成立。
- **主流 APM 已把错误跟踪做成内置模块**，说明两者互补而非替代：Datadog Error Tracking 把相似错误聚合为 Issue，展示首次出现时间、受影响用户数与可疑提交，来源覆盖 APM、浏览器与移动 SDK、日志和 RUM[2]；New Relic Errors Inbox 按指纹分组，支持指派、忽略、标记在指定版本解决，覆盖 APM、浏览器、移动端和 Lambda[3]。已采购这类 APM 时，应先核对该模块是否在合同内。
- **打通而非合并。** 错误事件携带 `trace_id`，可从错误跳转到调用链。但不要假设一份 OTel 数据能直接喂给专用错误跟踪系统：OTel 原先把异常记为 Span 事件，该约定已弃用、改为记入日志，过渡期由配置开关决定输出哪种[12]；而 Sentry 的 OTLP 接入仍为公开测试版，接入时丢弃全部 Span 事件[4]。接入前须按目标产品文档验证异常数据的实际去向。

```mermaid
flowchart TD
    A["盘点：现有 APM/RUM 的错误能力与覆盖终端"] --> R{"命中第三节<br/>不建或缓建情形？"}
    R -- "是" --> X["不建或缓建"]
    X -.->|"条件变化时重新盘点"| A
    R -- "否" --> B{"现有模块能聚合去重、<br/>关联版本、指派闭环？"}
    B -- "能，且覆盖全部终端" --> C["启用并验证现有模块<br/>不另建"]
    B -- "不能，或缺客户端/符号化" --> D{"数据能否交给第三方 SaaS？"}
    D -- "能" --> E["SaaS 试点"]
    D -- "不能" --> F{"有运维 Kafka/ClickHouse<br/>等组件的能力？"}
    F -- "有" --> G["自托管 Sentry 试点"]
    F -- "没有" --> H["轻量自托管（如 GlitchTip）<br/>或其他合规产品"]
    E --> I["试点 4–6 周：达标则推广，<br/>不达标则重评缺口"]
    G --> I
    H --> I
    C --> I
```

## 三、适用条件与反例

**适合建设：** 有面向用户的 Web/移动端；每周或更频繁发布，回归识别有价值；多团队共用服务，需要把错误自动派给负责人；偶发故障多，仅看服务端错误率容易漏掉少量用户的持续失败。

**不建或缓建：**
- 纯后端服务，现有 APM 错误模块已覆盖聚合与指派；
- 低变更的遗留系统、离线批处理，作业失败告警加日志已能闭环；
- 没有修复负责人和分诊时限，上线只会增加噪声。

缓建后若新增客户端、明确负责人或发布加快，应重新盘点。需另建而数据须内留、又缺重型组件运维能力时，SaaS 与重型自托管都不适用，应评估轻量方案，而非不建。

## 四、如何建设

**1. 选型**

| 方案 | 适用 | 主要代价与注意事项 |
|---|---|---|
| 现有 APM 错误模块 | 默认起点 | 核实增量费用、客户端覆盖、符号化与聚类质量，以及错误事件是否受 Trace 采样影响 |
| SaaS | 缺少运维人力、需快速上线 | 按事件量计费，须配采样、客户端限频、入站过滤和配额消耗告警；核对数据处理地域与跨境条件 |
| 自托管 Sentry | 数据驻留要求明确、有平台运维能力 | 官方最低 4 核、16 GB 内存加 16 GB swap、20 GB 磁盘，推荐 32 GB 内存，并定位为“适合简单场景的最小部署”[5]；组件含 Relay、Kafka、Snuba、ClickHouse、Symbolicator、PostgreSQL、Redis 等[6]，升级、备份、扩容和值守都要计入人力 |
| 轻量自托管（如 GlitchTip） | 中小规模、数据须内部留存 | 兼容 Sentry 客户端 SDK[7]，必需依赖仅 PostgreSQL，Redis/Valkey 可选[8]；功能弱于 Sentry，需按需求验证 |
| 从零自研 | 几乎不建议 | 聚类、符号化、多端 SDK 的维护成本易被低估 |

许可证需准确表述：Sentry 主应用采用 FSL（Functional Source License），官方明确它不符合 OSI 的开源定义，两年后转为 Apache-2.0[9]。报告和内部文档应写“源码可得、可自托管”，不宜写“开源 Sentry”。

**2. 落地步骤**
1. 盘点现有 APM/RUM 的错误能力与终端覆盖，按第三节判断是否建设；
2. 选一个客户端应用和一个关键后端试点 4–6 周：接入 release、environment、服务标识和 `trace_id`，在 CI 中上传与版本匹配的 Source Map/符号文件；
3. 先建立基线，再比较新回归从出现到发现的时间、定位与修复时间、聚类准确率、有效告警比例和总成本；达不到约定门槛就不推广。

**3. 数据安全**
- 默认不采集请求体、凭据、Cookie、完整 URL 查询参数、局部变量；附件和会话回放单独评估，默认遮蔽输入；
- 在 SDK（如 `beforeSend`）或自控网关出站前脱敏，服务端过滤只作补充。Sentry 官方说明：若要求“数据绝不能离开我方系统”，不要依赖其服务端脱敏，附件与回放另有各自的隐私机制[10]；
- 上线前用合成的令牌、邮箱，分别验证错误事件、附件和回放的实际出站内容；
- 权限要实测而非只看配置：New Relic 文档说明，Errors Inbox 的标准角色限制只作用于错误组评论，只读用户仍可指派问题、修改状态[3]。同时配置项目隔离、最小权限、SSO/MFA、审计、保留与删除策略；
- Source Map 只上传给错误跟踪系统，不随公网产物发布；保护符号文件和上传令牌。

**4. 组织配套**
- 用 CODEOWNERS 或服务目录自动指派负责人，研发对自己代码产生的新问题负责；
- 按用户影响、关键业务失败和新版本回归分级：只有需立即处置的进入值班，其余进入缺陷队列；
- 把新问题和回归数纳入发布评审。

**关于收益数据：** Sentry 客户案例称 Forethought 通过代码负责人和每周审查，把解决时间“最多缩短 94%”[11]。这是厂商发布的单个案例，未经独立核验，不能作为通用 ROI；收益应以本组织试点数据为准。

讨论中未被采纳的不同意见见附录 A。

## 参考来源

访问日期均为 2026-10-07。

1. OpenTelemetry，Semantic conventions for exceptions in logs：https://opentelemetry.io/docs/specs/semconv/exceptions/exceptions-logs/
2. Datadog，Error Tracking 文档：https://docs.datadoghq.com/error_tracking/
3. New Relic，Errors Inbox 文档：https://docs.newrelic.com/docs/errors-inbox/errors-inbox/
4. Sentry，OTLP 文档：https://docs.sentry.io/concepts/otlp/ ；Traces：https://docs.sentry.io/concepts/otlp/direct/traces
5. Sentry，Self-Hosted Sentry：https://develop.sentry.dev/self-hosted/
6. Sentry，Application Architecture Overview：https://develop.sentry.dev/application-architecture/overview/
7. GlitchTip 官网：https://glitchtip.com/
8. GlitchTip，Installation：https://glitchtip.com/documentation/install
9. Sentry，Licensing：https://open.sentry.io/licensing/
10. Sentry Help Center，What are Sentry's data scrubbing options：https://www.sentry.help/en/articles/13964268-what-are-sentry-s-data-scrubbing-options
11. Sentry，Forethought 客户案例：https://sentry.io/customers/forethought/
12. OpenTelemetry，Semantic conventions for exceptions on spans（状态：已弃用，改用 [1]）：https://opentelemetry.io/docs/specs/semconv/exceptions/exceptions-spans/

## 附录 A：少数意见

1. **顾问席（agy）：** 前端、移动端“必须独立建设”，中大型组织宜选自托管。多数意见认为，只要现有 APM 的浏览器/移动模块已覆盖崩溃采集、符号化和缺陷工作流，就不必独立建设[2][3]；是否自托管取决于合规要求与运维能力，而不是组织规模。
2. **研究综合主持席：** 已重度投入 OTel 的组织，可先用 OTel 采集的异常（Span 事件或日志）加日志关联做“轻量错误跟踪”，聚合或符号化成为明显痛点后再引入专用系统。多数意见认可“先复用”，但指出这种做法没有缺陷工作流；而且如第二节所述，OTel 异常记录方式正在从 Span 事件迁往日志[12]，部分专用产品的 OTLP 接入又不接收 Span 事件[4]，后续迁移需单独规划采集。
3. **核验席：** 估计自托管 Sentry 约需 0.3–0.5 人运维。该数字没有可核查数据，仅供参考。

## 附录 B：篇幅统计

- 口径：正文指一至四节（第一节标题至“讨论中未被采纳的不同意见见附录 A”一句），不含 mermaid 源码、参考来源和附录；分别统计汉字数，以及“汉字 + 英文单词/数字串各计 1 字”的数，两者均计入表格内文字。
- 切分规则：汉字按 Unicode 区间 `[\u4e00-\u9fff]` 逐字计数；英文单词/数字串按正则 `[A-Za-z0-9][A-Za-z0-9._/\-]*` 计数，以点、下划线、斜杠、连字符相连的整体算 1 个（如 `exception.type`、`SSO/MFA`），`4–6` 中的连接号“–”不在其内，计 2 个。计数脚本随讨论记录归档，在 v0.2 上复算结果与下文所列 v0.2 数字一致。
- v1.0 结果：汉字 1860；汉字加英文单词/数字串（含引用编号）1999，未超过 2000 字。
- 历史版本（同口径）：v0.3 与 v1.0 数字相同；v0.2 为汉字 1828、合计 1965；v0.1 一至四节为汉字 1689、合计 1819，加上原第五节后汉字为 1920。
- 质疑席第 2 轮报告 v0.1 一至五节汉字 2034，与本口径不同（未说明是否计入 mermaid 等），差异原因未能确认。

## 更新历史

### v1.0（2026-10-07）

- 定稿。按讨论组规约，终稿修订差异（v0.2→v1.0，含 v0.3 修订与本次定稿改动）交 Codex（质疑席，gpt-6.1-sol）做最终复核。
- 本次定稿改动：版本行改为终态；第三节“完整自托管”改为等字数的“重型自托管”（采纳 Codex 最终复核的少数意见，与“缺重型组件运维能力”的前提和轻量自托管分支对应）；附录 B 结果改记为 v1.0，并注明 v0.3 与 v1.0 正文篇幅相同；新增本条。正文其余部分未改动，篇幅仍为汉字 1860、合计 1999。
- 通过情况：第 2、3 轮复审均满足插件法定人数，质疑席与核验席均作答；强席位提出的唯一阻塞项 B1（第 3 轮核验席）已修复并经核验席定向复核闭环。第 4 轮不需要。
- 最终复核结果：Codex 投 APPROVE，无阻塞项。确认 B1 闭环，流程图、第三节、更新历史与附录 B 一致；New Relic 权限范围的收窄与补回“最小权限”准确；未见新增表述与引用不符。Codex 未独立复算篇幅，采信脚本结果。

### v0.3（2026-10-07）

- 依据第 3 轮复审（终审口径，standard 深度，5 席）修订。独立意见阶段五席均投 APPROVE，插件法定人数满足（Codex 质疑席、Opus 核验席计入；agy 顾问席因未给出可校验的行号证据被插件判为未读稿，不计票）；质疑席与核验席均作答，无超时或成本中止。
- **阻塞项 B1（核验席，互评阶段提出，投 REVISE）：已修复。** v0.2 在流程图盘点后新增“命中第三节不建或缓建情形”出口，而第三节原第 4 条“数据须严格留在内部，又缺乏重型组件运维能力”的建议是评估轻量方案，即图中“轻量自托管”分支；按图会先停在“不建或缓建”，走不到轻量分支，图文矛盾，且由 v0.2 引入。按核验席最小修改建议二，把该条移出“不建或缓建”清单，改为清单后的说明“应评估轻量方案，而非不建”；流程图 R 节点不变，该情形经“数据能否交给 SaaS→运维能力”分流到轻量分支。战略主持席、顾问席在独立意见中把同一问题列为少数意见，本次一并闭环。修订后由核验席（Opus）定向复核：B1 已闭环，未引入新矛盾，表决 APPROVE（核验席未运行计数脚本，篇幅一项为推算）。
- 采纳的少数意见：
  1. “不建或缓建”不是终局（核验席、战略主持席）：流程图加“条件变化时重新盘点”虚线回到盘点；第三节补“缓建后若新增客户端、明确负责人或发布加快，应重新盘点”。
  2. New Relic 权限表述的范围（质疑席、核验席）：改为“Errors Inbox 的标准角色限制只作用于错误组评论”，与 [3] 原文“Standard role restrictions … are only enforced in the error group comments feature”一致。
  3. 补回“最小权限”（研究综合主持席、核验席）：v0.2 改写时误删，“权限实测”是验证手段，不能替代最小权限这一设计原则。
  4. 附录 B 写明切分规则（核验席）：给出汉字区间与英文切分正则；主持人按该规则在 v0.2 上复算，得汉字 1828、合计 1965，与 v0.2 附录 B 一致。
  5. 版本行更新为 v0.3 的实际状态（核验席）；定稿时改为终态。
  6. 定向复核中核验席的少数意见：第三节轻量方案一句限定为“需另建”时，避免在现有模块已满足要求时显得绝对；附录 B 复算说明指明所对照的是 v0.2 数字。
- 未采纳或不采信：
  - 核验席建议加注“R 与 B 可在同一次盘点中判定”：第三节第 1 条与 B→“启用现有模块”结论相同，不构成矛盾；篇幅余量不足，未加。
  - 顾问席建议 CI 自动注入 commit SHA 作为 release、原子上传 Source Map：正文第四节第 2 步已要求在 CI 中上传与版本匹配的 Source Map/符号文件，属实现细节，未另写。其所称“70% 以上前端反解失败源于 release 不匹配”无来源，不采信；其所述 v0.2“引入的重评触发标准”和“保障关键首发异常 100% 留存”在报告中不存在，属误读，不采信。
- 核实情况：[3] 由质疑席本轮独立联网核对，与主持人第 2 轮摘录一致。[12] 的弃用状态与过渡期开关本轮核验席未获联网授权、未独立复核，依据仍为主持人第 2 轮的原文摘录。
- 篇幅统计（附录 B 口径）：正文汉字 1860，计入英文词与数字后 1999，未超过 2000 字。

### v0.2（2026-10-07）

- 依据第 2 轮复审（终审口径，standard 深度，5 席）修订。第 2 轮五席均投 APPROVE，插件法定人数满足（Codex、agy、Claude 三家计入）；质疑席（Codex）与核验席（Opus）均作答，无超时或成本中止。**本轮无阻塞项**，以下均为少数意见的采纳情况。
- 采纳的修改：
  1. 篇幅（质疑席、核验席、两主持席）：原第五节“少数意见”移入附录 A，新增附录 B 写明计数口径。
  2. 决策流程图（核验席、顾问席）：在盘点后加“命中第三节不建或缓建情形 → 不建或缓建”出口；试点节点改为“达标则推广，不达标则重评缺口”。
  3. OTel 异常记录方式（核验席）：主持人核实 OTel exceptions-spans 约定[12]，该约定已标为弃用、改用日志约定[1]，并以环境变量 `OTEL_SEMCONV_EXCEPTION_SIGNAL_OPT_IN` 控制过渡期输出。原句“OTel 常把异常记录为 Span 事件”据此改写，并补引用；结论不变，反而加强“不能假设一份 OTel 数据直接复用”的提醒。附录 A 第 2 条同步更新。
  4. 边界表 OTel 列“延迟、拓扑、容量”由“有”改为“定义信号”（核验席）。
  5. 现有 APM 错误模块的核实项加“错误事件是否受 Trace 采样影响”（核验席，源自顾问席第 1 轮的定性观点；第 1 轮所给采样比例仍未核实，未写入）。
  6. 数据安全（质疑席）：出站验证改为分通道覆盖错误事件、附件和回放；新增“权限要实测”。质疑席称 New Relic 只读用户仍可改问题状态，主持人核对 [3] 原文：“Standard role restrictions … are only enforced in the error group comments feature”，只读用户可指派错误组并更新其状态（ignored、resolved、unresolved），属实，写入正文。
  7. Source Map 不随公网产物发布（顾问席，核验席附议）：并入数据安全一节。
  8. SaaS 错误风暴（顾问席）：选型表 SaaS 行补“客户端限频”和“配额消耗告警”。
- 复核与闭环：
  - [4] 由主持人复核：Sentry OTLP 接入为 open beta，原文 “Span events are not supported. All span events are dropped during ingestion.”，与正文一致。
  - [5] 由主持人复核：最低 4 核、16 GB 内存加 16 GB swap、20 GB 磁盘，推荐 32 GB，定位为 “a minimal setup that works out-of-the-box for simple use cases”，与正文一致。
  - [8] GlitchTip 依赖表述：质疑席本轮独立核对安装页，表述成立；核验席提出的疑问闭环（第 1 轮核验席原文为“依赖 PostgreSQL 和 Redis”，v0.1 已按 [8] 修正为 Redis/Valkey 可选）。
  - 顾问席称“正文约 1700 字”，未给计数方法，不采信；以附录 B 口径为准。
- 未采纳：研究综合主持席建议压缩表格注释，改为移出第五节处理篇幅，未删减选型表中的硬件与组件信息（两强席位均认为这些代价信息有价值）。
- 篇幅统计（附录 B 口径）：正文汉字 1828，计入英文词与数字后 1965，未超过 2000 字。
- 待第 3 轮复审：请核验席定向复核第 2、3、4、5 项及篇幅统计，请质疑席定向复核第 6 项；其余席位只复核修订差异。

### v0.1（2026-10-07）

- 依据第 1 轮研讨（standard 深度，5 席：Claude Sonnet 5 主持席 ×2、Codex 质疑席、agy 顾问席、Claude Opus 5.5 核验席）的五份独立意见执笔。
- 第 1 轮情况：五席均完整作答，无超时或成本中止；但插件把五席判为 blind seat（第 1 轮没有待评审的稿件），法定人数未满足，未进入互评与综合，因此没有插件生成的综合稿。各席表决仅供参考：战略分析主持席 REVISE（要求区分单团队与平台级决策，已在结论第 4 条处理），其余四席 APPROVE。本轮只作意见收集，不作为通过依据。
- 引用核实：主持人逐条联网核对后写入上述 11 项来源。核对中新增一处修正：Sentry OTLP 接入会丢弃 Span 事件，因此删去核验席“同一份 OTel 采集可同时喂给两边”的表述。
- 未写入正文的内容（无法核实）：顾问席引用的“CNCF 调研 75% 部署 Tracing、40% 缺陷来自客诉”、“DORA 结论”的具体引申、“0.5~1 名专职 SRE”、“研发 < 15 人”阈值、APM 采样率“1%~10%”，以及 Bugly、啄木鸟等案例描述；核验席提到的 Stripe《Developer Coefficient》数据和“10 万+ 组织”；Elastic APM 的错误工作流（所查官方文档只确认有错误分组字段，未确认指派与回归流程）；国内云厂商具体产品能力。
- Sentry 许可证沿革（2019 年由 BSD-3 改为 BSL，2023 年改为 FSL）见 Sentry 官方博客 https://blog.sentry.io/introducing-the-functional-source-license-freedom-without-free-riding ，正文只保留当前许可证结论。