
研发效能看板上常有一个谁也说不清的数字:「平均交付周期 2.3 天」。追问下去,往往不是统计方法有问题,而是事件没对齐:commit 时间来自 Git,部署时间来自 CI/CD,两套系统各自记录、各自的主键和时钟,直接相减就得到一堆看着合理、实际无法复核的结果。更麻烦的是,这类数字一旦进了周报,后面所有对比都建立在它上面。
这篇不谈怎么选效能平台,只做一件很小的事:用仓库里已有的 git log 和部署记录,离线算出一张每一条都能追回到原始事件的变更前置时间(Lead Time for Changes)表,并附上让脏数据无法混入报表的自检脚本。全程只用 Python 标准库和 git 自带命令,不新增任何埋点。文中的 deploy_id、sha、时间均为演示用占位值,用来说明字段结构和计算过程,不代表任何生产环境的测量结果;读者请把它们替换成自己仓库与流水线的真实记录。
最容易起争议的是「一次变更从什么时候开始算」。我的口径是把部署批次当作变更单元,取该批次内最早那个提交的 committer 时间作起点:
概念 | 定义 | 取值来源 |
|---|---|---|
变更单元 | 一次成功进入生产环境的部署批次 | 部署记录,按 |
起点 | 该批次包含的提交中最早的 committer 时间 |
|
终点 | 该批次在生产环境标记成功的时间 | 部署记录 |
前置时间 |
| 计算列 |
观测指标 |
| 计算列 |
三个必须提前写进文档的判断,否则换了人算就是另一条曲线:
%cI**(committer date)而不是** %aI**(author date)**:rebase 和 cherry-pick 会保留 author date、更新 committer date。起点要表达的是「代码进入这条交付链路的时间」,不是作者在别的分支上第一次敲下它的时间。%aI 一并导出,但只用于复核。p50 被人为压低,看板会显得比实际快。p50 看常态、p85 看长尾、max 配合异常清单一起看,比一个孤零零的数字更有解释力。口径一旦定了就写进脚本头部的常量里并留版本号(
definition_version)。改口径不记版本,上季度和这季度的曲线就不可比,这是最常见的「看板突然变了」的真正原因。
脏数据类型 | 典型表现 | 不处理会怎样 | 处理方式 |
|---|---|---|---|
时间戳无时区 | 部署记录写 | 被隐式按本地时区解析,跨时区团队差 8 小时 | 强制 ISO-8601 带偏移;解析后检查 |
双时间戳混用 | 有人取 author date,有人取 committer date | 长期分支 / cherry-pick 的起点被提前到很早 | 统一 |
主键漂移 | squash merge / rebase 后,部署记录里的 sha 在仓库里找不到 | 该批次被静默丢弃,或匹配数为 0 后算出 0 小时 | 以部署批次为锚,用 |
重复与回滚 | 重跑同一批次、回滚再发布、多环境都记成 prod | 交付次数虚高、前置时间被压短 | 只取 |
第四类最隐蔽:「省下来的等待」很多时候只是被搬到了队列里。重试、补发、回滚会把一批交付拆成两条记录,看起来像两次快速交付。所以部署记录里必须显式留 kind 字段(normal / rerun / rollback),靠时间相邻去猜是猜不准的。
# 在目标仓库根目录执行;--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 限定统计窗口,但窗口必须按部署时间完整覆盖,别把跨天批次切在中间。
一行一个批次,字段固定。下面三行是演示用占位值:第二、三行 deploy_id 相同但 kind 不同,用来说明去重与回滚过滤为什么必须落在数据结构里。
{"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 持久化——否则每次重跑都可能把上一次已交付的提交又算进来。
#!/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。
python3 lead_time.py --repo . --commits /tmp/commits.tsv \
--deploys deploys.jsonl --out lead_times.csv输出 lead_times.csv 每行就是一个可追溯的变更单元:口径版本、批次 ID、起点、终点、前置时间、批次内提交数。任何人对报表里的数字有疑问,都能顺着 deploy_id 和 commit_range 回到原始事件重算一遍。
断言 | 位置 | 不过关时的动作 |
|---|---|---|
所有时间戳带时区偏移 |
| 抛 |
|
| 检查是否有平台混用本地时间与 UTC |
|
| 重跑记录应标 |
只统计 prod / success / normal |
| 预发、灰度、失败部署不进交付口径 |
区间内提交都能在台账找到 | 主循环 | 台账导出窗口是否没覆盖到该批次 |
| 主循环 | 大概率是 CI 与 Git 时钟不一致 |
口径版本一致 | 输出列 | 混用不同 |
异常数为 0 才出报表 | 退出码 | 逐条复核 |
现象 | 可能的解释 | 别急下的结论 |
|---|---|---|
| 多数批次顺畅,少数批次卡在评审或挂起 | 不要只报 |
| 统计窗口里混进了挂起后补发的批次 | 先确认 |
换了口径后曲线整体平移 |
| 分段展示,不要连成一条线 |
团队之间数值差异明显 | 分支策略、部署频率、批次粒度不同 | 不横比,只跟自己的历史比 |
两条边界要写清楚:第一,前置时间只反映交付链路的速度,不反映质量,也不反映价值;它缩短可能是批次变小了,不一定是效率提升。第二,这套离线计算依赖部署记录的可信度,如果平台本身不记 commit_range 或时间戳没有时区,脚本会诚实地报错,而不是给你一个凑合的数——这正是它比手工表格可靠的地方。
阶段 | 只做这一件事 | 能立刻挡住的问题 |
|---|---|---|
第 1 周 | 导出台账 + 部署 JSONL,跑通脚本,让异常清单为空 | 时区缺失、sha 对不上、重复部署 |
第 2 周 | 固定 | 口径被人悄悄改掉 |
第 3 周 | 按周看 | 只看均值导致的误判 |
误区 | 为什么错 |
|---|---|
逐 commit 相减 | 同一批交付被重复计数, |
用 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 删除。