ystp/docs/observability.md

可观测性与告警 - 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 文本格式。生产环境只应从宿主机或监控私网抓取，不要通过公开域名开放该路径：

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

imageforge_storage_fallbacks_total 是存储容量风险信号，而不仅是普通降级统计。建议对 increase(imageforge_storage_fallbacks_total[5m]) > 0 持续 5 分钟设置高优先级告警，并同步监控应用服务器 uploads 卷使用率，避免 S3 长时间不可用时本地回退写满磁盘。

Prometheus 抓取示例：

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 用量突增
• 格式探测失败率异常