RUNBOOK — 预检并发度归因测量脚本 `measure_serial.py`¶

本手册面向要复测或复核 env-monitor-deploy 预检并发收益的人。该脚本不是常驻服务，按需运行。

1. 服务概览¶

项	内容
干什么用	把 `env-monitor-deploy` 预检的主机探测并发度钉成指定值，用于复现「只合并、不并发」（`1`）与「合并 + 并发」（`5`）两组耗时
形态	一次性 Python 脚本（约 100 行），进程内 monkeypatch，零侵入：不改配置、不改工程源码
依赖	目标工程的 venv（其 `.pth` 挂载 `~/py_public_modules` 共享库）；本机到 14 台外部主机的 root 免密 ssh
为什么不直接改配置	`ops.batch_max_workers` 对预检不生效（恒取默认 5），详见技能 `measured-baselines.md` 第八节
业务影响	无——全程只读（`precheck` 子命令本身只读），不改任何目标机状态
重要性	低（诊断工具）；结论已固化，日常无需运行

2. 接入与凭据¶

项	值
脚本路径	`/home/rain/Documents/k8s_ins/attribution-split-20260930/measure_serial.py`
运行目录	必须是 `/home/rain/Documents/k8s_ins/env-monitor-deploy`（脚本用 `runpy` 调其 `main.py`）
Python	必须用工程 venv：`env-monitor-deploy/.venv/bin/python`
凭据	无需输入；复用工程的 root 免密 ssh（`~/.ssh`）
网络	本机 192.168.31.249 → 14 台 `.16`–`.29`（`.16`–`.20` / `.21`–`.22` / `.23`–`.27` / `.28` / `.29`）

3. 日常速查表¶

D=/home/rain/Documents/k8s_ins/attribution-split-20260930
cd /home/rain/Documents/k8s_ins/env-monitor-deploy

# 串行（只合并、不并发）——预期约 46 s
.venv/bin/python "$D/measure_serial.py" 1

# 并发 5（与工程默认一致）——预期约 11 s
.venv/bin/python "$D/measure_serial.py" 5

# 只看结论行（末段 JSON）
.venv/bin/python "$D/measure_serial.py" 1 2>&1 | sed -n '/===MEASURE===/,$p'

# 验证串行确实生效：14 台首次出现时刻应逐个递增
.venv/bin/python "$D/measure_serial.py" 1 > "$D/tmp.log" 2>&1
grep -oE "^\[[0-9-]+ [0-9:.]+\] \[ssh_executor\] \[INFO\] \[HOST: 192\.168\.31\.[0-9]+\]" "$D/tmp.log" | awk '!seen[$NF]++' | head -16

4. 日常操作¶

运行：cd env-monitor-deploy && .venv/bin/python <脚本> <并发度>。参数为整数，必须 ≥ 1。

结果读取：脚本末尾以 ===MEASURE=== 分隔，其后是 JSON：

{"subcmd": "precheck", "workers": 1, "exit_code": 0, "elapsed_s": 46.2}

exit_code 即被测量的 precheck 退出码（0 = 校验通过）。elapsed_s 含进程启动与本地/集群侧固定开销。

重复测量：建议每组 3 次取中位数。基线数据的极差 < 1.4 s，单次即可判断量级。

注意：脚本内已带 --refresh-precheck，会强制绕过 300 s 预检结论缓存；手工改用 main.py 直跑时不要漏掉该参数，否则会命中缓存、得到约 0.3 s 的假数字。

5. 配置管理¶

本脚本无自身配置；
被测量对象 env-monitor-deploy 的并发度配置在 config/env-monitor.yaml 的 ops.batch_max_workers（默认 5）——但该键对预检不生效，故本脚本用进程内注入替代；
修改脚本内的注入逻辑没有必要；需要换并发度只改命令行参数。

6. 备份与恢复¶

脚本本身无状态、无数据，无需备份；
运行产物（日志、耗时）由使用者自行重定向到主题目录；本目录已留存 serial-fixed-run*.log（串行）、concurrent-run*.log（并发）、times.txt（耗时汇总）；
脚本与被测工程解耦：工程升级不影响脚本（除非 main.py 入口或 PreCheckBase._cfg 改名，届时需同步改注入点）。

7. 监控与告警¶

无常驻进程、无指标、无告警。判断运行是否正常看两处：退出码（应为 0）与主机数（日志中 14 台各出现一次）。

8. 故障处置¶

场景 A：`ModuleNotFoundError: precheck_module`¶

症状：启动即报找不到共享库模块。诊断：ls ~/py_public_modules/precheck_module.py；确认用的是工程 venv（.venv/bin/python，非系统 python3）。处置：改用 env-monitor-deploy/.venv/bin/python 运行；若 venv 缺 .pth，见工程 SOP 的共享库挂载说明。验证：重跑，输出 ===MEASURE=== JSON 且 exit_code 为 0。

场景 B：耗时与预期差一个量级¶

症状：workers=1 却只跑出约 11 s（或 workers=5 跑出约 46 s）。诊断：按速查表第 4 条抓 14 台首现时刻——若前 5 台在数毫秒内同时出现，说明并发度未被改为 1。处置：确认命令行参数就是 1；确认脚本未被改动（注入点在 PreCheckBase._cfg）；若 _cfg 改名，需同步修脚本。验证：重跑后 14 台首现时刻逐个递增、间隔 2–5 s。

场景 C：大部分主机报 `SSH 不可达`¶

症状：JSON 里 exit_code 非 0，日志大量「SSH 不可达」。诊断：timeout 6 ssh -n -o BatchMode=yes -o ConnectTimeout=3 root@192.168.31.16 hostname。处置：确认免密可用、目标机在线；目标机有在跑作业或负载高时耗时会被拉长，属正常，需在结论中标注。验证：连通性命令返回主机名，重跑预检 exit_code 回到 0。

9. 安全与权限¶

全程只读：不写目标机、不改配置、不改工程源码；注入只作用于本进程内存；
无需 sudo；以当前用户 rain 运行；
不涉及凭据读写（复用既有 root 免密 ssh）；
若把并发度设得过大（接近或超过 14），可能触发目标端 sshd MaxStartups 导致连接被拒——这是正确性问题，不是「变慢」，复测请勿超过 5。

10. 容量与性能¶

并发度	预期耗时（14 台）	说明
1（串行）	约 46 s	单台探测 ≈ 3.3 s × 14
5（默认）	约 11 s	分 3 批 ≈ 9.9 s + 本地/集群侧固定开销

两组均为 3 次实测中位数；极差 < 1.4 s。耗时随目标机负载、网络延迟变化，数字是参照不是承诺。

11. 附录¶

术语：合并 = 每台 9 次逐项探测合并为 1 次脚本取回；并发 = 主机间线程池并发
相关文档：MEASUREMENT.md（测量记录与结论）、SOP.md（回填变更档案）、技能 ops-execution-efficiency 的 references/measured-baselines.md 第一、八节
修订记录：2026-09-30 建立（随归因拆分测量交付）

来源：/home/rain/Documents/k8s_ins/attribution-split-20260930/RUNBOOK.md ｜最后更新：2026-09-30 13:58（由 build/sync.py 同步，请勿在站点侧修改）

RUNBOOK — 预检并发度归因测量脚本 measure_serial.py¶