调度任务性能分析（通用版）
针对任意银企直联调度任务（明细查询、回单下载、支付收款等）的性能问题做归因分析。
核心方法：抽样发现事件词汇 → 全量扫描提取事件时间线 → 请求/响应逐次配对 → 分段耗时归因 → 三候选判定 → 对账 → HTML 报告。
开始前先加载 @references/gotchas.md。日志布局与统计陷阱都在其中，违反会得出错误结论。
输入
| 项 | 必需 | 缺省行为 |
|---|---|---|
日志根目录（含 logging-YYYY-MM-DD.N.log 分卷，目录套同名文件或平铺均可） |
是 | 无则停止，请用户确认路径与解压方式 |
任务名/业务标记（如 HisDetails 历史明细查询） |
否 | 跑 discover_events.py 自动发现，列候选让用户确认；用户不在时取 TOP1 并在报告写明口径 |
| 每次执行的起止时间与条数表现 | 否 | 从事件首末时间推断（报告标注"推断"）；无条数表现则对账步骤标注"无基准" |
| 工程源码路径（可选） | 否 | 用于 grep 日志标记语句、定位调度类/线程模型（THREADNUM）/判重逻辑，让优化建议落到具体类和行 |
步骤
- 环境检查：
python --version≥ 3.10 即可（脚本仅用标准库）。缺 Python 时停止并告知用户，不猜测结果。 - 事件词汇发现（tag 未知时必做）：
python scripts/discover_events.py --logdir <日志根目录>
输出候选业务标记 TOP20、默认事件关键词命中、content 前缀 TOP15、线程名分布。据此选定--tag；发现默认词汇表未覆盖的标记时，用--markers "TYPE=关键词;TYPE=关键词"扩展后扫描。
注意：候选标记常带实例 hash 与线程后缀（如HisDetails 历史明细查询 282e390c507d FC 50 TaskThread-0），--tag只取「任务英文名 中文名」前缀做子串匹配即可，同一业务的多条变体（不同 hash）会全部命中。 - 全量事件扫描（只读，几 GB 日志约数分钟）：
python scripts/scan_events.py --logdir <日志根目录> --tag <业务标记> --out events.json
事件类型由标记映射决定（默认覆盖：待发送报文/发送报文/返回报文/接收报文/已存在跳过/insert count/交易记录/下载成功/上传影像/入库成功/删除成功/空回单/加锁失败/触发回查/配置的线程数）。 - 分段归因（自动选择配对类型 REQ→RESP 或 SEND→RECV）：
python scripts/analyze_events.py --events events.json --start "<起>" --end "<止>"
输出：RTT 分布、空响应 vs 有数据响应 RTT 对比、INSERT 值求和、大间隙 TOP10、最慢 RTT TOP10、每 5 分钟事件时间线、墙钟利用率。 - 工程源码核查（提供了工程路径时）：
- grep 标记语句确认 tag 与事件词汇的真实来源类；
- 定位调度类与线程模型（线程数配置、配置的线程数日志），确认并行度瓶颈；
- 定位判重逻辑（已存在,跳过日志来源），确认对账口径。
未提供工程路径时照常分析，报告中注明"仅日志侧证据"。 - 三候选判定（每一项都必须给出证据后才能下结论）：
| 候选 | 判定为是的证据 |
|---|---|
| 单条入库/本地处理慢 | 本地处理（响应→下一事件）中位达数百 ms 以上，或下载/上传/入库等本地环节耗时占比显著 |
| 慢SQL | 日志出现慢查询记录，或结合执行计划另行分析 |
| 报文往返慢 | RTT 合计占墙钟 > 80%，且本地处理为毫秒级（同时排除前两者） |
- 根因链核查清单（逐项核对）：
- 并行度：线程分布是否只有TaskThread-0（单线程）；配置的线程数的值。
- 空查询/空页：空响应占比及其 RTT 与有数据响应的对比（空任务更慢 → 银行侧长尾）。
- 水位：DATEUPD 类事件被大量跳过且后续请求几乎全为第 1 页 → 查询日期不前进导致重复全量查询。
- 组合数验证：任务组合数（账户×日期等）× RTT ≈ 总耗时。
- RTT 方差：中位≈P90 且方差极小 → 疑似服务端固定延迟，不是网络抖动。 - 对账：INSERT 行的 count 值求和（不是行数；注意写同一张表的渠道不止一个，transType 标记可能相同，按 id/标记圈定口径并在报告写明）+ SKIP 条数 vs 用户条数表现；偏差 > 10% 时必须找出原因并在报告标注，不得强行下结论。
- 生成 HTML 分析报告，固定章节：一句话结论 → 关键数据表（墙钟/请求数/RTT 占比/空查询占比/有效产出）→ 三候选判定表 → 根因链 → 最慢样本与同维度对比 → 分级优化建议 → 数据质量说明（截断/乱码/对账偏差/时间口径）。
- 优化建议分级基线（按需裁剪，工程路径可核实后给到具体类和行）：
- P0：调度配置表中对应任务行的并发线程数调 3~8（账户级/任务级并发，不改代码）；对已确认无数据的（账户,日期）做水位/已查标记，砍掉重复空查询。
- P1：拿最慢样本与银行侧核查反常长尾与固定延迟；若支持区间查询，合并多日请求。
- P2：大报文日志刷屏治理（单卷可达百 MB 级）。
质量自查
- 每个数字都有日志证据来源（事件计数、配对数、值求和）。
- RTT 合计 + 本地环节 + 间隙 ≈ 墙钟（偏差 < 10%），对不上先查漏再下结论。
- 三候选每个都明确"排除/确认"，不给无证据归因。
- 报告区分"已实测数字"与"推断"。
停止条件
- 日志目录不存在或没有分卷 → 停止，请用户确认路径与解压方式。
- 扫描后配对事件数为 0 → tag 不匹配，回步骤 2 重新发现，不得空跑出报告。
- 对账偏差 > 10% 且找不到原因 → 报告标注"未对齐"，把已知与未知分开陈述。
