84 lines
8.0 KiB
Markdown
84 lines
8.0 KiB
Markdown
# P6：进程指标、采集隔离与告警规则
|
||
|
||
日期：2026-09-18。范围为运行观测第一批，交付HTTP/WS、连接池、后台批次、进程指标和可离线验证的告警规则。P6仍在进行，任务/流程持久积压和阶段延迟没有被本批替代。
|
||
|
||
## 实现和边界
|
||
|
||
- [指标目录与注册器](../../internal/observability/metrics.go)只接受[代码中固定的名称、类型及标签集合](../../internal/observability/catalog.go)。没有通用动态注册接口；非法更新丢弃并计数，未知指标不创建族，同名不同类型不会触发空指针或混写。
|
||
- [HTTP包装器](../../internal/observability/http.go)保留原始状态、流式写入、Hijack及panic传播。成功WS升级在握手完成时计一次HTTP，连接存续单独计数；普通HTTP延迟不包含长连接生命期。103等临时响应不阻止最终响应。
|
||
- [运行采样](../../internal/observability/runtime.go)读取本进程池状态，不在采集路径执行SQL；批次开始/返回时间只观测原调用，不改变事务、重试或状态语义。计数器初始零值和最后成功时间支持“尚未成功”和“随后停滞”的判断。
|
||
- [进程入口](../../cmd/orbit/main.go)使用独立指标监听，默认关闭；启用后业务端口仍无`/metrics`，采集端口不提供业务API。服务启动、绑定失败和SIGTERM退出明确处理两种监听。
|
||
- [接口及运维手册](../api/observability.md)说明所有名称、单位、标签、采样间隔、超时、限流和剩余范围。[告警规则](../../deploy/monitoring/orbit.rules.yml)是可修改的起始阈值，未对接或发送实际外部通知。
|
||
|
||
模型仍为36个、直接持久化字段312个、迁移版本25；未改模型/迁移、没有外键或级联。没有新增Go模块依赖、SDK耦合或运行必需服务。官方promtool仅作为一次性离线验证器。
|
||
|
||
## 针对性证据
|
||
|
||
[指标竞态与约束回归](../../internal/observability/metrics_test.go)覆盖16个并发写入者及同时采集；每条直方图的桶/count/sum保持一致。3000个动态名称和3000个动态标签均被拒绝；每种HTTP方法/路由/状态组合都写入后，原序列仍继续累计。类型冲突、计数器倒退、非有限数字和错误文本泄露均有直接断言。
|
||
|
||
[真实TLS WebSocket回归](../../internal/observability/http_test.go)通过现有coder/websocket实际升级，保持连接未关闭时确认HTTP计数完成、HTTP在途为0、WS在途为1；关闭后WS归0且HTTP不重计。另有真实HTTP 103→201及Flush完整响应检查。
|
||
|
||
[进程专项](../../cmd/orbit/metrics_integration_test.go)使用一次性MySQL和编译为race模式的Orbit二进制：分别启用/关闭指标，验证readiness、业务请求、独立采集、DB池及自然运行的后台批次、请求数据不泄露，最后SIGTERM并确认监听全部关闭。分配优化后的定向入口退出0，5.696秒；这是测试耗时，不是延迟指标。
|
||
|
||
最终`make fmt test vet build`退出0。未配置外部测试环境时的普通go test会跳过MySQL/进程场景，不能用这些跳过项代替专项与标准集成执行。
|
||
|
||
## 独立格式与规则验证
|
||
|
||
全量有限HTTP组合的文本夹具为926666字节，使用本地已有官方promtool 3.5.0（linux/arm64，revision 8be3a9560fbdd18a94dedec4b747c35178177202）执行`check metrics`，退出0且无格式/命名告警。固定验证镜像摘要为`prom/prometheus@sha256:63805ebb8d2b3920190daf1cb14a60871b16fd38bed42b857a3182bc621f4996`，运行时关闭网络；此版本仅描述实际验证器，不是生产部署版本建议。
|
||
|
||
五条告警规则通过`check rules`；[规则测试](../../deploy/monitoring/orbit.rules.test.yml)通过`test rules`，验证目标失联、启动宽限、组件停滞、健康不报警、错误/等待/非法采样触发及恢复后的解除。
|
||
|
||
```sh
|
||
# 不要求平台在运行，可导出有限指标组合供独立校验。
|
||
ORBIT_TEST_METRICS_OUTPUT=/tmp/orbit-metrics.txt go test -count=1 -run '^TestExportExpositionFixture$' ./internal/observability
|
||
promtool check metrics < /tmp/orbit-metrics.txt
|
||
promtool check rules deploy/monitoring/orbit.rules.yml
|
||
promtool test rules deploy/monitoring/orbit.rules.test.yml
|
||
```
|
||
|
||
格式契约以[官方文本说明](https://prometheus.io/docs/instrumenting/exposition_formats/)为依据，框架自身不要求部署Prometheus。
|
||
|
||
## 全量回归与开销记录
|
||
|
||
标准`make integration`对应的`GO=… DOCKER=… sh scripts/test-mysql.sh`执行完毕，退出0。标准脚本显式为测试子进程分配独立随机指标端口，让真实SDK/WSS及进程恢复链路在指标启用时执行；进程专项另验证默认关闭场景。环境为Go 1.27.1、darwin/arm64、Docker MySQL 8.4.10。
|
||
|
||
| 范围 | 本次终态及耗时 |
|
||
| --- | --- |
|
||
| 存储、升级、事务竞争和COMMIT切点 | PASS，280.152秒 |
|
||
| 指标独立监听开/关与退出 | PASS，4.620秒 |
|
||
| 流程运行器真实节点恢复 | PASS，48.262秒 |
|
||
| SDK任务/Worker、调度、队列、批量、查询、订阅/消费、恢复和流程接口 | 各组PASS；23个SDK示例均运行成功 |
|
||
| 独立业务Inbox / Outbox模块及demo | PASS，36.005 / 34.409秒；demo成功 |
|
||
| Worker / 事件消费进程故障组 | PASS，127.765秒；包含A04未送达派发、自然租约到期、ACK丢确认和四种重试全停恢复 |
|
||
| 公共SDK流程暂停全停恢复 | PASS，13.789秒；两旧节点全部退出后由两新节点接续 |
|
||
|
||
无外键升级专项再次确认：v7的70条历史外键全部移除，323项原索引组成不变，原任务保留，启动检查拒绝外键漂移。当前schema版本25；业务Inbox和Outbox库也保持零外键。早期迁移文件保留原校验和，通过000008前向移除，禁止将历史DDL误解为当前运行结构。
|
||
|
||
全量执行结束后的微基准发现标签转义器重复分配，随后唯一生产代码调整是复用一个并发安全的`strings.Replacer`，转义规则不变。该调整后重新通过`make fmt test vet build`，并重新导出完整指标夹具校验格式；真实race二进制的监听/采集/退出专项复验通过，退出0、5.696秒。上表为该分配优化之前的全量结果，不将它写成优化后的重复全量执行。
|
||
|
||
可复现中间件微基准：
|
||
|
||
```sh
|
||
go test -run '^$' -bench '^BenchmarkHTTPMiddleware$' -benchmem -benchtime=1s -count=3 -cpu=1,8 ./internal/observability
|
||
```
|
||
|
||
Apple M2 Max、12核、32 GiB；全量集成停止后单独运行，退出0。空204处理器复用请求和响应对象，使用`RunParallel`，下表为三次测量范围。
|
||
|
||
| 指标启用 | GOMAXPROCS | ns/op | B/op | allocs/op |
|
||
| --- | --- | --- | --- | --- |
|
||
| 否 | 1 | 1.997–2.122 | 0 | 0 |
|
||
| 否 | 8 | 0.2581–0.2747 | 0 | 0 |
|
||
| 是 | 1 | 1090–1126 | 704 | 19 |
|
||
| 是 | 8 | 1404–1482 | 704 | 19 |
|
||
|
||
优化前启用时为41272 B/op、61 allocs/op；共享转义器消除了每次构建查找表的分配。并行ns/op是总工作量的摊销值，不是单请求延迟；启用后的锁竞争仍需结合真实负载检查。这只是中间件本机开销，不包含网络、MySQL、并发抓取或业务处理，不能换算成受理吞吐或百万企业容量。
|
||
|
||
文档检查通过：1204个本地链接、68段JSON示例，未发现失效链接、非法JSON或接入方项目标识；`git diff --check`通过。
|
||
|
||
## 后续原范围
|
||
|
||
1. 受理/授权/完成的持久吞吐、阶段延迟、重试/核查/恢复量、流程Inbox至推进延迟；区分提交成功、回执丢失、重报和事件重放，不能把HTTP成功数直接当作业务量。
|
||
2. 持久待处理、到期积压与发送队列。使用有上限/超时的后台采样及明确的新鲜度/失败状态，不能让每次抓取扫描全库；状态指标和多节点重复采集的聚合口径须先明确。
|
||
3. 慢消费者、重连风暴、业务负载下观测开销、真实采集/通知演练，以及数据库锁/磁盘/复制指标和跨故障域验证。
|
||
4. 凭据轮换、保留/归档、备份恢复、容量六类负载和P7版本发布继续按[持续计划](../08-development-plan.md)执行。
|