perf(edge): EventLog 截断与全量回放停顿，等待持久化负载证据

[DeliciousBuding]

当前结论（2026-09-06 收口）

观测已由 #2308 落地；结构性重构保持 DEFERRED。 该 issue 跟踪的是 EventLog，不是 FileStore / SQLite 的公共锁。后两者的独立候选见 #2256。

已有本地 ARM64 / ext4 测量证明了停顿机制和规模上界，但没有证明实际持久化负载下的发生频率；不能将未配置 EventLog 的实例上“计数为零”当作无需优化的证据，也不指定已退役的实例作为采样目标。

已有测量（历史证据，不是本轮重跑）

truncateLocked：截断工作在 Append 的锁内完成

默认超过 50 MiB 后保留尾部 75%，重新读取并写回约 37.5 MiB。所有 publisher/replay 共用 EventLog 自己的 l.mu。

maxSize	keepBytes	触发截断的 Append
2 MiB	1.5 MiB	42 ms
4 MiB	3 MiB	77 ms
8 MiB	6 MiB	155 ms
50 MiB 默认	37.5 MiB	约 0.97 s，线性外推；独立对照中实测 952 / 966 ms 的截断停顿

每增加约 12.5 MiB 新事件触发一次截断。按当时约 660 bytes/event 的夹具估算，约每 1.9 万条一次；这不是现场事件速率。

ReadFrom：全量与常见 tail replay 不同

replay 形态（45 MiB 日志）	墙钟
tail 50 条	0.75 ms
tail 500 条	7.3 ms
cursor=0 全量，约 7 万条	1,095 ms

并发测量中 Append 的最大等待接近 replay 全程。较差形态出现在冷启动、首次全量连接或 cursor 早于存活窗口；不能将其描述为所有重连均冻结一秒。

下一次有效取证条件

1. 选择明确启用 AGENTHUB_EVENT_LOG_PATH 的隔离 staging 或已授权持久化实例；先证明配置与日志写入真实生效。
2. 收集日志尺寸、事件速率、replay 形态、gap/截断次数与耗时。指标为：
   • edge_event_log_truncations_total
   • edge_event_log_truncate_failures_total
   • edge_event_log_gaps_total
   • edge_event_log_truncate_duration_seconds_total
   • edge_event_log_truncate_last_duration_seconds
3. 满足任一既定触发条件再评估结构性方案：截断耗时占比 rate(edge_event_log_truncate_duration_seconds_total[1h]) > 0.005、最近一次截断 >0.5 s、gap 持续出现，或 truncate failures 增长。必须注明采样时窗和负载，不拿一次人工压满日志的测试冒充现场频率。

约束

• 本轮未开启任何现役实例的持久化、未压测现役服务，也未调整日志上限。
• 轮转、后台重写都会影响 cursor/gap、索引与外部文件变更语义，需要单独的契约/正确性验收；仅降低保留比例不能被宣称为消除停顿。
• 新观测不存在于旧版本时不能把缺失指标读成零。fix(edge-metrics): 三个 edge_event_log_* 指标从来没被生产 /v1/metrics 服务过——EdgeMetrics 唯一的生产构造点把 5 个 event-log hook 全填成看不见的位置参数 nil（活体实测：8956 字节 metrics 里 edge_event_log 命中 0），顺带补上 #2304 判定结构性修法所必需、此前完全不可见的「截断把总线冻住多久」 #2308 已补齐生产 metrics 接线；具体使用者仍须核对运行版本。

原始测量过程与理由保留在此前评论及 #2301 / #2308；本 issue 仅保留结构性决策与下一次有效取证入口。

[DeliciousBuding]

观测层已落地（#2308），并且落地时发现本 issue 的一个前提是错的

更正：「指标已存在」此前不成立

本 issue 正文写「指标已存在：edge_event_log_gaps_total、edge_event_log_truncate_failures_total」。这句话在 live 服务上是错的，主机实测：

buildEventBusAndMetrics（edge-server/internal/httpserver/server.go:225）是 EdgeMetrics 唯一的生产构造点，它调用 metrics.NewWithBusStats(busDepthFn, busDroppedFn)，而那个构造函数的实现是 newWithHooks(busDepthFn, busDroppedFn, nil, nil, nil) —— 三个 event-log hook 被硬编码成 nil，而 newWithHooks 对每个 hook 都是 if fn != nil { factory.New… } ⇒ nil 就是序列根本不注册。

于是计数器在跑、Bus.EventLogTruncations()/EventLogTruncateFailures()/EventLogGaps() 三个 accessor 存在、注释写着「Exposed for the edge_event_log_*_total Prometheus metric」、metrics.go 里有字段+注册块+Help 文案，而生产 /v1/metrics 一个都不服务。活体取证（dev 栈，临时给 edge 一个已知 token 抓 GET /v1/metrics，抓完立刻恢复 systemd 单元）：

http=200 bytes=8956
edge_event_bus_depth 0
edge_event_bus_dropped_total 0
$ grep -c edge_event_log  →  0

这正是本 issue 唯一未测那部分（UNMEASURED：需要生产/长稳环境的 event log 尺寸与 gap 计数）之所以测不到的原因：不是没人去看，是那三个序列从来没被服务过。

#2308 做了两件事

1. 把 5 个 event-log hook 全部接上，并把位置参数换成具名结构体 metrics.BusHooks{…7 字段…}（删掉 NewWithBusStats）。缺陷的成因正是「5 个同类型 func() float64 排成一排、少填 3 个在调用点上毫无痕迹」。

2. 补上本 issue 判定所需的幅度（原第 4 条「先加观测再决定」）：truncateLocked 全程持 l.mu，它的耗时就是总线冻结时长。新增

   • edge_event_log_truncate_duration_seconds_total（累计；配 truncations_total 可得平均冻结时长，其 rate 就是「墙钟里有多大比例被截断冻掉」）
   • edge_event_log_truncate_last_duration_seconds（最近一次；避免单次 ~1s 停顿被 rate() 窗口摊平）

   两个计数器每次截断各写一次，不在 Append 热路径上。

门禁：TestBuildEventBusAndMetricsServesEventLogSeries 对生产构造点抓 Handler()，断言 7 个序列都注册 + 每个样本值等于对应 Bus accessor 的返回值（防 hook 接错 accessor）+ 80 次 publish 越过 1024 字节上限后 truncations ≥ 1；TestMetricsWithoutHooksRegistersNoPullSeries 钉住「nil hook = 序列不注册，而不是服务一个常量 0」这条契约本身（这正是原缺陷的形状：常量 0 与没接线在图上不可区分）；TestEventLog_TruncateDurationIsRecorded 用 192KiB 保留窗口让恰好一次截断真的读写，从而在任何平台都能确定性断言计数器会动。暗卷 3 发（A 去掉全部 5 个 hook / B EventLogGaps 接到 EventLogTruncations() / C 不再计时）逐发翻红且只翻该翻的。

第一次推送在 Native Windows Go 判红，成因与处置也记在 #2308 里：last > 0 断言的是时钟分辨率与平台文件系统语义（1KiB 上限下几毫秒内截断几十次，走了早期错误分支的那次耗时本来就是 ~0），不是被测行为；修法是把「接线正确性」（平台无关）与「计数器真的会动」（需要平台前提，故以 truncateFailures == 0 为前提 + 192KiB 窗口）分开断言。

本 issue 剩下的部分：结构性修法，DEFERRED，触发条件现在是可执行的

两条停顿的机制、幅度、频率都已在正文实测（truncateLocked ≈0.97s/次 @ 50MiB 默认、每 ~1.9 万条事件一次；ReadFrom 全量 replay 1.10s，但尾部 50 条只 0.75ms）。四个候选修法（轮转 / 移出 Append 路径 / 降低 keepBytes 比例 / 先加观测）里，「先加观测」已完成，其余三个都要重定义 ReadFrom 的 cursor/gap 语义与 indexedSize 的外部变更检测，属结构性改动。

DEFERRED 的理由：现在缺的不是方案而是现场数据——「1.1s 冻结的实际频率取决于事件速率」这一条此前无法回答，因为计量它的序列不存在。

触发重新考虑的条件（任一满足即上调优先级）：

1. rate(edge_event_log_truncate_duration_seconds_total[1h]) 在任何一个长稳/生产 Edge 上 > 0.5%（= 每小时有 >18s 的总线被截断冻住），或 edge_event_log_truncate_last_duration_seconds > 0.5s；
2. rate(edge_event_log_gaps_total[…]) 非零且与重连频率同量级 ⇒ 说明客户端经常落在 gap 里、全量 replay 从最坏情况变成常见情况（正文已指出 50MiB 上限只保得住最近约 7.9 万条事件）；
3. 出现冷启动回放卡顿的现场报告；
4. SetMaxSize 被调大 ⇒ 全量 replay 与单次截断的成本都线性上升。

在此之前不动结构：按实测幅度，常见路径（尾部 replay）是亚毫秒级，而把读移出锁要重新处理索引重建与外部改文件检测，正确性风险与收益不成比例。

[DeliciousBuding]

round-74 判定：维持 DEFERRED，并补一条会致误判的活体事实

本轮没有对 EventLog 做任何结构性改动。按 #2308 落地的观测层 + 本 issue 定义的触发阈值判定，结论是「未触发」。但判定过程中发现一条必须先记录的事实，否则下一个人在 dev 栈上量到的 0 会被误读成「问题已经消失」：

dev 栈根本没有开启事件日志持久化

• edge-server/cmd/agenthub-edge/config.go:202：--event-log-path / AGENTHUB_EVENT_LOG_PATH 的默认值是空字符串，help 文本自己写明 empty = no persistence。
• 活体核验（dev edge PID 523358，已连续运行 8h）：
  • /proc/<pid>/environ 里 不存在 AGENTHUB_EVENT_LOG_PATH（该进程只有 AGENTHUB_DB_PASSWORD、AGENTHUB_OIDC_CLIENT_SECRET 两个 AGENTHUB_* 变量）；
  • /proc/<pid>/cmdline 只有 /root/agenthub-dev/bin/edge，没有 --event-log-path；
  • restart-edge.sh 只 source /home/.config/server-secrets/agenthub-dev.env，而该文件只含上述两个变量（已核 key 名，未取值）。

⇒ 在 dev 栈上 truncateLocked 结构上不可达（没有文件可轮转）。edge_event_log_truncations_total == 0 的含义不是「没有发生截断」，而是「这条代码路径没有被启用」。这两者在指标上长得一模一样。

因此本 issue 的触发条件需要改写评估地点

原写法是「看 edge /v1/metrics 的 edge_event_log_truncate_*」。这在一个没有配置事件日志路径的栈上永远读不到信号。修正为：

在一个 AGENTHUB_EVENT_LOG_PATH 非空的栈上（生产面 gz2 /opt/agenthub，或任何显式配置了该路径的 staging）看 edge /v1/metrics；阈值不变（rate(truncate_duration[1h]) > 0.5%、last > 0.5s、gaps ≠ 0、truncate_failures 增长）。

本轮判定

1. 不重构 —— 阈值未触发，且 dev 上不可能触发；
2. 观测层（fix(edge-metrics): 三个 edge_event_log_* 指标从来没被生产 /v1/metrics 服务过——EdgeMetrics 唯一的生产构造点把 5 个 event-log hook 全填成看不见的位置参数 nil（活体实测：8956 字节 metrics 里 edge_event_log 命中 0），顺带补上 #2304 判定结构性修法所必需、此前完全不可见的「截断把总线冻住多久」 #2308 的 5 条 edge_event_log_* 序列）保持已落地；
3. 若要在动手前拿到真实幅度，最小可行实验是给某个 staging edge 配上事件日志路径并跑真实流量，不是在 dev 上量；
4. 已在 round-74 记录中把「dev 上量到 0」显式标注为非证据。

round-74 的优先级是已实锤的用户可见缺陷：B-1（#2315）、B-6 卫生切片（#2316）、Web 失效空转族（#2317）。按 ADR-032/035 的纪律，未测量的候选不自动获得实现 lane。