前端 WebSocket 长连接的可观测性：心跳超时、断线重连、消息丢失三类事件怎么统一建模与上报？

【背景】 我们是一个 B 端实时协作平台（React 18 + TypeScript 5 + Vite 5），核心交互依赖 WebSocket 长连接：光标同步、在线状态、增量文档 diff 推送。线上约 5000 并发连接，平均在线时长 45min，心跳间隔 15s（前端主动发 ping，后端回 pong）。

【现象与卡点】

1. 静默断连无感知：用户反馈"操作没反应"的工单里，约 30% 最后查出来是 WebSocket 静默断连（TCP 半开，浏览器不触发 onclose/onerror），前端 UI 卡在"连接中"，DevTools Network 面板看不出异常，只能靠用户反馈倒查。
2. 重连后消息风暴：断线期间服务端会缓存消息（上限 2000 条），重连成功后一次性 flush，主线程被 JSON.parse + 状态更新打满，INP 飙到 800ms+，甚至触发 Long Task 告警。
3. 心跳超时只有 warn 日志：SDK 里心跳超时只打了一条 console.warn，没有结构化上报，运维只能 grep 后端 access log 拼时间线，一次排查 2~3 小时。
4. 消息丢失无量化：前端 onmessage 里加了 seq 号校验，发现丢消息时只 console.error，没有上报，也没有 gap 指标，丢了多少、丢在哪一段全靠猜。

【已尝试的排查与结果】

• 用 navigator.onLine + visibilitychange 做粗粒度检测——能覆盖网络切换，但覆盖不了 TCP 半开（对端已死但本地 socket 还活着）。
• 心跳超时后做指数退避重连（1s → 2s → 4s → 8s → 16s，最多 5 次），重连成功但消息缺口没有量化指标，不知道断了几秒、丢了几条。
• 在 onmessage 里做 seq 连续校验，发现 gap 时只 console.error，没有上报到监控平台。
• 试过在 Service Worker 里拦截 WebSocket 帧——发现浏览器不支持（SW 只能拦截 fetch，不能拦截 WS 数据帧），此路不通。
• 后端侧有完整的连接生命周期日志（connect / disconnect / heartbeat_miss），但前端侧没有对应的结构化事件，两边对不上。

【期望得到的答案形态】 希望社区里做实时协作、IM、或 WebSocket 监控的朋友能给一些可落地的做法，具体想看到：

1. 一个 WebSocket 可观测事件模型：哪些事件（connect / disconnect / heartbeat_timeout / reconnect / message_gap / message_storm…）、每个事件带什么字段、状态机怎么画，能同时覆盖"连接生命周期""心跳健康度""消息完整性"三个维度；
2. 心跳超时检测的具体实现：setTimeout vs setInterval vs 基于 performance.now() 的漂移补偿，为什么选哪种？浏览器 tab 切后台时心跳怎么办（visibilitychange 联动）？
3. 重连后消息缺口的量化方式：seq gap 怎么算、怎么上报、阈值怎么定（gap > N 才告警还是每次都报）？消息风暴（>500 条 flush）怎么削峰（分片、requestAnimationFrame 批量、还是 Web Worker 解析）？
4. 上报 payload 的字段设计（脱敏后）：前端事件和后端 trace 怎么关联（traceparent 注入到 WS 首帧？还是自定义 header？）；
5. 如果大家在用 Sentry / ARMS / 自研，有没有 WebSocket 专项的监控面板，能晒一下指标定义吗？

我先把我们目前的 SDK 事件列表贴一下，方便大家对比：

ws_connect | ws_disconnect | ws_reconnect_attempt | ws_reconnect_success
ws_heartbeat_sent | ws_heartbeat_timeout | ws_message_received | ws_message_seq_gap

缺的是：ws_message_storm（flush 量 > 阈值）、ws_tab_hidden_resume（后台切回前台）、ws_message_parse_error。

欢迎直接贴代码片段或指标定义，越具体越好。