rails_pod_kit 0.0.3 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 24c0e428faf1a3c46646a1d7a0e693b5cde8373f6aea61f9dc005d6b6dcba192
-  data.tar.gz: 968fc08545c75f5b22f91c2c882068b20069d7bb2bb6f48d1abf2aa09f4bc71b
+  metadata.gz: 85fea66a44c5b2198b5c3c7bfd05f5f1f4c3655559ed701748661d0e148650a5
+  data.tar.gz: 9c921528f839ea1d5b962035600316ea37affe17cf8fdc910453c30108a248dd
 SHA512:
-  metadata.gz: 266b27abb0911f031e54522dfcea870d603e1ec143465b4441a206590654087c1604a9aeb4438745bc10600bf3696b7d4938c0c936e0145322b76cb0279a5513
-  data.tar.gz: dedc4665fb51d38b9e713caead650ee875108aed4a24e9f27bb3053f2ec0152bdcc0f3840cc0ac76056858f330b723c502bc5f66d726261db47a7033e6ae2142
+  metadata.gz: d7fbfee31ce338a6dd7c11d65214dc442cd2cb261848ae2403a415dc4a6e1333fa55b39e2d06441b4e05fcacff2ec3971ee009613a532f384fcc19fbe84f070d
+  data.tar.gz: 894f99f9fba4596aa7d69e143f5fa23d2ebc64ef85f6b7cac310096c902005dd003103cb12c3933e49dfe26263c68f9656cfc3e68c0d9551a8f118e79496fd48

data/README.md

@@ -3,14 +3,17 @@
 The operational endpoints a Rails pod needs to be a good Kubernetes citizen,
 packaged behind a single, opinionated entry point:
 
-- **Prometheus metrics** for Puma and Sidekiq, served **in-process** on a
-  single `/metrics` endpoint (default port **9394**) in both the web (Puma) and
-  worker (Sidekiq) processes — no sidecar, no separate collector process. A
-  metrics agent (e.g. the Datadog Agent via OpenMetrics autodiscovery) scrapes
-  the pod directly.
+- **Prometheus metrics** for Puma, Sidekiq and SolidQueue, served **in-process**
+  on a single `/metrics` endpoint (default port **9394**) in the web (Puma) and
+  worker processes — no sidecar, no separate collector process. A metrics agent
+  (e.g. the Datadog Agent via OpenMetrics autodiscovery) scrapes the pod
+  directly.
 - **Health checks** on `/healthz` (database, cache, optionally Redis and Sidekiq),
   wired for Kubernetes startup/liveness/readiness probes — a thin, opinionated
   wrapper around [health-monitor-rails](https://github.com/lbeder/health-monitor-rails).
+- **Scheduler hosting for scale-to-zero**, so a job executor can be autoscaled to
+  zero without stranding its recurring and scheduled jobs: a supervised
+  SolidQueue scheduler thread, and a supervised sidekiq-cron poller for Sidekiq.
 
 The metrics side is a thin wrapper around the
 [yabeda](https://github.com/yabeda-rb) ecosystem:
@@ -21,11 +24,14 @@ The metrics side is a thin wrapper around the
 | `yabeda-puma-plugin` | Puma thread-pool / worker stats + the `:yabeda` / `:yabeda_prometheus` Puma plugins |
 | `yabeda-sidekiq` | Sidekiq per-process job metrics + global/Redis-wide queue metrics |
 | `yabeda-prometheus-mmap` | Prometheus text exporter, multiprocess-safe via `prometheus-client-mmap` |
-| `webrick` | HTTP server for the Sidekiq exporter |
+| `webrick` | HTTP server for the non-Puma exporters |
 
-> Scope: **runtime/worker metrics only** (Puma backlog/threads, Sidekiq queues
-> and jobs). HTTP request-level metrics are intentionally out of scope — that is
-> covered by APM.
+The SolidQueue queue gauges are the gem's own: SolidQueue ships no metrics
+endpoint and there is no `yabeda-solid_queue` plugin to wrap.
+
+> Scope: **runtime/worker metrics only** (Puma backlog/threads, Sidekiq and
+> SolidQueue queues and jobs). HTTP request-level metrics are intentionally out
+> of scope — that is covered by APM.
 
 The gem is deliberately **connection-agnostic**: it never reads `REDIS_URL` and
 makes no TLS decisions. Wherever a Redis connection is needed (health checks,
@@ -67,19 +73,24 @@ RailsPodKit::Puma.activate(self)
 RailsPodKit::Sidekiq.install!(config)
 ```
 
+On a SolidQueue stack there is no step 3 — see
+[SolidQueue](#solidqueue-scale-to-zero) instead.
+
 ## Configuration
 
 `RailsPodKit::Config` is an [anyway_config](https://github.com/palkan/anyway_config)
 config: besides the `RailsPodKit.configure` block (which runs last and wins),
 every setting can come from a `RAILS_POD_KIT_*` env var (e.g.
 `RAILS_POD_KIT_ENABLED=false`, `RAILS_POD_KIT_PORT=9500`,
-`RAILS_POD_KIT_SIDEKIQ_GLOBAL_METRICS=off`) or an optional
+`RAILS_POD_KIT_SIDEKIQ_GLOBAL_METRICS=off`,
+`RAILS_POD_KIT_SCHEDULER_ENABLED=false`) or an optional
 `config/rails_pod_kit.yml` — handy for the Rails-free exporter pod, which runs
 no initializers.
 
 | setting | default | meaning |
 |---------|---------|---------|
-| `enabled` | on, except in `test` | master switch; `false` ⇒ no exporter, no port bound |
+| `enabled` | on, except in `test` | master switch for the **exporter**; `false` ⇒ no exporter, no port bound |
+| `scheduler_enabled` | on, everywhere | kill switch for the **hosted schedulers** (sidekiq-cron poller, SolidQueue scheduler thread). Separate from `enabled` — an app may want one without the other, and this is the one you may need to flip in a hurry, since the scheduler is a single point of failure for the whole schedule. On even in `test`: nothing starts a scheduler implicitly, so there is no port to protect, and a switch that failed closed on a typo would silently stop a schedule. Turning it off logs a warning naming the scheduler that did not start. |
 | `port` | `9394` (env `PROMETHEUS_EXPORTER_PORT`) | exporter bind port for Puma **and** Sidekiq |
 | `sidekiq_global_metrics` | `:web` | who exports the Redis-wide queue metrics: `:web` = only the always-on web process (no per-worker duplication); `:all` = every worker; `:off` = nobody |
 | `puma_control_url` | `tcp://127.0.0.1:9293` (env `PUMA_CONTROL_URL`) | localhost-only Puma control app the stats reader queries |
@@ -148,6 +159,8 @@ endpoint every few seconds); pass `silence_controller_log: false` to keep it.
   `sidekiq_queue_latency`, `sidekiq_active_processes`,
   `sidekiq_active_workers_count`, `sidekiq_jobs_retry_count`,
   `sidekiq_jobs_dead_count`, `sidekiq_jobs_scheduled_count`.
+- **SolidQueue (DB-wide):** `solid_queue_backlog`,
+  `solid_queue_latency_seconds`.
 
 Series are intentionally **untagged**: a scraping agent adds
 `service`/`env`/`version` and `kube_*` tags at scrape time, so the gem doesn't
@@ -182,35 +195,53 @@ instances:
     raw_metric_prefix: "sidekiq_"   # sidekiq_queue_latency -> sidekiq.queue_latency
     metrics: [".*"]
     tag_by_endpoint: false
+
+# SolidQueue (the pod publishing the queue gauges) — :9394/metrics
+instances:
+  - openmetrics_endpoint: "http://%%host%%:9394/metrics"
+    namespace: "solid_queue"
+    raw_metric_prefix: "solid_queue_"  # solid_queue_backlog -> solid_queue.backlog
+    metrics: [".*"]
+    tag_by_endpoint: false
 ```
 
+**One prefix per endpoint.** `metrics: [".*"]` ingests *everything* served
+there, so each block above assumes its endpoint carries a single group — which
+is why the SolidQueue gauges are best published from their own pod (below).
+Where one endpoint really must carry two groups (e.g. a web pod exposing both
+`puma_*` and `solid_queue_*`), give **every** instance on it an explicit filter
+— `metrics: ["puma_.*"]` and `metrics: ["solid_queue_.*"]` — or each namespace
+will swallow the other's series un-stripped.
+
 On Kubernetes this is typically wired as pod-annotation autodiscovery. The
 `openmetrics_endpoint` above uses the Datadog Agent's `%%host%%` autodiscovery
 template (resolves to the pod IP) — a **non-k8s adopter** (a plain `conf.yaml`
 check) swaps `%%host%%:9394` for the real `host:port`; everything else
 (`namespace`, `raw_metric_prefix`, `metrics`) is identical.
 
-### Invariant — the endpoint must stay prefix-pure
+### Invariant — every series must carry a group prefix
 
 The Datadog check uses `metrics: [".*"]`, which ingests **every** series on the
 endpoint. `raw_metric_prefix` only *strips* the prefix when present — **it does
 not filter**. So the naming scheme above holds only because the `/metrics`
-endpoint exposes **solely** yabeda-registered series, all sharing the
-`puma_` / `sidekiq_` group prefix:
+endpoint exposes **solely** yabeda-registered series, each carrying its
+`puma_` / `sidekiq_` / `solid_queue_` group prefix:
 
-- the gem registers only the `:puma` and `:sidekiq` yabeda groups (no process,
-  GC, or Ruby-runtime collectors);
+- the gem registers only the `:puma`, `:sidekiq` and `:solid_queue` yabeda
+  groups (no process, GC, or Ruby-runtime collectors);
 - the exposition serves Yabeda's registry only — the Prometheus client's HTTP
   request collector (`http_*`) is **not** mounted on the exporter.
 
-If a series without the `puma_` / `sidekiq_` prefix ever appeared on the
-endpoint, `metrics: [".*"]` would ingest it **un-stripped** under the namespace
-(e.g. `puma.http_requests_total`). **Do not** add cross-cutting metrics (process,
-runtime, HTTP request) to this exporter, and do not mount the Prometheus Rack
-collector on it. If you ever need such metrics, expose them on a separate
-endpoint with its own check rather than polluting this one. Conversely, any new
-metric you *do* add to the `:puma` / `:sidekiq` groups is picked up automatically
-by `[".*"]` — no check change needed.
+If an unprefixed series ever appeared on the endpoint, `metrics: [".*"]` would
+ingest it **un-stripped** under the namespace (e.g. `puma.http_requests_total`).
+**Do not** add cross-cutting metrics (process, runtime, HTTP request) to this
+exporter, and do not mount the Prometheus Rack collector on it. If you ever need
+such metrics, expose them on a separate endpoint with its own check rather than
+polluting this one. Conversely, any new metric you *do* add to an existing group
+is picked up automatically by `[".*"]` — no check change needed.
+
+`spec/rails_pod_kit/metrics_invariant_spec.rb` guards this at both the registry
+and the exposition level.
 
 > ⚠️ Renaming the namespace prefix is a **breaking metric rename** — existing
 > dashboards/monitors built on the old `puma.puma_*` / `sidekiq.sidekiq_*` series
@@ -258,6 +289,13 @@ Sidekiq job class.
 | `sidekiq.job_runtime` | histogram | `queue`, `worker` |
 | `sidekiq.job_latency` | histogram | `queue`, `worker` |
 
+**SolidQueue — DB-wide queue state** (`namespace: solid_queue`):
+
+| canonical Datadog metric | type | functional tags |
+|---|---|---|
+| `solid_queue.backlog` | gauge | `queue` |
+| `solid_queue.latency_seconds` | gauge | `queue` |
+
 ### Where Sidekiq global metrics come from
 
 The global (Redis-wide) queue gauges — `sidekiq_jobs_waiting_count`,
@@ -313,10 +351,227 @@ declares the cluster gauges, starts the exporter and blocks until SIGTERM.
 Booting the full host app just to read a handful of Redis counters would cost
 ~300Mi RSS for nothing — this process sits at ~60Mi.
 
+## Sidekiq: scale-to-zero
+
+Being an always-on singleton makes that same pod the right home for the
+**sidekiq-cron poller**, which is what lets the worker fleet scale to zero.
+
+sidekiq-cron installs its poller from inside `Sidekiq.configure_server`, so on
+its own the schedule exists only while a Sidekiq server is alive. At zero
+replicas nothing polls, nothing is enqueued, and nothing ever raises the queue
+depth that would wake a worker back up — a closed loop that forces a permanent
+floor of one replica just to keep a poller alive. Missed runs are not caught up
+afterwards either: `reschedule_grace_period` (60s by default) discards any run
+older than itself.
+
+The poller has no such requirement of its own — `Sidekiq::Cron::Poller` is a
+Redis-polling thread that runs in any process holding a Sidekiq config — so
+`scheduler: true` hosts it here:
+
+```ruby
+RailsPodKit::GlobalExporter.run!(
+  redis: { url: ENV['REDIS_URL'] },
+  scheduler: true,
+  schedule_file: File.expand_path('../config/schedule.yml', __dir__)
+)
+```
+
+`schedule_file:`, `poll_interval:` and `reschedule_grace_period:` override
+sidekiq-cron's defaults (`config/schedule.yml` resolved against the working
+directory, polled every 30s, catching up runs at most 60s late);
+`supervision_interval:` tunes the liveness check. `RailsPodKit::GlobalScheduler`
+is usable on its own (`start!` / `stop!`) if the always-on process is something
+other than the exporter.
+
+> **Size `reschedule_grace_period` over your worst restart.** It is what makes
+> restarting the *only* scheduling process free: below it a missed occurrence is
+> caught up on the next poll, above it the run is skipped silently. sidekiq-cron
+> defaults to 60s, which a node drain or an evicted pod can easily exceed —
+> rolling updates are covered anyway, since a `maxSurge` overlap means there is
+> no gap at all. Catching up is bounded, not repeated: `last_enqueue_time` in
+> Redis still gates each occurrence to exactly one enqueue.
+>
+> This is the reason a singleton scheduler does **not** need to become an HA
+> pair. A second replica is safe for the poller (same `zadd` lock) but doubles
+> every metric series the pod publishes, and a `PodDisruptionBudget` on a
+> single-replica Deployment stalls node drains rather than protecting anything.
+
+The poller runs under `RailsPodKit::Supervisor` — the same supervising timer
+that keeps the SolidQueue scheduler thread alive, since both share the failure
+mode: the thread dies, the host process notices nothing, and the schedule stops
+silently. The cron poller's own loop swallows StandardError, so a Redis blip
+costs one skipped tick; the supervisor makes anything it does *not* catch a
+skipped tick too.
+
+> **Every schedule entry must declare `active_job: true`.** This process has no
+> Rails, so it cannot resolve the job classes; sidekiq-cron then falls back to
+> pushing a raw message, and only that flag makes the message an ActiveJob
+> wrapper (naming the class as a *string*, which the worker resolves). Without it
+> the job is pushed as a bare Sidekiq job and runs outside ActiveJob entirely.
+> `start!` logs a warning naming any entry in that state. For the same reason the
+> schedule file's ERB must not reach for Rails.
+
+Leaving the workers' own poller in place is fine and costs nothing: enqueueing is
+gated on a Redis `zadd` that exactly one caller wins — the same lock that already
+lets multiple worker replicas coexist without double-firing. Both processes must
+then read the *same* schedule file, though: `load_from_hash!` removes the
+schedule-sourced jobs that are absent from the file it is given, so two processes
+loading different files will delete each other's entries.
+
+## SolidQueue: scale-to-zero
+
+SolidQueue's executor has nothing to do while the queue is empty, so it is the
+natural candidate for **scale-to-zero** autoscaling (KEDA, or an HPA). Two things
+stand in the way, and the gem covers both. Everything here is opt-in; requiring
+the gem alone changes nothing.
+
+### 1. The scheduler has to move off the executor
+
+With the executor at zero there is no scheduler, so nothing enqueues the
+recurring and scheduled jobs that would wake one — the queue stays empty because
+it is empty. A k8s CronJob can't take over either: it can't own **dynamic**
+recurring tasks, the ones created and updated at runtime through
+`SolidQueue.schedule_recurring_task`.
+
+The fix is to run the *scheduler alone* on a process that is always on, and let
+the executor be nothing but dispatcher + workers (`bin/jobs` with
+`SOLID_QUEUE_SKIP_RECURRING=true`):
+
+```ruby
+# config/puma.rb — after_booted only runs in the real Puma process, never in a
+# console, a rake task or the test suite.
+after_booted { RailsPodKit::SolidQueue.start_scheduler! }
+at_exit      { RailsPodKit::SolidQueue.stop_scheduler! }
+```
+
+This is deliberately **not** `plugin :solid_queue`. That one runs the full
+supervisor, which forks and whose watchdog takes Puma down when the supervisor
+exits — and a transient Postgres disconnect is enough to cause that
+([rails/solid_queue#512](https://github.com/rails/solid_queue/issues/512)). Here
+a DB blip at worst kills the scheduler thread; `RailsPodKit::Supervisor` — a
+`Concurrent::TimerTask`, the same primitive SolidQueue supervises its own
+processes with, and the same one that keeps the sidekiq-cron poller alive —
+notices on the next tick and starts a fresh one, the process itself never
+notices, and the scheduler re-registers on recovery.
+
+Running it on every replica is safe: enqueues stay exactly-once via the unique
+index on `solid_queue_recurring_executions (task_key, run_at)`. Static tasks come
+from `config/recurring.yml` (honouring `SOLID_QUEUE_RECURRING_SCHEDULE`), dynamic
+ones from the DB.
+
+| option | default | meaning |
+|---|---|---|
+| `polling_interval` | `5` | how often the scheduler re-reads the dynamic tasks |
+| `supervision_interval` | `5` | how often we check the scheduler thread is alive |
+| `recurring_schedule_file` | `config/recurring.yml` | static task definitions; skipped when absent |
+
+`start_scheduler!` is **not** gated on `enabled` — that switch owns the metrics
+exporter, and an app may well want the scheduler with metrics off.
+`scheduler_enabled` is the switch that does own it, shared with the sidekiq-cron
+poller. Beyond that, what keeps it out of consoles and specs is *where* you call
+it from.
+
+### 2. Queue depth has to be visible
+
+SolidQueue publishes no metrics, so the autoscaler and the dashboards have
+nothing to read. `install_metrics!` adds two gauges, computed **at scrape time**
+from the SolidQueue tables (a yabeda `collect` block — no background thread, no
+cached snapshot):
+
+```ruby
+# config/initializers/rails_pod_kit.rb
+RailsPodKit::SolidQueue.install_metrics!
+```
+
+| metric | meaning |
+|---|---|
+| `solid_queue_backlog` | how many jobs could be claimed right now, per `queue` |
+| `solid_queue_latency_seconds` | how long the oldest of them has been waiting, per `queue` |
+
+"Claimable right now" is ready executions **plus** scheduled ones whose time has
+come — the dispatcher has only to move those across. A scheduled job's wait is
+measured from its `scheduled_at`, not its `created_at`: enqueuing a week ahead of
+the slot doesn't make it a week late.
+
+Both matter, and neither alone is enough: backlog misses a small-but-stalled
+queue, latency misses a large-but-moving one.
+
+**An idle system reads 0, not no-data.** A queue that drains is explicitly zeroed
+rather than left pinned at its last reading, and the zeroing starts from a
+baseline of every queue the app is known to use — discovered once per process
+from the jobs table, or pinned by the host:
+
+```ruby
+RailsPodKit::SolidQueue.install_metrics!(queues: %w[default mailers])
+```
+
+Without that baseline a process booting while the queue is empty — the steady
+state of a scale-to-zero deployment — would publish no series at all, since a
+gauge only exists once it has been set. Discovery is best-effort: the jobs table
+is bounded by `clear_finished_jobs_after`, so a queue idle for longer than the
+retention window leaves no trace in it. Pin `queues:` where the zero has to be
+guaranteed.
+
+**A collection error is always reported** (logged, plus handed to
+`Rails.error`), then either swallowed or raised:
+
+| | |
+|---|---|
+| `fail_scrape_on_error: false` (default) | serve the last reading. Right on an endpoint shared with the Puma or Sidekiq series, where failing the response would lose those too — at the cost of a stale gauge a consumer cannot tell apart from a live one. |
+| `fail_scrape_on_error: true` (`run_exporter!`'s default) | fail the scrape. Right on the dedicated pod, where there is nothing else to protect: the gauges go to no-data and the scrape failure shows up in the scraper's own `up` series. |
+
+### The always-on pod
+
+The cleanest home for both is a **1-replica Deployment** that hosts the scheduler
+and publishes the gauges, decoupled from the web and the executor — so the
+signals survive either scaling to zero, and each series has exactly one source.
+`run_exporter!` is that process: it declares the gauges, starts the scheduler,
+serves `/metrics` and blocks until SIGTERM (winding the scheduler down so it
+deregisters rather than expiring).
+
+Unlike the Sidekiq global exporter it is **not** Rails-free — SolidQueue is
+ActiveRecord-backed and reads the app's own tables — so the host's entrypoint
+boots the environment first. The gem ships no executable; e.g.
+`bin/solid-queue-pod`:
+
+```ruby
+#!/usr/bin/env ruby
+require_relative '../config/environment'
+
+RailsPodKit::SolidQueue.run_exporter!
+```
+
+```
+command: ["bin/solid-queue-pod"]
+```
+
+Pass `scheduler: false` to serve the gauges only, on an app whose web process
+already hosts the scheduler, and `metrics:` to override the gauge options (this
+endpoint is the collector's own, so `fail_scrape_on_error` defaults to `true`
+here):
+
+```ruby
+RailsPodKit::SolidQueue.run_exporter!(scheduler: false, metrics: { queues: %w[default mailers] })
+```
+
+Keep the endpoint single-prefix (see
+[One prefix per endpoint](#datadog-naming--the-canonical-metric-set)) — that pod
+serves `solid_queue_*` and nothing else, so the check config needs no filters.
+
 ## Caveats
 
 - **Puma only.** The Puma plugins only activate under Puma; under any other
-  app server the in-process `/metrics` endpoint is **not** exposed.
+  app server the in-process `/metrics` endpoint is **not** exposed. The non-Puma
+  entry points (Sidekiq, the global exporter, the SolidQueue pod) serve it from
+  a WEBrick thread instead, started at most once per process.
+- **SolidQueue and Sidekiq are the host's.** The gem depends on neither; the
+  SolidQueue integration is inert until you call it, exactly like the Sidekiq one.
+  `sidekiq-cron` too: it is required only when `GlobalScheduler.start!` is called,
+  so an app that does not schedule anything need not carry it.
+- **Queue-gauge query cost.** The gauges run four small grouped aggregates per
+  scrape. `MIN(created_at)` is not covered by SolidQueue's indexes, so on a
+  backlog of many thousands of rows it is a scan — cheap at a normal scrape
+  interval, worth knowing about if you scrape aggressively.
 - **Puma control app.** `yabeda-puma-plugin` reads Puma's thread-pool stats
   through Puma's control app, so `Puma.activate` activates one on a
   localhost-only socket (`no_token: true`, never network-exposed).
@@ -352,6 +607,10 @@ curl -s localhost:9394/metrics | grep '^puma_'
 bundle exec sidekiq
 curl -s localhost:9394/metrics | grep '^sidekiq_'
 
+# SolidQueue: solid_queue_* series (enqueue a job first so the queue isn't empty)
+bin/solid-queue-pod
+curl -s localhost:9394/metrics | grep '^solid_queue_'
+
 # Health endpoint
 curl -s localhost:3000/healthz -H 'Accept: application/json'
 ```

data/VERSION

@@ -1 +1 @@
-0.0.3
+0.2.0

data/lib/rails_pod_kit/config.rb

@@ -60,17 +60,29 @@ module RailsPodKit
     #   transports — the Puma plugin's exporter (`prometheus_silence_logger`)
     #   and the WEBrick exporter used by Sidekiq / the dedicated global exporter
     #   (`Rack::CommonLogger`). Flip to false only to debug the exporter itself.
+    # scheduler_enabled: kill switch for the hosted schedulers (the sidekiq-cron
+    #   poller and the SolidQueue scheduler thread). Separate from `enabled`,
+    #   which owns the metrics exporter: an app may well want one without the
+    #   other, and the scheduler is the piece you may need to turn off in a
+    #   hurry — it is a single point of failure for the whole schedule, and
+    #   `RAILS_POD_KIT_SCHEDULER_ENABLED=false` + a restart beats a deploy at
+    #   3am. Defaults to on *including* in the test env, unlike `enabled`:
+    #   nothing starts a scheduler implicitly (it takes an explicit call from an
+    #   entry point), so there is no port to protect, and a flag that fails
+    #   closed on a typo would silently stop a schedule.
     attr_config :enabled,
                 :port,
                 :puma_control_url,
                 sidekiq_global_metrics: :web,
                 retries_segmented_by_queue: false,
-                silence_exporter_access_log: true
+                silence_exporter_access_log: true,
+                scheduler_enabled: true
 
     coerce_types port: :integer,
                  enabled: :boolean,
                  retries_segmented_by_queue: :boolean,
-                 silence_exporter_access_log: :boolean
+                 silence_exporter_access_log: :boolean,
+                 scheduler_enabled: :boolean
 
     def initialize(overrides = nil)
       super
@@ -87,6 +99,10 @@ module RailsPodKit
       !!enabled
     end
 
+    def scheduler_enabled?
+      !!scheduler_enabled
+    end
+
     # True unless we're clearly in a test environment. Kept independent of
     # Rails so the gem's own specs (which don't load the host app) get a safe
     # default and never bind a socket.
@@ -114,5 +130,15 @@ module RailsPodKit
     def enabled?
       config.enabled?
     end
+
+    # Gate shared by both hosted schedulers. Says so out loud when it turns one
+    # off: a process that starts, stays up and quietly schedules nothing is the
+    # one failure this whole feature exists to avoid.
+    def scheduler_enabled?(what = 'scheduler')
+      return true if config.scheduler_enabled?
+
+      warn "[rails_pod_kit] scheduler_enabled=false — #{what} not started"
+      false
+    end
   end
 end

data/lib/rails_pod_kit/error_reporter.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module RailsPodKit
+  # Where the gem's background work (the SolidQueue scheduler supervisor, the
+  # scrape-time metric collectors) sends the errors it swallows. Those errors
+  # must never propagate — one would kill the supervising timer or fail the whole
+  # /metrics response — but they must not vanish either.
+  #
+  # Always logs, and additionally hands the error to the Rails error reporter
+  # when there is one, so the host's Rollbar / Sentry / Datadog subscriber picks
+  # it up. The log line is not redundant: `Rails.error.report` only fans out to
+  # subscribers, so on an app with none — or with one that is not wired in a
+  # given environment — the failure would otherwise leave no trace at all, and
+  # the only symptom of a broken collector is a gauge quietly serving a stale
+  # value.
+  module ErrorReporter
+    module_function
+
+    def report(error, source:)
+      message = "[#{source}] #{error.class}: #{error.message}"
+      logger ? logger.error(message) : warn(message)
+
+      rails_reporter&.report(error, handled: true, source: source)
+    end
+
+    def logger
+      ::Rails.logger if defined?(::Rails) && ::Rails.respond_to?(:logger)
+    end
+
+    def rails_reporter
+      ::Rails.error if defined?(::Rails) && ::Rails.respond_to?(:error)
+    end
+  end
+end

data/lib/rails_pod_kit/exporter.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'rails_pod_kit/config'
+
+module RailsPodKit
+  # The in-process WEBrick /metrics server, shared by every non-Puma entry
+  # point: the Sidekiq worker, the Rails-free global exporter and the SolidQueue
+  # exporter. Under Puma the exporter comes from the `:yabeda_prometheus` plugin
+  # instead (see RailsPodKit::Puma), so this is never used there.
+  module Exporter
+    module_function
+
+    # Starts the background exporter and returns whether it did. Idempotent: the
+    # latch keeps a re-entrant boot from double-binding the port.
+    def start!
+      return false unless RailsPodKit.enabled?
+      return false if @started
+
+      require 'yabeda/prometheus/mmap'
+
+      # `start_metrics_server!` reads the bind port from the env, so publish the
+      # configured one first.
+      ENV['PROMETHEUS_EXPORTER_PORT'] ||= RailsPodKit.config.port.to_s
+      # Drop the exporter's per-scrape access log (Rack::CommonLogger, which the
+      # mmap exporter mounts unless this is exactly 'false'). See
+      # Config#silence_exporter_access_log.
+      ENV['PROMETHEUS_EXPORTER_LOG_REQUESTS'] = 'false' if RailsPodKit.config.silence_exporter_access_log
+
+      Yabeda::Prometheus::Exporter.start_metrics_server!
+      @started = true
+    end
+
+    def started?
+      !!@started
+    end
+
+    # Test/reset hook — drops the "already started" latch.
+    def reset!
+      @started = false
+    end
+  end
+end

data/lib/rails_pod_kit/global_exporter.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require 'rails_pod_kit/config'
+require 'rails_pod_kit/global_scheduler'
+require 'rails_pod_kit/shutdown'
 
 module RailsPodKit
   # Standalone, always-on exporter for the Sidekiq global (Redis-wide) queue
@@ -26,6 +28,10 @@ module RailsPodKit
   #   require 'bundler/setup'
   #   require 'rails_pod_kit/global_exporter'
   #   RailsPodKit::GlobalExporter.run!(redis: { url: ENV['REDIS_URL'] })
+  #
+  # Being an always-on singleton also makes it the natural host for the
+  # sidekiq-cron poller (`scheduler: true`, see GlobalScheduler), which is what
+  # lets the workers scale to zero without losing their schedule.
   module GlobalExporter
     module_function
 
@@ -47,22 +53,34 @@ module RailsPodKit
     # `redis:` takes the same options hash the host passes to its own
     # `Sidekiq.configure_*` blocks (`url:`, `ssl_params:`, …), so the connection
     # config stays a host decision with a single source of truth.
-    def run!(redis:)
-      unless RailsPodKit.enabled?
-        warn '[rails_pod_kit] disabled — global exporter not started'
-        return
-      end
+    #
+    # `scheduler: true` additionally runs the sidekiq-cron poller here; any
+    # extra keywords are GlobalScheduler.start!'s (`schedule_file:`,
+    # `poll_interval:`, `supervision_interval:`). The scheduler is not gated on
+    # `RailsPodKit.enabled?` —
+    # that switch owns the metrics exporter, and an app may well want the
+    # singleton scheduler with metrics turned off.
+    def run!(redis:, scheduler: false, **scheduler_options)
+      serve_metrics = RailsPodKit.enabled?
+      warn '[rails_pod_kit] disabled — /metrics not served by the global exporter' unless serve_metrics
+      return unless serve_metrics || scheduler
 
       configure_redis!(redis)
+      start_metrics! if serve_metrics
+      GlobalScheduler.start!(**scheduler_options) if scheduler
+
+      # Both the exporter and the poller serve from background threads; block
+      # the main thread so the process stays up until the kubelet sends SIGTERM.
+      Shutdown.await
+      GlobalScheduler.stop! if scheduler
+    end
+
+    def start_metrics!
       install!
       RailsPodKit::Sidekiq.start_metrics_server!
 
       require 'yabeda'
       Yabeda.configure! unless Yabeda.already_configured?
-
-      # The exporter serves from a background thread; block the main thread so
-      # the process stays up until the kubelet sends SIGTERM.
-      sleep
     end
 
     # Configure the Sidekiq client's Redis connection so this Rails-free process