raceprobe

command
v0.49.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 19, 2026 License: MIT Imports: 16 Imported by: 0

Documentation

Overview

classify.go —— race 门禁失败形态的**判定**(纯函数层,不碰进程)。

这层为什么必须与执行层分开

判据要能被**逐条钉死**:形态判定是纯函数(输入一段输出文本,输出一个结论), 于是「哪种输出算哪种形态」可以用构造出来的文本逐条钉住,不需要真的去跑一场 11 分钟的挂死。执行层只负责把真实输出**喂进来**。

混在一起时,判据只能等真挂死时才被验证——而真挂死在本机**不可稳定复现** (2026-11-18 实录:四轮全量重跑全绿,单包重跑 1.1~1.6 秒通过)。 判据跑不到 ⇒ 改坏了也没人知道 ⇒ 门禁是**看着在、其实没判**。

六种形态与各自的处置

none          没失败。
data-race     检出数据竞争 ⇒ 代码面,按竞态报告里的栈修共享状态。
test-hang     用例挂死(Go 运行时活着,打出了 goroutine 栈)⇒ 代码面。
startup-wedge 启动期楔死(Go 运行时压根没起来,**没有 goroutine 栈**)⇒ 环境面。
test-failure  普通用例失败(断言失败)⇒ 代码面,按失败用例名修。
unknown       认不出 ⇒ **明说认不出**,不猜。

判据是「栈在不在」而不是「超时了没有」

「超时」是**症状**,「有没有栈」是**机制指纹**:

· 用例挂死 ⇒ Go 运行时活到过 ⇒ 栈打得出来;
· 启动期楔死 ⇒ Go 运行时压根没起来 ⇒ 栈打不出来(连打栈的工具都不存在)。

能留下栈 ⇒ 运行时活到过 ⇒ 是用例问题。判「有没有超时」会把两种形态混成一种 (都超时),处置就只剩猜——2026-11-18 那次 11m0s 的失败就是这么被归错的。

exec.go —— race 门禁的**执行层**:起子进程、兜底超时、整树杀。

这层的两条硬约束(都是被实测打出来的,不是洁癖)

  1. **看门狗不得持有父进程的 stdout**:若继承了管道,写 `make check | tail` 的那端会一直等 EOF(孤儿进程握着管道 ⇒ 输出延迟半小时才刷出, 且管道把 make 的非零退出码吞成 tail 的 0 ⇒ 「红」看起来像「绿」)。 本工具的子进程输出走 **os/exec 自己建的管道**,本进程写完就退, 不存在「谁替我们握着父 stdout」。
  2. **看门狗不得留下孤儿**:只杀 go test 一个进程,会留下它的测试二进制 (每个测试二进制都是 go test 的子进程),而卡在启动期的那个**永不退出** (Go 运行时压根没启动 ⇒ 连它自己的超时都不触发)。 故超时处置是**杀整棵进程树**(unix 下靠独立进程组,见 proc_unix.go)。

main.go —— raceprobe 的 CLI 装配层。

参数:

-packages <模式>        要跑的包(默认 ./...)
-timeout <时长>        传给 go test -timeout 的用例超时(默认 10m)
-watchdog <时长>       本工具的兜底看门狗(默认 15m;必须 > timeout + 1m)
-out <目录>             取证落盘目录(默认 $TMPDIR/raceprobe)
-recheck <bool>         是否允许串行复核这条反事实实验(默认 true)
-recheck-timeout <时长> 复核自己的上限(默认 10m)

退出码:0 = 通过(含「环境面已复核」);1 = 未通过;2 = 用法/配置错。

race.go —— race 门禁的**编排层**:跑一轮、判形态、必要时做串行复核、落取证。

为什么编排层要单独一层

判据(classify.go)是纯函数,编排层只负责三件事:

  1. **跑**:把 go test 的输出同时送到终端、日志文件与内存缓冲;
  2. **判**:把缓冲喂给判据,拿一个形态结论;
  3. **复核**:结论是「启动期楔死」时,做一次**反事实实验**(同树、串行重跑 受害包),把「这是环境面」从一句断言变成一次实测。

串行复核是什么、为什么它有资格改判

假设:启动期楔死是**并行启动期的机器面争用**(macOS 动态链接器在内存压力下 抢不到锁),不是代码缺陷。反事实:同一棵树、同一台机器、**不并行启动** (-p 1)重跑受害包。

· 复核通过 ⇒ 代码在这台机器上能跑 ⇒ 原失败与「并行启动」这个变量相关,
  而不是与代码相关 ⇒ 判为环境面;
· 复核仍红 ⇒ 代码面(或另一类环境面)⇒ 按复核结果判红。

这条反事实与人工定责用的是**同一个方法**(换一个变量重跑一次对照), 差别只在于这里由机器执行、每次都执行。

判绿的条件有多严

只有**同时**满足下面四条才判绿:

  1. 首轮形态是 startup-wedge(Go 运行时压根没起来 ⇒ 没有 goroutine 栈);
  2. 首轮确实有受害包可复核(没有就无从反事实);
  3. 串行复核**全部通过**(退出码 0 且没被看门狗掐掉);
  4. 复核期间**没有**再出现新的失败形态。

任何一条不满足 ⇒ 判红。且判绿时**必留痕**:原始输出、复核输出、结论块 三份都落盘,并打印在终端上——不是「悄悄变绿」。

为什么「环境面已复核」可以判绿而不是判红

门禁变红的含义是「有东西不对,需要人处理」。若失败已被实测排除到代码面之外, 继续红就只剩两种后果:人每次都要重做一遍同样的复核,或者人学会无视这个红。 后者更贵——**一个会喊「狼来了」的门禁等于没有门禁**。

判绿不是掩盖:结论块、证据路径、原始输出全在,且写明「若反复出现,查机器面」。

report.go —— 结论的**渲染与落盘**(人读的那一面)。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL