交付环境衔接失败可以定义为一个可识别事件：交付流在环境交接点（如构建产物进入测试环境、测试通过进入预发、预发进入生产）未能按预期完成。围绕这个事件，需要统计失败率、恢复时长和影响范围三个量，并用同口径的前后对比判断改进是否真的生效。本文范围限于交付流执行中的环境衔接环节，给出公式、取数口径、计算步骤和一个可复算的算例；记录与关联动作可由工作项、流水线执行记录和事件工单承载。
要点总览（TL;DR）
- 把环境衔接失败定义为一个可识别事件，失败率=失败衔接次数÷有效衔接尝试次数，分母只计真正到达衔接点的尝试，计划内维护与人为取消排除。
- 恢复时长从失败被记录算到环境恢复可用或重试成功，建议同时报告平均值与中位数，单位统一为分钟，跨天事件换算为小时。
- 影响范围按受影响服务、环境、变更单、下游等待任务四个维度分别计数，不合并成总分，口径确定后版本化。
- 判断改进是否有效，用同口径等长窗口前后对比，并配合失败原因分布偏移与未改动环境作参照；样本过少或分母为零时只报区间与原始事件，不下结论。
- 单指标下降不等于改进生效，结论按“时间窗+范围+指标+方向”表述，并附口径版本与样本量。
评估目标：先明确要回答的三个问题
这套度量要回答三个问题：环境衔接是否稳定、失败后恢复是否够快、失败波及面是否可控。三个问题分别对应失败率、恢复时长和影响范围，它们共同支撑一个决策：是否继续投入当前改进动作，或者是否需要调整环境衔接方式本身（例如改变交接点的准入条件、增加环境预检、调整重试策略）。
把三个指标放在一起看，是因为它们各自只描述一个侧面。失败率低但恢复慢，说明问题少却一旦发生就拖住下游；恢复快但影响范围大，说明单次失败波及的服务和变更单多；影响范围小但失败率持续偏高，说明衔接环节本身不稳定。只有三个量同时观察，才能判断改进动作作用在哪个环节、是否值得继续。
需要提前说明一条边界：本文的指标不构成整体交付质量结论。失败率下降可能来自发布节奏放缓或变更规模缩小，恢复时长缩短可能来自值班人力临时加强。度量结论应表述为“在某一时间窗、某一统计范围内，环境衔接表现发生了何种变化”，并配合原因分布与复盘记录使用，避免把单指标当作团队绩效评价依据。
指标与范围：失败率、恢复时长、影响范围怎么定义
三个指标都需要固定分子、分母、时间窗和单位，否则前后数据无法比较。下表给出建议口径，团队可在此基础上调整，但一旦确定应版本化并保持稳定。
| 指标 | 公式 | 分子 | 分母 | 时间窗 | 单位 | 排除规则 |
|---|---|---|---|---|---|---|
| 环境衔接失败率 | 失败衔接次数 ÷ 有效衔接尝试次数 | 在衔接点未按预期完成、且被记录为失败事件的次数 | 真正发起并到达衔接点的尝试次数 | 按周或按迭代汇总，可叠加月度趋势 | 百分比 | 计划内维护窗口、人为取消的发布不计入分子分母 |
| 恢复时长 | 环境恢复可用时间 − 失败被记录时间 | — | — | 逐事件计算，再按时间窗汇总 | 分钟或小时 | 失败后放弃该环境、改走其他环境的，需在口径中单独标注 |
| 影响范围 | 按维度分别计数 | 受影响服务数、环境数、变更单数、下游等待任务数 | — | 与失败事件同一时间窗 | 个 | 同一失败重复重试不重复计数 |
分母口径是失败率最容易出错的地方。“有效衔接尝试次数”只计真正发起并到达衔接点的尝试：流水线在到达交接点之前就因编译错误终止的，属于构建阶段问题，不计入环境衔接分母；计划内维护期间被主动跳过的发布，也不计入。这样分母反映的是“环境交接这件事实际发生了多少次”，失败率才有解释力。
恢复时长的起点是失败被记录的时刻，终点是环境恢复可用或衔接重试成功的时刻。建议同时报告平均值和中位数：平均值受个别长尾事件影响大，中位数更能反映典型恢复速度，两者并列可以暴露恢复时长的分布是否偏斜。单位统一用分钟，跨天事件换算为小时并注明。
影响范围按四个维度分别计数：受影响的服务、受影响的环境、关联的变更单、因等待该环境而阻塞的下游任务。四个维度分开报，不合并成一个总分，因为它们的业务含义不同——服务数反映波及面，下游等待任务数反映对交付节奏的实际阻塞。
统计范围需要明确写清：纳入哪些环境层级（测试、预发、生产，或团队自定义的环境序列）、纳入哪些交付流（全部还是核心服务）、时间窗起止。范围一旦变化，前后数据即不可比，应作为口径版本变更处理。
数据口径与证据：从哪里取数、如何保证可比
取数来源通常有四类：流水线执行记录、环境变更记录、事件工单、部署日志。关键字段包括衔接点标识（哪个环境交接）、开始与结束时间、失败原因码、影响对象（服务、变更单、下游任务）。字段对齐的核心是让每条失败事件都能关联到唯一一次衔接尝试，从而保证分子分母来自同一份记录。
事件去重与关联规则需要提前约定。同一次失败如果被多次重试，应按一次失败事件计数，重试成功只影响恢复时长的终点，不改变失败次数；如果重试发生在不同环境，则按环境分别记录。跨系统关联时，以衔接尝试的唯一标识作为主键，把流水线记录、环境变更记录和事件工单挂到同一主键下。
缺失值和记录不全的处理方式要写进口径：缺少失败原因码的事件仍计入失败次数，但标注为“原因未分类”，在原因结构分析时单列；缺少恢复结束时间的事件不参与恢复时长计算，并单独报告缺失数量，避免用删除缺失值后的均值掩盖数据质量问题。
口径变更必须版本标记。每次调整分母定义、排除规则或影响范围维度，都记录版本号与生效时间，改进前后对比只在同一版本内进行；跨版本比较时明确说明差异，不把口径变化带来的数值变化当作改进效果。
在工具承载层面，ONES DevOps 解决方案可整合 DevOps 工具链并集中可视化 CI/CD 全过程，支持集成 Jenkins、GitLab CI 等第三方流水线工具，集成后自动同步流水线数据、更新执行状态和日志，并可将流水线与项目关联以识别阻塞。ONES Performance 可对系统内产生的研发数据进行多维度、自定义分析，并提供仪表盘模板与共享能力。这些能力可用于承载流水线执行记录与度量报表；衔接点标识、失败原因码等字段的粒度需以实际集成配置为准。
计算与评估步骤：从原始记录到改进判断
计算按时间窗汇总，步骤如下：
- 从流水线执行记录中筛出到达衔接点的尝试，剔除计划内维护与人为取消，得到分母。
- 在分母集合中标记失败事件，按唯一标识去重，得到分子，计算失败率。
- 对每条失败事件计算恢复时长，汇总平均值与中位数，并报告缺失数量。
- 按服务、环境、变更单、下游等待任务四个维度统计影响范围。
- 按失败原因码分组，得到原因分布，作为改进是否作用在预期环节的辅助证据。
改进验证采用同口径分段对比：取改进上线前后的两个等长时间窗（例如各四周），在同一口径版本下分别计算三个指标，并检查两段的衔接尝试次数是否足够。样本量过少时（例如单段失败事件少于若干条，具体阈值由团队按波动情况设定），只报告区间与原始事件清单，不下“改进有效”的结论。分母为零的时间窗，失败率记为“无数据”，不记为 0%。
判定规则建议写成三条同时满足才算改进有效：失败率在可比口径下下降且失败事件数不为零星个位数；恢复时长的中位数下降或持平而长尾事件减少；失败原因分布向预期环节偏移（例如目标环节的失败占比下降）。此外可设置对照：选择未改动环境或未改动交付流作为参照，若对照组同期指标基本平稳，改进结论更可信；若对照组同步变化，需排查发布节奏、季节性等共同因素。
例子：一次环境衔接失败率与恢复时长的完整算例
以下为演示情景，数据为虚构，仅用于展示计算过程。某团队统计一个四周时间窗内“测试环境进入预发环境”这一衔接点：有效衔接尝试 120 次，其中失败 9 次。
- 失败率 = 9 ÷ 120 = 7.5%。
- 9 次失败的恢复时长分别为 25、30、40、45、60、90、120、180、240 分钟。平均值 = 830 ÷ 9 ≈ 92.2 分钟；中位数 = 60 分钟。平均值明显高于中位数，说明存在少数长尾事件。
- 影响范围：涉及 4 个服务、1 个环境（预发）、6 张变更单、累计 14 个下游等待任务。
假设改进前一个等长窗口为：尝试 110 次、失败 15 次，失败率约 13.6%，恢复时长中位数 85 分钟，影响 7 个服务、11 张变更单。对比可见失败率从约 13.6% 降至 7.5%，中位数从 85 分钟降至 60 分钟，影响范围同步收窄。若两段口径版本一致、失败事件数量足以支撑比较，且失败原因分布显示目标环节占比下降，可初步判断改进在该衔接点产生了效果。
这个算例的局限也要说明：四周窗口可能受一次大版本发布影响，9 次失败的样本量偏小，平均值受 240 分钟的长尾事件拉动明显。结论应表述为“在该窗口、该衔接点上观察到改善”，并继续观察后续窗口是否稳定，不据此推断其他衔接点或整体交付质量同步改善。
解读与限制：哪些结论能下、哪些不能
指标波动与改进因果需要区分。失败率下降可能来自改进动作，也可能来自变更规模缩小、发布频率降低或环境预检拦截了部分尝试（使分母结构变化）。判断因果需要至少三个证据：同口径前后对比、失败原因分布向预期环节偏移、未改动环境作为参照保持平稳。三者不齐时，结论应停留在“观察到变化”。
样本量、季节性与发布节奏会显著影响结果。节假日前后发布密度变化、大版本集中上线、环境扩容等都会造成指标波动，单窗口对比容易误判。建议以滚动多窗口趋势为主，单窗口数据作为辅助。
影响范围计数口径变化会直接破坏可比性。新增一个统计维度或调整服务归并方式，都会让数值跳变，这类变化必须通过口径版本标记识别，不能当作改进效果。恢复时长中有一部分由值班与响应机制决定，例如夜间失败发现晚、响应慢，这部分改善属于运维响应范畴，与衔接方式改进应分开归因。
结论表述建议采用“时间窗 + 范围 + 指标 + 方向”的格式，例如“某季度内预发衔接点失败率由 X% 降至 Y%，恢复时长中位数由 A 分钟降至 B 分钟，影响服务数由 C 个减至 D 个”，并附上口径版本与样本量。配合失败原因分布和复盘记录作为辅助证据，可以让改进判断更可靠，也便于后续复核。
常见问题
流水线在到达环境交接点之前就失败了，算不算环境衔接失败？
不算。失败率的分母是“有效衔接尝试次数”，只计真正发起并到达衔接点的尝试。编译错误、单元测试未通过等发生在交接点之前的失败，属于构建或测试阶段问题，既不进分子也不进分母。这样分母反映的是环境交接实际发生了多少次，失败率才有解释力。如果团队希望观察端到端失败，可以另设一个指标，但不要与衔接失败率混用同一口径。
同一次失败被重试了多次，失败次数和恢复时长怎么记？
按一次失败事件计数，重试成功只影响恢复时长的终点，不改变失败次数。如果重试发生在不同环境，则按环境分别记录。跨系统关联时以衔接尝试的唯一标识作主键，把流水线记录、环境变更记录和事件工单挂到同一主键下，避免同一事件在多个来源被重复统计。
改进上线后失败率下降了，可以直接说改进有效吗？
建议先排除其他解释。失败率下降也可能来自变更规模缩小、发布频率降低，或环境预检拦截了部分尝试导致分母结构变化。判定改进有效通常需要三个证据同时具备：同口径等长窗口前后对比显示下降且失败事件数不为零星个位数；失败原因分布向预期环节偏移；未改动环境或交付流作为参照同期基本平稳。三者不齐时，结论停留在“观察到变化”，并继续观察滚动多窗口趋势。
某个时间窗内没有发生衔接尝试，失败率填 0% 还是空着？
记为“无数据”，不记为 0%。分母为零时失败率没有定义，填 0% 会让趋势图出现虚假的“表现完美”窗口，干扰后续判断。同理，单段失败事件过少时（阈值由团队按波动情况设定），只报告区间与原始事件清单，不给出“改进有效”的结论。缺失恢复结束时间的事件不参与恢复时长计算，并单独报告缺失数量。
恢复时长该看平均值还是中位数？
两个都报。平均值受个别长尾事件拉动明显，中位数更能反映典型恢复速度；两者并列可以暴露分布是否偏斜。例如九次失败中位数 60 分钟、平均值约 92 分钟，说明存在少数长时间未恢复的事件，这类事件往往对应值班响应或环境重建的薄弱环节，值得单独复盘。单位统一用分钟，跨天事件换算为小时并注明。
