92 lines
7.6 KiB
Markdown
92 lines
7.6 KiB
Markdown
# 运行指标与告警接入
|
||
|
||
状态：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)。
|