【背景】 做了 8 年技术文档和指标体系搭建，最扎心的一次经历：去年接手一个 200+ 微服务的告警体系，翻指标字典，发现 40% 的指标"owner"是已离职同学，30% 的 SLO 目标还是 2021 年定的（当时 P99 < 80ms，现在业务量翻了 3 倍，P99 早就 120ms 了），还有一批告警规则注释写着"临时加，观察两周后删"——观察了 18 个月。
排障的时候，oncall 翻指标字典找不到对应指标的口径说明，只能问原作者（已经转岗），最后靠猜。一次 P1 故障，因为告警规则里的阈值是"拍脑袋"定的，误报率 70%，真正的故障淹没在噪音里，多花了 40 分钟才定位。
从现象倒推根因：指标体系的"文档债务"比代码债务更隐蔽——代码会编译报错，指标文档不会。它不崩，但它让你每次排障都在"猜"。
【常见分歧：三种做法，没有共识】
我见过三种团队，处理方式完全不同：
做法 A：没人管，靠 oncall 的"肌肉记忆" 指标字典是 2019 年写的一次性文档，之后没人碰。新 oncall 靠"问老人"和"翻代码里的注释"来理解指标口径。告警阈值是"上次出事之后改的"，没有系统性的回顾机制。 → 优点：零维护成本。缺点：人一走，知识就断；排障效率完全依赖个人经验。
做法 B：专人维护，但"维护"变成了"写新文档" 有专门的 SRE/文档工程师负责指标体系，但实际工作流是"新服务上线时写一份新文档"，旧文档只改不改删。指标字典从 200 条涨到 2000 条，没人知道哪些还活着。 → 优点：新服务有文档。缺点：债务只增不减，"找不到的指标"越来越多。
做法 C：定期清理，但"清理"变成了"大扫除" 每个季度做一次指标审计，把不活跃的指标标记为 deprecated。但实际操作是：审计人花两周翻完，改了一版，下个季度又回到原点。 → 优点：有"仪式感"。缺点：脉冲式维护不如持续维护，两次大扫除之间的 3 个月是真空期。
【我的倾向：把指标当"有生命周期的 API"来管】
我主张三件事，不一定对，想听大家拍砖：
-
每个指标必须有"owner + 存活条件"：不是"谁写的"，而是"什么条件下这个指标应该被删"。比如"该指标对应的服务下线时自动标记 deprecated"，而不是靠人记得。
-
告警规则必须带"为什么"：每条告警规则的注释里写清楚"这个阈值是怎么推出来的"（是 P99 历史分位 × 1.5？还是拍脑袋？），以及"误报后应该调什么"。没有"为什么"的告警规则，和没有文档的代码一样，是负债不是资产。
-
指标字典要"可搜索、可关联"：不是一个大 Markdown 文件，而是结构化的（哪怕只是一张表），每条指标关联到：对应服务、SLO 目标、告警规则 ID、最近一次修改时间和修改人。这样 oncall 排障时搜服务名就能拉出所有相关指标，不用"问人"。
核心逻辑：指标不是"写一次就完事"的文档，而是和代码一样有生命周期的活资产。创建、变更、废弃，每一步都应该有 owner 和触发条件。
【想听大家在什么场景下怎么选】
- 你们团队的指标字典是"活的"还是"死的"？多久没更新了？
- 告警阈值的"为什么"，你们有系统性的记录吗？还是靠"上次出事之后改的"？
- 有没有人做过"指标大扫除"？效果如何，坚持了几个季度？
- 如果让你用一句话定义"一个指标该被删掉的充分条件"，你会怎么定？
- 你们觉得指标文档的 owner 应该是"写指标的人"、"服务的 SRE"、还是"告警平台的运维"？
欢迎贴你们团队的具体做法（脱敏即可），尤其是"踩过坑之后改的"——那种经验比最佳实践值钱得多。