k2safe/orbit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: sample recent business events

Browse Source
This commit is contained in:
k2safe
2026-09-18 21:12:05 +08:00
parent 5284206731
commit 8ce9f4e1fa
14 changed files with 68 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
docs/api/observability.md
View File

@@ -1,6 +1,6 @@
# 运行指标与告警接入
状态：P6第一批进程观测及有界业务状态采样已实现，指标、采集入口和下方规则均有回归。采样只提供每节点有限快照，完整生产观测尚未验收。
状态：P6第一批进程观测、有界业务状态采样和固定事件窗口采样已实现，指标、采集入口和下方规则均有回归。采样只提供每节点有限快照，完整生产观测尚未验收。
## 1. 启用独立采集端口
@@ -25,7 +25,7 @@ curl -fsS http://127.0.0.1:9090/metrics
仅 `GET /metrics`（及标准HEAD）提供采集，查询参数返回400。正文使用[Prometheus文本格式0.0.4](https://prometheus.io/docs/instrumenting/exposition_formats/)，Content-Type为 `text/plain; version=0.0.4; charset=utf-8`，Cache-Control为no-store。输出是本节点的运行快照，没有跨节点或跨指标原子快照保证。
每节点同时最多2个采集请求，超出返回503及 `Retry-After: 1`，不排无限等待队列。独立HTTP服务器的读头/读/写/空闲超时分别为2/3/5/15秒，头部限制8 KiB。每次HTTP采集只访问进程内存，不查询业务表；DB池快照在启动时及之后每5秒读取 `database/sql.DBStats`，该调用不执行SQL。指标启用后同一个5秒后台采样器另外执行一次有界业务快照：查询固定状态、固定表和固定索引，单状态最多读取10000条，数据库调用使用900ms截止时间；失败只增加错误/超时计数并保留上次成功值，不改变业务事务。
每节点同时最多2个采集请求，超出返回503及 `Retry-After: 1`，不排无限等待队列。独立HTTP服务器的读头/读/写/空闲超时分别为2/3/5/15秒，头部限制8 KiB。每次HTTP采集只访问进程内存，不查询业务表；DB池快照在启动时及之后每5秒读取 `database/sql.DBStats`，该调用不执行SQL。指标启用后同一个5秒后台采样器另外执行一次有界业务快照：查询固定状态、固定表和固定索引，单状态或事件类别最多读取10000条；固定事件类别窗口为最近5分钟；数据库调用使用900ms截止时间；失败只增加错误/超时计数并保留上次成功值，不改变业务事务。
所有指标名称、类型、标签名和取值在代码目录中固定。未知名称、错误类型、非法标签、非有限数值和计数器倒退会被丢弃，并增加 `orbit_observability_rejected_samples_total`。新增指标需要修改目录和回归，不允许业务方动态注册标签。HTTP标签为8种方法、12种路由分类和6种状态分类，两组HTTP族各最多576种标签组合。禁止将任务/流程/租户ID、业务键、URL、参数、原始错误或凭据写入指标。
@@ -53,6 +53,7 @@ curl -fsS http://127.0.0.1:9090/metrics
| `orbit_result_delivery_oldest_age_seconds` | gauge | PENDING/LEASED交付样本中最早可处理时间的年龄 |
| `orbit_weave_workflows_state{state}` | gauge | Weave实例固定状态的有界计数 |
| `orbit_weave_workflow_oldest_age_seconds` | gauge | RUNNING/WAITING/CANCELLING/NEEDS_REVIEW实例样本中最早更新时间的年龄 |
| `orbit_business_events_recent{event}` | gauge | 最近5分钟内固定事件类别的有界数量，用于观察受理、完成、核查、恢复和流程推进趋势 |
| `orbit_business_snapshot_total{outcome}` | counter | 有界业务快照成功、错误或超时次数 |
| `orbit_business_snapshot_duration_seconds` | histogram | 有界业务快照耗时；包含数据库读取 |
| `orbit_business_snapshot_last_success_timestamp_seconds` | gauge | 最近一次完整成功快照的Unix时间；失败不会推进 |
@@ -100,4 +101,4 @@ promtool check rules deploy/monitoring/orbit.rules.yml
promtool test rules deploy/monitoring/orbit.rules.test.yml
```
HTTP失败率和延迟可按route/status_class统计；受理接口响应成功与已完成业务应分别判断。业务状态指标是本节点有限样本，不能相加作为全局精确数量；应结合 `orbit_business_snapshot_last_success_timestamp_seconds` 和 `orbit_business_snapshot_truncated` 判断新鲜度与完整性。可靠结果量、排队/授权/完成阶段延迟、流程Inbox推进延迟、发送队列、磁盘/复制等仍须补充专门指标；具体当前证据见[进程观测报告](../reports/phase-6-observability.md)和[有界业务采样报告](../reports/phase-6-business-observability.md)。
HTTP失败率和延迟可按route/status_class统计；受理接口响应成功与已完成业务应分别判断。业务状态和事件窗口指标是本节点有限样本，不能相加作为全局精确数量；未知事件类型不会进入标签，应结合 `orbit_business_snapshot_last_success_timestamp_seconds` 和 `orbit_business_snapshot_truncated` 判断新鲜度与完整性。可靠结果量、排队/授权/完成阶段延迟、流程Inbox推进延迟、发送队列、磁盘/复制等仍须补充专门指标；具体当前证据见[进程观测报告](../reports/phase-6-observability.md)和[有界业务采样报告](../reports/phase-6-business-observability.md)。