108 lines
3.3 KiB
Markdown
108 lines
3.3 KiB
Markdown
# 可观测性与告警 - ImageForge
|
||
|
||
目标：让“压缩效果、性能瓶颈、队列健康、计费正确性、滥用风险”都能被观测与告警，便于商用运营。下列请求标识和基础 Prometheus 指标已经实现；OpenTelemetry 和业务仪表板仍属于后续增强项。
|
||
|
||
---
|
||
|
||
## 1. 统一规范
|
||
|
||
### 1.1 请求标识
|
||
- API 会生成 `req_<uuid>`，也会接受由可信网关透传的安全 `X-Request-Id`。
|
||
- 请求 ID 会写入全部响应的 `X-Request-Id`、成功/失败请求日志和 JSON 错误体。
|
||
- 传入值仅允许 1-128 个 ASCII 字母、数字、点、下划线、冒号和连字符，避免日志注入。
|
||
|
||
### 1.2 日志格式
|
||
- 结构化日志（JSON）优先，便于 Loki/ELK 聚合。
|
||
- 禁止记录：明文密码、JWT、API Key、Webhook secret。
|
||
|
||
建议最小字段：
|
||
- `timestamp`、`level`、`service`（api/worker）、`request_id`
|
||
- `user_id`（可空）、`api_key_id`（可空）、`ip`、`user_agent`
|
||
- `route`、`method`、`status`、`latency_ms`
|
||
- `task_id`、`task_file_id`（压缩链路）
|
||
- `bytes_in`、`bytes_out`、`format_in/out`、`compression_level`
|
||
|
||
---
|
||
|
||
## 2. 指标（Prometheus，已实现）
|
||
|
||
API 在 `/metrics` 暴露 Prometheus 文本格式。生产环境只应从宿主机或监控私网抓取，不要通过公开域名开放该路径：
|
||
|
||
```bash
|
||
curl --fail http://127.0.0.1:18180/metrics
|
||
```
|
||
|
||
压缩、S3 回退和死信累计值存放在 Redis Hash `metrics:imageforge`，因此 API 与独立 Worker 的事件会汇总到同一组指标。HTTP 请求与错误指标是 API 进程级指标，重启后归零。
|
||
|
||
### 2.1 API 服务指标
|
||
请求类：
|
||
- `imageforge_http_requests_total{method,status_class}`
|
||
- `imageforge_http_request_duration_seconds_bucket`
|
||
|
||
错误与风控：
|
||
- `imageforge_errors_total{code}`，包含 `RATE_LIMITED`、`QUOTA_EXCEEDED` 等业务错误码
|
||
|
||
依赖与队列：
|
||
- `imageforge_dependency_up{dependency="database|redis"}`
|
||
- `imageforge_active_tasks`
|
||
- `imageforge_queue_messages{state="stream|pending|dead_letter"}`
|
||
|
||
### 2.2 Worker 指标
|
||
队列与吞吐：
|
||
- `imageforge_compressions_total{result}`
|
||
- `imageforge_compression_duration_seconds_sum/count`
|
||
|
||
压缩效果：
|
||
- `imageforge_compression_bytes_total{direction="input|output"}`
|
||
|
||
资源与异常：
|
||
- `imageforge_storage_fallbacks_total`
|
||
- `imageforge_dead_letters_total`
|
||
|
||
Prometheus 抓取示例：
|
||
|
||
```yaml
|
||
scrape_configs:
|
||
- job_name: imageforge
|
||
static_configs:
|
||
- targets: ['127.0.0.1:18180']
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 追踪（Tracing）
|
||
|
||
建议：API 与 Worker 使用 OpenTelemetry，打通跨服务链路：
|
||
- API：`create_task` span、`auth` span、`db` span、`redis` span
|
||
- Worker：`fetch_job` span、`download_input` span、`compress` span、`upload_output` span、`metering` span
|
||
|
||
价值：
|
||
- 发现耗时集中点（解码/编码/S3/DB）。
|
||
- 对账问题定位（用量事件写入失败/重复）。
|
||
|
||
---
|
||
|
||
## 4. 仪表板与告警（建议）
|
||
|
||
### 4.1 SLO（建议起点）
|
||
- API：P95 < 300ms（不含压缩直返）、错误率 < 0.5%
|
||
- Worker：队列积压 < N（按规模定义），失败率 < 1%
|
||
|
||
### 4.2 告警
|
||
可用性：
|
||
- `http 5xx` 激增
|
||
- `/health` 探活失败
|
||
|
||
队列健康：
|
||
- pending/inflight 持续上升
|
||
- 单任务耗时异常增长
|
||
|
||
计费正确性：
|
||
- webhook 处理失败
|
||
- 订阅状态异常（active->incomplete 回退等）
|
||
|
||
滥用风险：
|
||
- 单 key/单 IP 用量突增
|
||
- 格式探测失败率异常
|
||
|