25 lines
3.7 KiB
Markdown
25 lines
3.7 KiB
Markdown
# P6：有界业务状态采样
|
||
|
||
日期：2026-09-18。本文记录第二批运行观测实现的边界和回归证据。它补充进程级批次指标，用于回答“本节点看到哪些固定状态、最早样本等待多久、采样是否完整”，不把有限样本当作全局业务统计，也不宣称生产容量或高可用已经验收。
|
||
|
||
## 已实现
|
||
|
||
- 迁移 `000026_operational_metrics` 为 `pulse_tasks`、`orbit_deliveries`、`weave_instances` 增加固定前缀索引；不增加模型字段，不引入外键或级联。
|
||
- [存储采样器](../../internal/storage/mysql/operational_metrics.go)只拼接代码内固定的表、索引、列名和状态集合。每个状态使用索引读取最多10001条，再将结果封顶到10000；至少一类封顶时 `orbit_business_snapshot_truncated=1`。
|
||
- 采样器先读取数据库UTC时间，再读取任务、结果交付和流程实例固定状态计数及最早未完成年龄。所有调用由独立900ms上下文限制；取消、数据库错误和超时都返回失败，不修改持久化数据。
|
||
- [业务指标记录器](../../internal/observability/business.go)将成功、错误、超时分别计数并记录耗时。失败样本不覆盖最后一次成功状态，同时保留最后成功时间，方便告警区分“旧值可见”和“本轮采集失败”。标签基数和状态取值均在目录中固定。
|
||
- [进程入口](../../cmd/orbit/main.go)仅在显式启用指标时每5秒后台采样；`GET /metrics`仍只渲染进程内存，不在抓取请求中执行SQL。采样错误进入脱敏结构化日志，不能改变任务、交付或流程事务。
|
||
|
||
## 回归证据
|
||
|
||
- [业务记录器单测](../../internal/observability/metrics_test.go)验证成功状态、年龄、截断、成功计数和失败后保留最后成功值；超时计数单独增加。
|
||
- [真实MySQL专项](../../internal/storage/mysql/operational_metrics_integration_test.go)验证迁移索引真实存在、数据库外键为0、任务状态被采样、固定状态集合存在、空交付/流程状态不误报，并验证已取消上下文被拒绝。
|
||
- `go test ./...`覆盖编译和普通单测；真实MySQL专项由标准`GO=... DOCKER=... sh scripts/test-mysql.sh`执行，未设置`ORBIT_TEST_MYSQL_DSN`时专项会跳过，不能把跳过当通过。最终标准脚本在Go 1.27.1、darwin/arm64、Docker MySQL 8.4.10环境退出码为0；其中存储/迁移/事务组256.539秒，指标开关进程组5.204秒，流程运行器全停恢复49.333秒，SDK与两个独立业务示例均通过。专项日志确认`TestIntegrationOperationalSnapshot`、`TestIntegrationNoForeignKeysUpgrade`、`TestIntegrationCredentialOperations`及`TestIntegrationCredentialCommitFaults`均PASS。
|
||
- 当前固定目录导出的指标夹具为929159字节，`promtool check metrics`成功；`promtool check rules deploy/monitoring/orbit.rules.yml`报告7条规则成功，`promtool test rules deploy/monitoring/orbit.rules.test.yml`成功。标准验证镜像仅用于离线检查，平台运行不依赖Prometheus。
|
||
|
||
## 解释和边界
|
||
|
||
每个Orbit节点都读取自己的有限样本；多节点指标不能直接相加获得全局精确积压。达到10000上限、采样超时、节点重启或节点间时间不同都会影响解释，必须结合截断标记、最后成功时间、数据库权威查询和审计判断。最早年龄使用任务/交付的`available_at`及流程的`updated_at`，它是告警线索，不是端到端受理、授权或完成延迟。
|
||
|
||
当前仍未完成持久化吞吐与阶段延迟、流程Inbox推进延迟、重试/核查/恢复量、发送队列全局聚合、生产采集通知演练、锁/磁盘/复制指标和多故障域容量验证。此批实现不能替代保留、备份恢复、HA、RPO/RTO及发布验收。
|