feat: add bounded process metrics and private monitoring endpoint
This commit is contained in:
@@ -8,6 +8,7 @@
|
||||
| --- | --- | --- |
|
||||
| `GET /health/live` | 已实现 | [健康检查](health.md) |
|
||||
| `GET /health/ready` | 已实现，验证数据库、迁移记录及零外键要求 | [健康检查](health.md) |
|
||||
| 独立监听的 `GET /metrics` | 已实现基础运行指标，默认关闭 | [运行观测](observability.md) |
|
||||
| `/v1/tasks` 提交、查询、分页与待执行取消 | 已实现，P3扩展业务键与创建时间筛选 | [任务接口](tasks.md) / [查询契约](task-queries.md) |
|
||||
| `GET /v1/tasks/{task_id}/source` | 已实现普通、人工重试、计划固定版本及流程历史激活/轮次来源 | [来源查询](task-source.md) |
|
||||
| `POST /v1/tasks:batch` | P3 已实现逐项受理、独立幂等、部分结果与补交 | [批量任务](batch-tasks.md) |
|
||||
|
||||
@@ -42,4 +42,4 @@ curl -i http://127.0.0.1:8080/health/ready
|
||||
|
||||
对应 `Client.Liveness(ctx)` 和 `Client.Readiness(ctx)`，见 [SDK 接入](../sdk/README.md)。HTTP 503 返回 `*orbit.HTTPError`。
|
||||
|
||||
ready 只表示数据库与迁移基础可用；不检查 Worker、任务积压、流程执行或业务效果。P1 启动时先校验迁移，缺失或 dirty 会拒绝启动；运行后数据库不可用时 ready 返回 503。SDK 默认请求超时为 10 秒，调用方可通过 context 设置更短期限。
|
||||
ready 只表示数据库与迁移基础可用；不检查 Worker、任务积压、流程执行或业务效果。P1 启动时先校验迁移，缺失或 dirty 会拒绝启动；运行后数据库不可用时 ready 返回 503。SDK 默认请求超时为 10 秒，调用方可通过 context 设置更短期限。运行指标见[观测接口](observability.md)，指标端点是否启用由 `ORBIT_METRICS_ADDR` 控制。
|
||||
|
||||
91
docs/api/observability.md
Normal file
91
docs/api/observability.md
Normal file
@@ -0,0 +1,91 @@
|
||||
# 运行指标与告警接入
|
||||
|
||||
状态：P6第一批进程观测已实现，指标、采集入口和下方规则均有回归。任务/流程的持久积压和业务阶段延迟仍待补齐；完整生产观测尚未验收。
|
||||
|
||||
## 1. 启用独立采集端口
|
||||
|
||||
默认不启动指标监听，也不创建指标注册器。显式配置后，业务端口与采集端口分别监听：
|
||||
|
||||
```sh
|
||||
export ORBIT_HTTP_ADDR=127.0.0.1:8080
|
||||
export ORBIT_METRICS_ADDR=127.0.0.1:9090
|
||||
# 数据库凭据按现有秘密配置注入；先完成迁移。
|
||||
go run ./cmd/orbit
|
||||
```
|
||||
|
||||
```sh
|
||||
curl -fsS http://127.0.0.1:9090/metrics
|
||||
```
|
||||
|
||||
`ORBIT_METRICS_ADDR` 为空或未设置即关闭，`127.0.0.1:0` 可用于测试时分配空闲端口。非法地址、端口超界或绑定失败会拒绝启动；绑定失败不能静默降级为“看起来已经监控”。进程日志用 `metrics_address` 报告实际采集地址。业务端口 `/metrics` 返回404；指标端口不注册业务或健康接口。
|
||||
|
||||
指标监听不使用业务凭据，没有多租户查询接口；只面向平台运维人员。部署到远程采集网络时，显式选择内部地址并配置网络策略或带鉴权/TLS的内部代理，不将此端口发布到公网。SDK不封装该端点；业务读取、核查和审计仍使用原有鉴权API。
|
||||
|
||||
## 2. HTTP契约和数据范围
|
||||
|
||||
仅 `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。采集只访问进程内存，不查询业务表；DB池快照在启动时及之后每5秒读取 `database/sql.DBStats`，该调用不执行SQL。
|
||||
|
||||
所有指标名称、类型、标签名和取值在代码目录中固定。未知名称、错误类型、非法标签、非有限数值和计数器倒退会被丢弃，并增加 `orbit_observability_rejected_samples_total`。新增指标需要修改目录和回归，不允许业务方动态注册标签。HTTP标签为8种方法、12种路由分类和6种状态分类，两组HTTP族各最多576种标签组合。禁止将任务/流程/租户ID、业务键、URL、参数、原始错误或凭据写入指标。
|
||||
|
||||
格式化输出前只短暂复制注册器引用；不在全局记录锁下排序、格式化或写网络。直方图的桶、count、sum在同一局部锁下获取，保持单条直方图快照一致。指标在重启后重置，不能用于账务审计、幂等判断或恢复授权。
|
||||
|
||||
## 3. 指标目录
|
||||
|
||||
| 名称 | 类型 | 口径 |
|
||||
| --- | --- | --- |
|
||||
| `orbit_http_requests_total` | counter | HTTP响应完成次数；成功WS握手在Hijack完成时计入 |
|
||||
| `orbit_http_request_duration_seconds` | histogram | HTTP处理/升级握手耗时，不包含成功升级后的连接存续时间 |
|
||||
| `orbit_http_requests_in_flight` | gauge | 尚未返回或成功升级的HTTP处理器数量 |
|
||||
| `orbit_http_panics_total` | counter | 非正常返回的HTTP处理器次数；无响应时按5xx观测分类，但不声称客户端收到500；保留原panic传播及已发响应 |
|
||||
| `orbit_websocket_connections` | gauge | 成功升级且处理器尚未退出的WS连接，按worker_connect/event_connect区分 |
|
||||
| `orbit_websocket_connections_total` | counter | WS成功升级累计次数；并不表示协议hello、业务鉴权或任务执行成功 |
|
||||
| `orbit_runtime_batch_total` | counter | 后台批次返回次数，标签component及outcome |
|
||||
| `orbit_runtime_batch_duration_seconds` | histogram | 后台批次调用耗时，标签component |
|
||||
| `orbit_runtime_batch_last_success_timestamp_seconds` | gauge | 最后一次无错误批次返回的Unix时间；启动后未成功时为0 |
|
||||
| `orbit_db_connections_open` / `orbit_db_connections_in_use` / `orbit_db_connections_idle` | gauge | 本节点MySQL连接池当前连接数 |
|
||||
| `orbit_db_connections_max_open` | gauge | 池配置的最大连接数 |
|
||||
| `orbit_db_wait_count_total` / `orbit_db_wait_duration_seconds_total` | counter | 连接池累计等待次数/秒数，不是数据库锁等待 |
|
||||
| `orbit_process_start_time_seconds` / `orbit_process_uptime_seconds` | gauge | 本次指标注册器初始化Unix时间/单调时钟经过的秒数；初始化发生在数据库启动校验之后 |
|
||||
| `orbit_go_goroutines` | gauge | Go协程数，按5秒采样 |
|
||||
| `orbit_build_info` | gauge | 恒为1，go_version仅取当前编译运行时版本；不是Orbit发布版本 |
|
||||
| `orbit_observability_rejected_samples_total` | counter | 内部不合法指标更新次数，正常运行应为0 |
|
||||
|
||||
HTTP方法为GET/POST/PATCH/PUT/DELETE/HEAD/OPTIONS/OTHER；路由为health_live、health_ready、worker_connect、event_connect、tasks、queues、workflows、workflow_definitions、schedules、subscriptions、application_resources、other；状态为1xx–5xx及other。路径值不会进入标签；分类不表示路由存在或授权通过。独立采集请求不混入业务HTTP计数。
|
||||
|
||||
后台component为workflow、schedule、execution_recovery；outcome为success、error、cancelled。context.Canceled归cancelled，超时与其他错误归error，错误文本不导出。success只说明一批调用无错误返回，允许空批次；不能将它解释为持久任务成功量。已提交但确认不明的状态仍须按原身份核对。
|
||||
|
||||
直方图有限桶边界固定为0.005、0.01、0.025、0.05、0.1、0.25、0.5、1、2.5、5、10秒，另有+Inf桶和sum/count。不得将高于10秒的有限分位估计当作精确延迟，后续容量验证需结合样本及合适的桶配置。
|
||||
|
||||
## 4. 采集与告警例子
|
||||
|
||||
如果已有兼容采集器，可配置job名为orbit（规则按此名筛选）：
|
||||
|
||||
```yaml
|
||||
scrape_configs:
|
||||
- job_name: orbit
|
||||
scrape_interval: 15s
|
||||
scrape_timeout: 3s
|
||||
static_configs:
|
||||
- targets: ["127.0.0.1:9090"]
|
||||
```
|
||||
|
||||
示例地址仅适用于同机采集；远程采集需替换为受保护的内部目标。平台运行不依赖采集器、Prometheus或额外数据库。
|
||||
|
||||
[五条告警规则](../../deploy/monitoring/orbit.rules.yml)和[离线规则测试](../../deploy/monitoring/orbit.rules.test.yml)包含以下场景：
|
||||
|
||||
- 目标连续2分钟采集失败：检查指标监听、网络和进程，不直接判断业务任务停止。
|
||||
- 启动60秒后，某后台组件超过30秒没有成功批次并持续1分钟：结合readiness、批次错误和数据库状态调查。
|
||||
- 批次错误速率持续为正2分钟：查日志和原任务/流程审计，不把数据库故障改判成业务失败。
|
||||
- 池累计等待时间增长超过0.1秒/秒并持续5分钟：联查锁等待、慢SQL、CPU和存储，不自动提高连接数。
|
||||
- 内部非法指标更新持续出现：检查观测代码契约，不能忽略丢弃的样本。
|
||||
|
||||
这些阈值是可修改的运行基线，尚未通过生产负载调优；不构成SLO或可用性承诺。规则测试覆盖触发、启动宽限、健康不报警和错误停止后的解除，未发送实际通知或创建外部监控服务。
|
||||
|
||||
```sh
|
||||
promtool check rules deploy/monitoring/orbit.rules.yml
|
||||
promtool test rules deploy/monitoring/orbit.rules.test.yml
|
||||
```
|
||||
|
||||
HTTP失败率和延迟可按route/status_class统计；受理接口响应成功与已完成业务应分别判断。可靠结果量、排队/授权/完成延迟、流程Inbox积压、发送队列、磁盘/复制等仍须补充专门指标；具体当前证据见[验证报告](../reports/phase-6-observability.md)。
|
||||
Reference in New Issue
Block a user