企业官网建设流程全解析

Lago 基础设施监控指南：基于 Prometheus 与 StatsD 的 Sidekiq 可观测性实践

【免费下载链接】lagoOpen Source Metering and Usage Based Billing API ⭐️ Consumption tracking, Subscription management, Pricing iterations, Payment orchestration & Revenue analytics项目地址: https://gitcode.com/GitHub_Trending/la/lago

导读

本文档面向 Lago（开源 Metering 与 Usage Based Billing 平台）的部署与运维人员，系统讲解其核心后台任务引擎 Sidekiq 的监控与可观测性方案：包括通过 Prometheus Exporter 暴露的全局、队列级、主机级指标，基于 Sidekiq Pro + DogStatsD 的逐任务执行指标，以及可直接落地的 Prometheus 告警规则与 Grafana 面板设计建议。读完本文，你将掌握 Lago 后台任务体系（计费、事件处理、Webhook、发票生成等队列）的完整监控接入方法，并能结合告警阈值进行容量规划与故障定位。

1. 监控架构总览：两条并行的指标采集链路

Lago 的 Sidekiq 监控由两套互补的指标采集链路组成，分别面向"队列整体健康状况"与"单个任务的执行质量"。其整体采集拓扑如下：

┌─────────────────────────────────────────────────────────────────────────┐ │ Metrics Collection │ ├─────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌──────────────┐ ┌─────────────────────┐ ┌────────────────┐ │ │ │ Sidekiq │ │ Sidekiq Web UI │ │ Prometheus │ │ │ │ Workers │─────▶│ + Prometheus │─────▶│ │ │ │ │ │ │ Exporter │ │ │ │ │ └──────────────┘ └─────────────────────┘ └────────────────┘ │ │ :3000/prometheus/metrics │ │ │ │ ┌──────────────┐ ┌─────────────────────┐ ┌────────────────┐ │ │ │ Sidekiq │ │ StatsD Exporter │ │ Prometheus │ │ │ │ Pro │─────▶│ (DogStatsD) │─────▶│ │ │ │ │ Middleware │ │ │ │ │ │ │ └──────────────┘ └─────────────────────┘ └────────────────┘ │ │ (optional) :12345/metrics │ │ │ └─────────────────────────────────────────────────────────────────────────┘

两条链路的核心组件与职责如下：

1. Sidekiq Web UI + Prometheus Exporter（lago-sidekiqs服务，默认启用）

   • 内置sidekiq/prometheus/exportergem；
   • 在/prometheus/metrics端点暴露指标；
   • 提供队列级（per-queue）与全局（global）的 Sidekiq 统计信息，同时支持 OSS 与 Pro 版本；
   • 其 Rack 入口配置见lago-sidekiqs/config.ru（该仓库api/为子模块，未随本仓库拉取；下同）。

2. Sidekiq Pro StatsD 指标（可选，需 Sidekiq Pro 许可证）

   • 通过LAGO_SIDEKIQ_STATSD_ENDPOINT环境变量开启；
   • 使用 Datadog StatsD 客户端，以lago_api作为应用命名空间；
   • 提供逐任务（per-job）的执行指标：执行时长、成功/失败计数等；
   • 配置入口见lago-api/config/initializers/sidekiq.rb。

适用前提说明：链路 1 是基础监控，开源版即可使用；链路 2 依赖 Sidekiq Pro 许可证。若你运行的是社区版 Sidekiq，链路 2 相关的指标与告警规则将不可用。

2. 采集链路一：Sidekiq Web UI 与 Prometheus Exporter

lago-sidekiqs是一个独立的 Rack 应用，同时承载 Sidekiq Web UI 与 Prometheus 指标端点。其config.ru完整配置如下：

# lago-sidekiqs/config.ru require './app' require 'sidekiq' require 'sidekiq/web' require 'sidekiq/prometheus/exporter' require 'sidekiq/throttled' require 'sidekiq/throttled/web' Sidekiq.configure_client do |config| config.redis = { url: ENV['REDIS_URL'] } end Sidekiq::Web.use(Rack::Session::Cookie, secret: ENV['SESSION_SECRET']) run Rack::URLMap.new('/' => Sidekiq::Web, '/prometheus/metrics' => Sidekiq::Prometheus::Exporter)

几个关键点：

• Redis 连接：Sidekiq.configure_client使用REDIS_URL连接 Sidekiq 队列存储所在的 Redis。这与 docs/architecture.md 中描述的"Primary Redis（Sidekiq Queue Storage）"一致——该 Redis 实例专门存放 Sidekiq 任务队列与任务数据。
• 会话安全：Web UI 使用SESSION_SECRET签名 Cookie 会话，生产环境务必为其配置强随机值。
• 路由映射：Rack::URLMap将根路径/映射到 Sidekiq Web UI（可人工查看队列、重试、死信队列并手动触发重试），将/prometheus/metrics映射到 Prometheus Exporter（供 Prometheus 定时抓取）。URLMap 语法为'路径' => Rack 应用，此处'/' => Sidekiq::Web, '/prometheus/metrics' => Sidekiq::Prometheus::Exporter即把两个端点挂载到同一服务。

配置完成后，在 Prometheus 的scrape_configs中把该服务（默认端口3000）的/prometheus/metrics加入抓取目标即可开始采集。

3. 采集链路二：Sidekiq Pro StatsD 逐任务指标

当使用 Sidekiq Pro 时，可开启第二层指标：通过server_middleware挂载 Datadog StatsD 中间件，将每个任务的执行结果（时长、成功、失败、错误类型）以 DogStatsD 协议发送给 StatsD Exporter，再转换成 Prometheus 格式。

3.1 配置代码与启用逻辑

lago-api/config/initializers/sidekiq.rb中的核心逻辑如下：

# lago-api/config/initializers/sidekiq.rb def configure_sidekiq_pro_metrics(config) statsd_endpoint = ENV.fetch("LAGO_SIDEKIQ_STATSD_ENDPOINT", nil) if statsd_endpoint.nil? Rails.logger.warn "LAGO_SIDEKIQ_STATSD_ENDPOINT not set, Sidekiq Pro metrics will not be reported" return end statsd_host, statsd_port = statsd_endpoint.split(":") if statsd_host.empty? || statsd_port.nil? || statsd_port.empty? Rails.logger.error "LAGO_SIDEKIQ_STATSD_ENDPOINT invalid format, expected host:port" return end require "datadog/statsd" config.dogstatsd = -> { Datadog::Statsd.new(statsd_host, statsd_port.to_i, tags: ["env:#{config[:environment]}", "service:sidekiq"], namespace: Rails.application.name) } config.server_middleware do |chain| require "sidekiq/middleware/server/statsd" chain.add Sidekiq::Middleware::Server::Statsd end end

该代码揭示的启用细节：

• 开关变量：LAGO_SIDEKIQ_STATSD_ENDPOINT未设置时仅告警并跳过，不影响其余功能（优雅降级）；
• 格式校验：必须形如host:port，格式非法时记录错误并返回；
• 标签体系：每个指标自动附带env（如production）与service=sidekiq标签；
• 命名空间：namespace: Rails.application.name决定了后面 3.3 节指标统一使用lago_api_前缀；
• 中间件注入：通过server_middleware链挂载Sidekiq::Middleware::Server::Statsd，从而在每个任务执行前后埋点。

3.2 环境变量配置

LAGO_SIDEKIQ_STATSD_ENDPOINT=statsd-exporter:9125

设置该变量后，指标会以 DogStatsD 协议发送到statsd-exporter的9125端口（StatsD Exporter 的默认端口即 9125），由后者转换成 Prometheus 格式供抓取。

所有指标携带的标签包括：

4. 基础 Prometheus 指标（开源/Pro 均可用）

以下指标由lago-sidekiqs服务的/prometheus/metrics提供，Sidekiq OSS 与 Pro 均可用。

4.1 全局指标（Global Metrics）

4.2 单主机指标（Per-Host Metrics）

4.3 单队列指标（Per-Queue Metrics）

运维提示：sidekiq_queue_latency_seconds是判断任务积压最直接的风向标；它与 docs/architecture.md 中"扩缩容指南"明确挂钩——当队列延迟上升、sidekiq_queue_enqueued_jobs持续增长时，即应扩容对应 worker。

4.4 队列清单：理解指标name标签的业务含义

Lago 的队列按业务类型划分，指标中的name标签对应下表：

结合仓库 docker-compose.yml 可以看到，api-worker（默认 worker）之外，Lago 还提供了api-events-worker、api-alerts-worker、api-pdfs-worker、api-billing-worker、api-clock-worker、api-webhook-worker、api-analytics-worker、api-ai-agent-worker等可按需取消注释启用的专用 worker 服务定义，分别对应events、alerts_high_priority/alerts、pdfs、billing、clock_worker、webhook_worker、analytics、ai_agent等专属队列。启用专用 worker 后，任务会通过queue_as路由（依据SIDEKIQ_*环境变量）进入专属队列，实现负载隔离与独立监控。

5. Sidekiq Pro 逐任务指标（StatsD）

当 Sidekiq Pro 配合LAGO_SIDEKIQ_STATSD_ENDPOINT使用时，可获得逐任务的执行质量指标。这些指标以 DogStatsD 协议发送，需借助 StatsD Exporter 转换为 Prometheus 格式。所有指标使用lago_api_前缀（即应用命名空间Rails.application.name）。

5.1 指标清单

5.2 常用 PromQL 查询示例

按 worker 统计任务失败率：

rate(lago_api_jobs_failure[5m]) / rate(lago_api_jobs_count[5m])

billing 队列任务的 P99 执行时长：

lago_api_jobs_perform{queue="billing", quantile="0.99"}

Top 10 最慢任务（按中位数执行时长）：

topk(10, lago_api_jobs_perform{quantile="0.5"})

按队列统计每秒任务数（吞吐）：

sum by (queue) (rate(lago_api_jobs_count[5m]))

解读要点：lago_api_jobs_perform是 Summary 类型指标，按quantile标签区分分位数；topk(10, ...)适用于快速定位"哪些任务类最拖慢系统"；失败率计算需同时除以任务总数，避免低基数下的假性高失败率。

6. 推荐的 Prometheus 告警规则

6.1 Critical 级告警

# Queue latency too high (jobs waiting too long) - alert: SidekiqQueueLatencyHigh expr: sidekiq_queue_latency_seconds > 300 for: 5m labels: severity: critical annotations: summary: "Sidekiq queue {{ $labels.name }} has high latency" description: "Queue {{ $labels.name }} has jobs waiting for {{ $value | humanizeDuration }}" # Dead jobs accumulating - alert: SidekiqDeadJobsIncreasing expr: increase(sidekiq_dead_jobs[1h]) > 100 labels: severity: critical annotations: summary: "Sidekiq dead jobs increasing rapidly" description: "{{ $value }} jobs moved to dead queue in the last hour" # No workers available - alert: SidekiqNoWorkers expr: sidekiq_workers == 0 for: 2m labels: severity: critical annotations: summary: "No Sidekiq workers available" description: "All Sidekiq workers are down"

6.2 Warning 级告警

# Queue backlog building up - alert: SidekiqQueueBacklog expr: sidekiq_queue_enqueued_jobs > 1000 for: 10m labels: severity: warning annotations: summary: "Sidekiq queue {{ $labels.name }} has backlog" description: "Queue {{ $labels.name }} has {{ $value }} jobs waiting" # High failure rate - alert: SidekiqHighFailureRate expr: | rate(lago_api_jobs_failure[5m]) / rate(lago_api_jobs_count[5m]) > 0.05 for: 5m labels: severity: warning annotations: summary: "High job failure rate for {{ $labels.worker }}" description: "{{ $labels.worker }} has {{ $value | humanizePercentage }} failure rate" # Worker process in quiet mode (shutting down) - alert: SidekiqWorkerQuiet expr: sidekiq_host_processes{quiet="true"} > 0 for: 10m labels: severity: warning annotations: summary: "Sidekiq worker {{ $labels.host }} in quiet mode" description: "Worker has been shutting down for over 10 minutes" # Slow job execution - alert: SidekiqSlowJobs expr: lago_api_jobs_perform{quantile="0.99"} > 30 for: 5m labels: severity: warning annotations: summary: "Slow job execution for {{ $labels.worker }}" description: "P99 execution time is {{ $value }}s"

6.3 Info 级告警

# Retry queue has jobs - alert: SidekiqRetryQueueNotEmpty expr: sidekiq_retry_jobs > 50 for: 15m labels: severity: info annotations: summary: "Sidekiq retry queue has pending jobs" description: "{{ $value }} jobs waiting to be retried"

6.4 阈值设定建议

结合 docs/architecture.md 中的任务机制可以更好地理解这些阈值的含义：

• Lago 默认不重试任务（max_retries为 0，sidekiq_options retry: 0），因此sidekiq_dead_jobs的快速增长通常意味着出现了系统性失败（如 Redis 不可用、下游服务故障）；
• 任务通过 Clock 进程（Clockwork）周期性入队，包含大量计费、发票、Webhook 等时间敏感任务，SidekiqQueueLatencyHigh（>300s）直接反映了用户可感知的延迟；
• SidekiqWorkerQuiet监控quiet=true的主机进程，quiet 模式是 Sidekiq 收到 SIGTSTP 后的优雅关闭状态，长时间处于该状态说明进程未正常退出，需要人工介入。

7. Grafana Dashboard 面板设计建议

在 Grafana 中为 Sidekiq 监控构建看板时，建议按如下分组组织面板：

1. Overview Row（总览行）

   • 已处理任务总数（Counter）
   • 当前失败率（Gauge）
   • 活跃 worker 数 vs 总 worker 数
   • 入队任务总数

2. Queue Health Row（队列健康行）

   • 各队列延迟（时间序列，sidekiq_queue_latency_seconds）
   • 各队列入队任务数（堆叠面积图，sidekiq_queue_enqueued_jobs）
   • 队列吞吐（各队列每秒任务数，sum by (queue) (rate(...))）

3. Worker Health Row（Worker 健康行）

   • 各主机进程数（表格，sidekiq_host_processes）
   • 忙碌 worker 随时间变化（sidekiq_busy_workers）
   • 处于 quiet 模式的 worker 数

4. Job Performance Row（任务性能行，需 Sidekiq Pro）

   • 各任务的 P50/P90/P99 执行时长
   • Top 10 最慢任务
   • 按任务类型统计的失败率
   • 按错误类型的失败分布

5. Capacity Planning Row（容量规划行）

   • 每小时处理任务数（趋势）
   • 队列深度趋势
   • Worker 利用率百分比

8. 与 Worker 架构、扩缩容实践的联动

监控的最终目的是指导运维决策。docs/architecture.md 的 Worker 架构章节与监控指标形成了闭环：

• 何时扩容（Scale Out）：队列积压上升、任务等待时间增长时，首先利用sidekiq_queue_enqueued_jobs、sidekiq_queue_latency_seconds定位到具体队列，再通过启用对应专用 worker（见 docker-compose.yml 中api-events-worker、api-billing-worker、api-webhook-worker等服务）将负载从默认 worker 剥离；
• 何时升配（Scale Up）：CPU 持续高于 80%、发生内存压力或 OOM、任务处理延迟升高，对应调整该 worker 的 CPU/内存请求与SIDEKIQ_CONCURRENCY；
• 自动扩缩容：可为 Horizontal Pod Autoscaler（HPA）配置基于 CPU 利用率（70–80% 目标）与队列深度指标（sidekiq_queue_enqueued_jobs）的双重扩缩容策略；
• 最小生产部署基线：API 2 副本 + 默认 worker 2 副本 + Clock 1 副本 + App 1 副本，随后按 PDF Worker → Webhook Worker → Events Worker → Billing Worker 的顺序逐步启用专用 worker。

在生产部署上，deploy/README.md 的 Monitoring 一节明确建议为 Sidekiq worker 配置监控，并指向本文档以获取：Prometheus 指标端点与可用指标清单、推荐的告警规则、Grafana 面板建议——即本文第 4～7 节的内容。

9. 附加资源

• Worker 架构与队列配置 — 各队列的用途、专用 worker 的启用方式与扩缩容建议
• Clock 系统（定时任务） — Clockwork 调度的周期任务清单，理解各队列任务来源
• 部署指南 — 生产部署时的监控接入建议
• Docker Compose 服务定义 — 默认 worker 与各专用 worker 的服务编排

【免费下载链接】lagoOpen Source Metering and Usage Based Billing API ⭐️ Consumption tracking, Subscription management, Pricing iterations, Payment orchestration & Revenue analytics项目地址: https://gitcode.com/GitHub_Trending/la/lago