数据度量工作指南（四）：指标字典模板，把定义变成可复算的协作接口

同一个“完成率”，在不同人手里经常有不同分母：有人以点击开始为分母，有人以请求发起为分母，有人排除了超时，有人把重试后的成功算作一次完整成功。没有指标字典，数据口径会在会议、SQL 和看板之间逐渐分叉。

指标字典的目标不是把定义写得很长，而是让读者在不认识作者、不打开原始代码的情况下，知道这个数如何计算、何时可比较、出了变化该看什么。本文提供一份模板和六类公开示例；可直接复制到 Markdown、文档或数据目录中。

一、每条指标都用同一张定义卡

名称： 一句话目的：它帮助做什么决策？ 层级：任务结果 / 体验护栏 / 过程诊断 / 数据质量 测量对象：请求、会话、去重用户、任务，或其他明确对象 事件与来源：使用哪些受控事件、日志或公开测量工具？ 公式：分子 / 分母；聚合方式；分位数或时间窗口 成功与失败定义：哪些状态计入，哪些状态单列？ 去重与归因：用什么 ID 关联；重复尝试怎样处理？ 排除项：测试、机器人、重复上报、无效样本等 切分维度：平台、版本、网络、入口等；以及不应采集的维度 数据时效与质量：可用延迟、覆盖率、已知盲区 配套指标：目标、护栏、诊断指标分别是什么？ 解释边界：这个指标不能说明什么？ 变更记录：口径、事件或计算规则何时改变，能否与历史比较？ 字段不必每次都写成段落；表格或 YAML 也可以。关键是同一团队的词典采用相同结构，尤其不能省略分母、排除项、数据来源和解释边界。

二、示例一：任务完成率

工作用法： 完成率下降时，先确认开始事件是否漏报；再看无结果率、等待和错误是否同步变化；最后按入口或版本定位。不要用某个接口成功率直接替代任务完成率。

三、示例二：转化与留存

转化、活跃、新增和留存是常见公开产品指标，但它们尤其容易因时间窗和分群不同而失去可比性。

示例：不要把“新增”与“留存”混成一个结论

某个入口带来了更多首次访问者，新增指标上升，但同 cohort 的后续有效使用没有改善。这可以说明入口扩展了触达，不足以说明它创造了长期价值。反过来，留存变化也要先检查 cohort 的来源构成是否变化。把新增、转化、留存放在同一任务或漏斗中观察，才更接近完整判断。

四、示例三：错误、可用性与资源质量

工作用法： 先分网络和非网络错误，再区分“请求失败”与“用户看见失败”。当错误总量上升时，同时看错误率和受影响用户占比；否则流量变化会误导判断。

五、示例四：延迟、卡顿与可感知等待

| 指标 | 公式或定义 | 常用配套 | 解释边界 | | --- | --- | --- | | P95 任务等待 | 任务从提交到用户看见明确结果的耗时 P95 | P50、超时率、任务完成率 | 不能仅用平均值替代；任务类型应可比。 | | 每用户每分钟可感知等待 | 前台可见等待总时长 / 去重用户使用分钟数 | 等待任务数、超时率 | 使用分钟数需排除后台与异常驻留。 | | 每用户每分钟卡顿 | 满足既定卡顿条件的前台卡顿次数 / 去重用户使用分钟数 | 长任务、INP、设备分群 | 卡顿阈值和采样方法必须固定并公开。 | | LCP / INP / CLS | Web Vitals 定义下的加载、交互、布局稳定性观测 | 任务完成率、错误、设备与网络维度 | 不等同于业务结果，定义以公开标准为准。 |

工作用法： 将等待的起止点定义为用户能感知的状态，而不是只计算服务端耗时。若 P95 变慢而 P50 稳定，优先检查长尾环境；若 P50、P95 都稳定但反馈变多，检查用户是否无法理解当前等待状态。

六、示例五：反馈与问题质量

反馈是重要的发现通道：公开资料中也常见“监控发现的问题有限，真实线上问题常由用户先报告”的情形。正确做法不是让反馈替代数据，而是将它与任务事件、错误分类和复现路径相互验证。

七、示例六：数据质量指标

指标字典最容易漏掉的，恰恰是用来验证指标本身的数字。

八、词典的维护规则

• 新增核心指标前，先写定义卡，再写查询或看板。

• 修改事件、公式、排除项或分母时，必须记录版本；必要时把历史趋势断开。

• 避免一个名称对应多种计算；宁可在名称中写明“按用户”“按请求”“首次”或“最终”。

• 每个核心指标都链接到至少一个护栏、一个诊断指标和一个数据质量检查。

• 定期删除无人使用、无法行动或已失去可信度的指标，避免词典变成废弃名词表。

指标字典最终服务的是协作：让分析者、开发者、产品人员和后续接手者在同一个数字上讨论同一件事。定义清楚，分歧才值得发生在目标和取舍上，而不是分母到底是什么。