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 │ │ │ └─────────────────────────────────────────────────────────────────────────┘两条链路的核心组件与职责如下Sidekiq Web UI Prometheus Exporterlago-sidekiqs服务默认启用内置sidekiq/prometheus/exportergem在/prometheus/metrics端点暴露指标提供队列级per-queue与全局global的 Sidekiq 统计信息同时支持 OSS 与 Pro 版本其 Rack 入口配置见lago-sidekiqs/config.ru该仓库api/为子模块未随本仓库拉取下同。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 Exporterlago-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 RedisSidekiq 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与servicesidekiq标签命名空间namespace: Rails.application.name决定了后面 3.3 节指标统一使用lago_api_前缀中间件注入通过server_middleware链挂载Sidekiq::Middleware::Server::Statsd从而在每个任务执行前后埋点。3.2 环境变量配置LAGO_SIDEKIQ_STATSD_ENDPOINTstatsd-exporter:9125设置该变量后指标会以 DogStatsD 协议发送到statsd-exporter的9125端口StatsD Exporter 的默认端口即 9125由后者转换成 Prometheus 格式供抓取。所有指标携带的标签包括标签含义示例env环境名productionservice固定为sidekiqsidekiqqueue队列名billingworker任务类名Job classInvoices::CreateAllServiceJoberror_type失败任务所属错误类别仅失败指标StandardError4. 基础 Prometheus 指标开源/Pro 均可用以下指标由lago-sidekiqs服务的/prometheus/metrics提供Sidekiq OSS 与 Pro 均可用。4.1 全局指标Global MetricsMetricTypeDescriptionsidekiq_processed_jobs_totalCounter已处理任务总数全时段累计sidekiq_failed_jobs_totalCounter失败任务总数全时段累计sidekiq_workersGauge所有进程中的工作线程总数sidekiq_processesGauge正在运行的 Sidekiq 进程数sidekiq_busy_workersGauge当前正在执行任务的 worker 数sidekiq_enqueued_jobsGauge所有队列中等待执行的任务总数sidekiq_scheduled_jobsGauge计划在未来执行的任务数sidekiq_retry_jobsGauge等待重试的任务数sidekiq_dead_jobsGauge死信队列dead queue中的任务数4.2 单主机指标Per-Host MetricsMetricTypeLabelsDescriptionsidekiq_host_processesGaugehost,quiet每台主机上的进程数。quiettrue表示该进程正处于优雅关闭状态4.3 单队列指标Per-Queue MetricsMetricTypeLabelsDescriptionsidekiq_queue_latency_secondsGaugename队列中最老任务自入队以来的时间即队列延迟秒sidekiq_queue_enqueued_jobsGaugename队列中等待执行的任务数sidekiq_queue_max_processing_time_secondsGaugename队列中最长运行任务的执行时长sidekiq_queue_workersGaugename服务该队列的工作线程数sidekiq_queue_processesGaugename服务该队列的进程数sidekiq_queue_busy_workersGaugename当前正在处理该队列任务的 worker 数运维提示sidekiq_queue_latency_seconds是判断任务积压最直接的风向标它与 docs/architecture.md 中扩缩容指南明确挂钩——当队列延迟上升、sidekiq_queue_enqueued_jobs持续增长时即应扩容对应 worker。4.4 队列清单理解指标name标签的业务含义Lago 的队列按业务类型划分指标中的name标签对应下表QueueWorker Typeai_agentAI Agent WorkeranalyticsAnalytics WorkerbillingBilling WorkerclockDefault Workerclock 任务clock_workerDedicated Clock WorkerdefaultDefault WorkereventsEvents Workerhigh_priorityDefault WorkerintegrationsDefault WorkerinvoicesDefault Workerlong_runningDefault Workerlow_priorityDefault WorkermailersDefault WorkerpdfsPDF WorkerprovidersDefault WorkerwalletsDefault Worker已废弃webhookDefault Workerwebhook 任务webhook_workerDedicated Webhook Worker结合仓库 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 指标清单MetricTypeLabelsDescriptionlago_api_jobs_countCounterqueue,worker执行的任务总数lago_api_jobs_successCounterqueue,worker成功完成任务数lago_api_jobs_failureCounterqueue,worker,error_type按错误类型统计的失败任务数lago_api_jobs_performSummaryqueue,worker任务执行时长秒含 p50、p90、p99 分位数lago_api_jobs_recovered_fetchCounterqueue从中断的 fetch 中恢复的任务数5.2 常用 PromQL 查询示例按 worker 统计任务失败率rate(lago_api_jobs_failure[5m]) / rate(lago_api_jobs_count[5m])billing 队列任务的 P99 执行时长lago_api_jobs_perform{queuebilling, quantile0.99}Top 10 最慢任务按中位数执行时长topk(10, lago_api_jobs_perform{quantile0.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 down6.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{quiettrue} 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{quantile0.99} 30 for: 5m labels: severity: warning annotations: summary: Slow job execution for {{ $labels.worker }} description: P99 execution time is {{ $value }}s6.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 retried6.4 阈值设定建议结合 docs/architecture.md 中的任务机制可以更好地理解这些阈值的含义Lago 默认不重试任务max_retries为 0sidekiq_options retry: 0因此sidekiq_dead_jobs的快速增长通常意味着出现了系统性失败如 Redis 不可用、下游服务故障任务通过 Clock 进程Clockwork周期性入队包含大量计费、发票、Webhook 等时间敏感任务SidekiqQueueLatencyHigh300s直接反映了用户可感知的延迟SidekiqWorkerQuiet监控quiettrue的主机进程quiet 模式是 Sidekiq 收到 SIGTSTP 后的优雅关闭状态长时间处于该状态说明进程未正常退出需要人工介入。7. Grafana Dashboard 面板设计建议在 Grafana 中为 Sidekiq 监控构建看板时建议按如下分组组织面板Overview Row总览行已处理任务总数Counter当前失败率Gauge活跃 worker 数 vs 总 worker 数入队任务总数Queue Health Row队列健康行各队列延迟时间序列sidekiq_queue_latency_seconds各队列入队任务数堆叠面积图sidekiq_queue_enqueued_jobs队列吞吐各队列每秒任务数sum by (queue) (rate(...))Worker Health RowWorker 健康行各主机进程数表格sidekiq_host_processes忙碌 worker 随时间变化sidekiq_busy_workers处于 quiet 模式的 worker 数Job Performance Row任务性能行需 Sidekiq Pro各任务的 P50/P90/P99 执行时长Top 10 最慢任务按任务类型统计的失败率按错误类型的失败分布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 UpCPU 持续高于 80%、发生内存压力或 OOM、任务处理延迟升高对应调整该 worker 的 CPU/内存请求与SIDEKIQ_CONCURRENCY自动扩缩容可为 Horizontal Pod AutoscalerHPA配置基于 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 面板建议——即本文第 47 节的内容。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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考