首页
学习
活动
专区
圈层
工具
发布
社区首页 >专栏 >变更前置时间算不准,多半是事件没对齐:用 git log 和部署记录做一份可复核的 Lead Time 表

变更前置时间算不准,多半是事件没对齐:用 git log 和部署记录做一份可复核的 Lead Time 表

原创
作者头像
老王说技术
发布于 2026-11-19 11:27:53
发布于 2026-11-19 11:27:53
230
举报

研发效能看板上常有一个谁也说不清的数字:「平均交付周期 2.3 天」。追问下去,往往不是统计方法有问题,而是事件没对齐:commit 时间来自 Git,部署时间来自 CI/CD,两套系统各自记录、各自的主键和时钟,直接相减就得到一堆看着合理、实际无法复核的结果。更麻烦的是,这类数字一旦进了周报,后面所有对比都建立在它上面。

这篇不谈怎么选效能平台,只做一件很小的事:用仓库里已有的 git log 和部署记录,离线算出一张每一条都能追回到原始事件的变更前置时间(Lead Time for Changes)表,并附上让脏数据无法混入报表的自检脚本。全程只用 Python 标准库和 git 自带命令,不新增任何埋点。文中的 deploy_id、sha、时间均为演示用占位值,用来说明字段结构和计算过程,不代表任何生产环境的测量结果;读者请把它们替换成自己仓库与流水线的真实记录。

一、先把口径写死,再谈计算

最容易起争议的是「一次变更从什么时候开始算」。我的口径是把部署批次当作变更单元,取该批次内最早那个提交的 committer 时间作起点:

概念

定义

取值来源

变更单元

一次成功进入生产环境的部署批次

部署记录,按 deploy_id 去重

起点 first_commit_at

该批次包含的提交中最早的 committer 时间

git log 的 %cI

终点 deployed_at

该批次在生产环境标记成功的时间

部署记录

前置时间

(deployed_at - first_commit_at),单位小时

计算列

观测指标

p50 / p85 / max,不用均值

计算列

三个必须提前写进文档的判断,否则换了人算就是另一条曲线:

  • 用 %cI**(committer date)而不是** %aI**(author date)**:rebase 和 cherry-pick 会保留 author date、更新 committer date。起点要表达的是「代码进入这条交付链路的时间」,不是作者在别的分支上第一次敲下它的时间。%aI 一并导出,但只用于复核。
  • 按批次聚合,不按 commit 聚合:一个批次常含十几个提交,逐提交相减会把同一次交付重复计十几次,p50 被人为压低,看板会显得比实际快。
  • 不用均值,用分位数:少量跨假期挂起的批次能把均值抬高一大截。p50 看常态、p85 看长尾、max 配合异常清单一起看,比一个孤零零的数字更有解释力。

口径一旦定了就写进脚本头部的常量里并留版本号(definition_version)。改口径不记版本,上季度和这季度的曲线就不可比,这是最常见的「看板突然变了」的真正原因。

二、四类脏数据,任何一类都能让结果失真

脏数据类型

典型表现

不处理会怎样

处理方式

时间戳无时区

部署记录写 2026-11-19 09:00:00

被隐式按本地时区解析,跨时区团队差 8 小时

强制 ISO-8601 带偏移;解析后检查 tzinfo,缺失直接抛错

双时间戳混用

有人取 author date,有人取 committer date

长期分支 / cherry-pick 的起点被提前到很早

统一 %cI,两者差异超阈值的提交单独列出复核

主键漂移

squash merge / rebase 后,部署记录里的 sha 在仓库里找不到

该批次被静默丢弃,或匹配数为 0 后算出 0 小时

以部署批次为锚,用 git rev-list prev..head 反查区间,而不是逐 sha 精确匹配

重复与回滚

重跑同一批次、回滚再发布、多环境都记成 prod

交付次数虚高、前置时间被压短

只取 env=prod 且 status=success 且 kind=normal,按 deploy_id 去重

第四类最隐蔽:「省下来的等待」很多时候只是被搬到了队列里。重试、补发、回滚会把一批交付拆成两条记录,看起来像两次快速交付。所以部署记录里必须显式留 kind 字段(normal / rerun / rollback),靠时间相邻去猜是猜不准的。

三、可复现步骤

3.1 导出提交台账

代码语言:bash
复制
# 在目标仓库根目录执行;--no-merges 去掉合并节点,%cI 是带时区的 committer 时间
git log --no-merges --pretty=format:'%H%x09%cI%x09%aI%x09%s' \
  > /tmp/commits.tsv
head -3 /tmp/commits.tsv

%x09 是制表符,用它可以避开 commit message 里的空格干扰字段分隔。第三列 %aI 只作复核用,不参与计算。如果仓库很大,可以加 --since 限定统计窗口,但窗口必须按部署时间完整覆盖,别把跨天批次切在中间。

3.2 部署记录格式(JSONL)

一行一个批次,字段固定。下面三行是演示用占位值:第二、三行 deploy_id 相同但 kind 不同,用来说明去重与回滚过滤为什么必须落在数据结构里。

代码语言:json
复制
{"deploy_id": "REL-DEMO-001", "deployed_at": "2026-11-17T10:30:00+08:00", "env": "prod", "status": "success", "kind": "normal", "commit_range": "PREV_SUCCESS_SHA..HEAD_SHA_1"}
{"deploy_id": "REL-DEMO-002", "deployed_at": "2026-11-18T14:00:00+08:00", "env": "prod", "status": "success", "kind": "normal", "commit_range": "HEAD_SHA_1..HEAD_SHA_2"}
{"deploy_id": "REL-DEMO-002", "deployed_at": "2026-11-18T14:05:00+08:00", "env": "prod", "status": "success", "kind": "rerun", "commit_range": "HEAD_SHA_1..HEAD_SHA_2"}

关键是 commit_range:用区间而不是逐个 sha,squash / rebase 之后也能靠 git rev-list 还原出这一批交付究竟包含哪些提交。若部署平台只能给出单个 HEAD sha,退而求其次,用「上一个成功部署的 sha .. 本次 sha」自己拼区间,并在流水线里把 last_success_sha 持久化——否则每次重跑都可能把上一次已交付的提交又算进来。

3.3 计算脚本

代码语言:python
复制
#!/usr/bin/env python3
"""变更前置时间(Lead Time for Changes)离线计算。
数据源:git log 导出的 TSV + 部署记录 JSONL;仅依赖 Python 标准库。
口径:变更单元 = 一次 prod 成功部署批次;起点 = 批次内最早 committer 时间。
所有时间统一转 UTC 后相减;异常批次逐条列出,不静默丢弃。
"""
import argparse
import csv
import json
import subprocess
import sys
from datetime import datetime, timezone

DEF_VERSION = "lead-time-v1"


def parse_ts(raw):
    """只接受带时区偏移的时间戳;缺时区直接抛错,杜绝隐式本地时区。"""
    dt = datetime.fromisoformat(raw.strip().replace("Z", "+00:00"))
    if dt.tzinfo is None:
        raise ValueError("时间戳缺少时区偏移: %r" % raw)
    return dt.astimezone(timezone.utc)


def load_dedup(path):
    """按 deploy_id 去重;只保留 prod / success / normal 的批次。"""
    seen, rows = set(), []
    dropped = {"dup": 0, "env": 0, "failed": 0, "kind": 0}
    with open(path, encoding="utf-8") as fh:
        for line in fh:
            if not line.strip():
                continue
            rec = json.loads(line)
            did = rec["deploy_id"]
            if did in seen:
                dropped["dup"] += 1
                continue
            seen.add(did)
            if rec.get("env") != "prod":
                dropped["env"] += 1
                continue
            if rec.get("status") != "success":
                dropped["failed"] += 1
                continue
            if rec.get("kind", "normal") != "normal":
                dropped["kind"] += 1
                continue
            rows.append(rec)
    return rows, dropped


def range_to_shas(repo, commit_range):
    """用 rev-list 还原区间内提交,规避 squash/rebase 造成的 sha 漂移。"""
    out = subprocess.run(
        ["git", "-C", repo, "rev-list", "--no-merges", commit_range],
        check=True, capture_output=True, text=True,
    )
    return [s for s in out.stdout.split() if s]


def load_commit_times(path):
    by_sha = {}
    with open(path, encoding="utf-8") as fh:
        for row in csv.reader(fh, delimiter="\t"):
            if len(row) < 2:
                continue
            by_sha[row[0]] = parse_ts(row[1])
    return by_sha


def percentile(values, q):
    """线性插值分位数,避免引入 numpy 依赖。"""
    xs = sorted(values)
    if not xs:
        return None
    pos = (len(xs) - 1) * q
    lo = int(pos)
    hi = min(lo + 1, len(xs) - 1)
    return xs[lo] + (xs[hi] - xs[lo]) * (pos - lo)


def main():
    ap = argparse.ArgumentParser()
    ap.add_argument("--repo", default=".", help="git 仓库路径")
    ap.add_argument("--commits", required=True, help="git log 导出的 TSV")
    ap.add_argument("--deploys", required=True, help="部署记录 JSONL")
    ap.add_argument("--out", default="lead_times.csv")
    ap.add_argument("--version", default=DEF_VERSION)
    args = ap.parse_args()

    commit_times = load_commit_times(args.commits)
    deploys, dropped = load_dedup(args.deploys)
    results, anomalies = [], []

    for rec in deploys:
        try:
            shas = range_to_shas(args.repo, rec["commit_range"])
        except subprocess.CalledProcessError as exc:
            anomalies.append((rec["deploy_id"], "rev-list 失败", exc.stderr.strip()[:120]))
            continue
        times = [commit_times[s] for s in shas if s in commit_times]
        if not times:
            anomalies.append((rec["deploy_id"], "批次内无可用 commit", ""))
            continue
        if len(times) != len(shas):
            anomalies.append((rec["deploy_id"], "台账缺 %d 个 commit" % (len(shas) - len(times)), ""))
        start, end = min(times), parse_ts(rec["deployed_at"])
        hours = (end - start).total_seconds() / 3600
        if hours < 0:
            anomalies.append((rec["deploy_id"], "前置时间为负(时钟不一致)", "%.2fh" % hours))
            continue
        results.append({
            "definition_version": args.version,
            "deploy_id": rec["deploy_id"],
            "first_commit_at": start.isoformat(),
            "deployed_at": end.isoformat(),
            "lead_time_hours": round(hours, 2),
            "commit_count": len(times),
        })

    with open(args.out, "w", newline="", encoding="utf-8") as fh:
        w = csv.DictWriter(fh, fieldnames=[
            "definition_version", "deploy_id", "first_commit_at",
            "deployed_at", "lead_time_hours", "commit_count",
        ])
        w.writeheader()
        w.writerows(results)

    vals = [r["lead_time_hours"] for r in results]
    print("口径版本: %s" % args.version)
    print("有效批次: %d  去重/过滤丢弃: %s" % (len(vals), dropped))
    if vals:
        print("p50=%.2fh  p85=%.2fh  max=%.2fh" % (
            percentile(vals, 0.5), percentile(vals, 0.85), max(vals)))
    if anomalies:
        print("异常 %d 条(必须逐条复核,不得直接入报表):" % len(anomalies))
        for a in anomalies:
            print("  -", a)
        return 1
    return 0


if __name__ == "__main__":
    sys.exit(main())

脚本有两个刻意设计:异常不静默丢弃(台账缺 commit、rev-list 失败、时钟为负都会进 anomalies 并让进程返回非 0),以及过滤规则写死在函数里(load_dedup 只放行 prod/success/normal)。这样 CI 里可以直接拿退出码当门禁,不用人肉检查 CSV。

3.4 运行

代码语言:bash
复制
python3 lead_time.py --repo . --commits /tmp/commits.tsv \
  --deploys deploys.jsonl --out lead_times.csv

输出 lead_times.csv 每行就是一个可追溯的变更单元:口径版本、批次 ID、起点、终点、前置时间、批次内提交数。任何人对报表里的数字有疑问,都能顺着 deploy_id 和 commit_range 回到原始事件重算一遍。

四、自检:让脏数据挡在报表之前

断言

位置

不过关时的动作

所有时间戳带时区偏移

parse_ts

抛 ValueError,先修部署平台的导出格式

tzinfo 转 UTC 后再相减

parse_ts

检查是否有平台混用本地时间与 UTC

deploy_id 唯一

load_dedup

重跑记录应标 kind=rerun,而不是新开 ID

只统计 prod / success / normal

load_dedup

预发、灰度、失败部署不进交付口径

区间内提交都能在台账找到

主循环

台账导出窗口是否没覆盖到该批次

lead_time_hours >= 0

主循环

大概率是 CI 与 Git 时钟不一致

口径版本一致

输出列

混用不同 definition_version 的数据不可合并统计

异常数为 0 才出报表

退出码

逐条复核 anomalies,不要删掉异常凑好看的数

五、输出怎么读,以及这套口径管不了什么

现象

可能的解释

别急下的结论

p50 很小但 p85 很大

多数批次顺畅,少数批次卡在评审或挂起

不要只报 p50,把长尾批次单独拉清单

max 突然出现跨假期的值

统计窗口里混进了挂起后补发的批次

先确认 kind 与 deployed_at 是否真实

换了口径后曲线整体平移

definition_version 变了

分段展示,不要连成一条线

团队之间数值差异明显

分支策略、部署频率、批次粒度不同

不横比,只跟自己的历史比

两条边界要写清楚:第一,前置时间只反映交付链路的速度,不反映质量,也不反映价值;它缩短可能是批次变小了,不一定是效率提升。第二,这套离线计算依赖部署记录的可信度,如果平台本身不记 commit_range 或时间戳没有时区,脚本会诚实地报错,而不是给你一个凑合的数——这正是它比手工表格可靠的地方。

六、落地节奏与常见误区

阶段

只做这一件事

能立刻挡住的问题

第 1 周

导出台账 + 部署 JSONL,跑通脚本,让异常清单为空

时区缺失、sha 对不上、重复部署

第 2 周

固定 definition_version,把脚本接进 CI 定时任务

口径被人悄悄改掉

第 3 周

按周看 p50 / p85 与长尾批次清单

只看均值导致的误判

误区

为什么错

逐 commit 相减

同一批交付被重复计数,p50 被压低

用 author date 当起点

长期分支的评审等待被算成前置时间,数值虚高

直接删掉异常样本

问题被藏起来,下个月换个形式再出现

回滚重发算两次交付

交付次数虚高,曲线看起来「变快了」

跨团队横比排名

批次粒度与分支策略不同,数字不可比

上线前自测清单:① 故意写一条不带时区的时间戳,确认脚本抛错;② 造一条 kind=rerun,确认被过滤且计入 dropped;③ 造一条 deployed_at 早于起点的记录,确认进 anomalies 且退出码非 0;④ 用 git rev-list 手工核对一个批次的提交数;⑤ 确认 CSV 里 definition_version 只有一种取值;⑥ 确认 %cI 与 %aI 差异大的提交被单独列出复核;⑦ 把 p50 / p85 / max 与长尾清单一起看,不单报一个数;⑧ 把口径定义写进仓库 README,改口径先改版本号。

结语

做效能度量时,最花时间的从来不是算分位数,而是把「什么算一次交付」「从哪一刻开始算」「哪些记录不算」这三件事说清楚,并且让说不清楚的数据根本进不了报表。一旦事件对齐、脏数据被挡在门外,git log 加上一份朴素的部署记录就够用了,不需要先上一套平台。本文的脚本和字段结构都可以直接改造成自己仓库的版本;把演示占位值换成真实记录跑一遍,比讨论哪套看板更好用要快得多。

原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。

如有侵权,请联系 cloudcommunity@tencent.com 删除。

目录
  • 一、先把口径写死,再谈计算
  • 二、四类脏数据,任何一类都能让结果失真
  • 三、可复现步骤
    • 3.1 导出提交台账
    • 3.2 部署记录格式(JSONL)
    • 3.3 计算脚本
    • 3.4 运行
  • 四、自检:让脏数据挡在报表之前
  • 五、输出怎么读,以及这套口径管不了什么
  • 六、落地节奏与常见误区
  • 结语
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档