rails_pod_kit 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fb47aab3b005492f13eaaa6ede0a89a5891cfbc8d034ebc0f1284b590efbb59a
+  data.tar.gz: 3f0f50b521bb1f96655edcbb296ea00156f90b631239491c49fad381f351989e
+SHA512:
+  metadata.gz: 33733cd886176b0341314e9ba6641cb0368f6010e3d24e0b11851d8a18d32119dd183eb8f17a885d8be5f4c5e36d7b123205d5051bf79b90e8f0cc95b434d0ef
+  data.tar.gz: db116a08eb1b3fb3c0d4017a5be0082568e48907032717d35dbb10933f741811b0009c64749937747aa44e45db0dbb73a1647d288f1dca986c6ec8007cc4531e

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Fabio Napoleoni
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,362 @@
+# rails_pod_kit
+
+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.
+- **Health checks** on `/healthz` (database, cache, Redis, optionally Sidekiq),
+  wired for Kubernetes startup/liveness/readiness probes — a thin, opinionated
+  wrapper around [health-monitor-rails](https://github.com/lbeder/health-monitor-rails).
+
+The metrics side is a thin wrapper around the
+[yabeda](https://github.com/yabeda-rb) ecosystem:
+
+| gem | what it gives us |
+|-----|------------------|
+| `yabeda` | in-process metrics registry |
+| `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 |
+
+> 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 gem is deliberately **connection-agnostic**: it never reads `REDIS_URL` and
+makes no TLS decisions. Wherever a Redis connection is needed (health checks,
+the dedicated global exporter) the host injects its own options, so connection
+config keeps a single, host-owned source of truth.
+
+## Wiring
+
+The host app wires the gem in three one-liners. Every metrics hook is a
+complete no-op when the exporter is disabled or in the `test` environment, so
+the suite never binds the port. The integrations wire themselves at
+`Bundler.require` and the gem's Railtie mounts the health endpoint — no
+`require:` gymnastics in the Gemfile, no routes change.
+
+**1. `config/initializers/rails_pod_kit.rb`** — configure once:
+
+```ruby
+RailsPodKit.configure do |c|
+  c.enabled = !Rails.env.test?
+  c.port    = Integer(ENV.fetch('PROMETHEUS_EXPORTER_PORT', 9394))
+end
+
+RailsPodKit::Health.install!(
+  redis:   { url: ENV['REDIS_URL'] },              # the host's own Redis options
+  sidekiq: { queue_size: 200, latency: 10.minutes } # omit on hosts without Sidekiq
+)
+```
+
+**2. `config/puma.rb`** — activate the Puma plugins:
+
+```ruby
+require 'rails_pod_kit/puma'
+RailsPodKit::Puma.activate(self)
+```
+
+**3. `config/initializers/sidekiq.rb`** (inside `Sidekiq.configure_server`):
+
+```ruby
+RailsPodKit::Sidekiq.install!(config)
+```
+
+## 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
+`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 |
+| `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 |
+| `retries_segmented_by_queue` | `false` | when `true`, the global retry gauge (`sidekiq_jobs_retry_count`) carries a `queue` tag instead of being a single scalar. Opt-in: per-queue retries increase series cardinality. |
+| `silence_exporter_access_log` | `true` | suppress the exporter's per-scrape `GET /metrics` access log on **both** transports (Puma plugin + WEBrick). The endpoint is pod-internal and scraped on a fixed interval, so the line is pure noise. Set `false` only to debug the exporter. |
+
+## Health checks (`RailsPodKit::Health`)
+
+`Health.install!` configures health-monitor-rails with the kit's defaults:
+endpoint at `/healthz`, checking **database** (health_monitor's default),
+**cache**, **Redis** (connection injected by the host) and — when a `sidekiq:`
+thresholds hash is given — **Sidekiq**. The gem's Railtie mounts
+`HealthMonitor::Engine` at `/` automatically; pass `mount: false` to keep
+route ownership (custom mount point, constraints) and mount it yourself in
+`config/routes.rb`. Any further tuning goes through the optional block, which
+receives the `HealthMonitor` configuration.
+
+```ruby
+RailsPodKit::Health.install!(
+  redis:   { url: ENV['REDIS_URL'] }, # or a ready Redis/ConnectionPool object
+  path:    :healthz,                  # default
+  sidekiq: { queue_size: 200, latency: 10.minutes }
+) do |config|
+  config.error_callback = ->(e) { ... } # host-specific extras
+end
+```
+
+Probe wiring on Kubernetes:
+
+- **startup probe** → `/healthz` — the full check, so the pod doesn't go ready
+  until its dependencies are actually up;
+- **liveness/readiness probes** → `/healthz?providers[]=none` — short-circuits
+  the dependency checks once the pod is live, so a transient Redis hiccup
+  doesn't restart the app.
+
+The same `providers[]=none` trick works for a manual basic check:
+
+```bash
+curl '/healthz?providers[]=none' -H 'Accept: application/json'
+```
+
+The per-probe controller logging is silenced by default (kubelet probes hit the
+endpoint every few seconds); pass `silence_controller_log: false` to keep it.
+
+## Metrics exposed on `/metrics`
+
+- **Puma:** `puma_workers`, `puma_running`, `puma_pool_capacity`,
+  `puma_max_threads`, `puma_backlog`, `puma_busy_threads`,
+  `puma_requests_count`, …
+- **Sidekiq (per-process):** `sidekiq_jobs_executed_total`,
+  `sidekiq_jobs_success_total`, `sidekiq_jobs_failed_total`,
+  `sidekiq_job_runtime_seconds`, `sidekiq_job_latency_seconds`,
+  `sidekiq_running_job_runtime_seconds`, …
+- **Sidekiq (global/Redis-wide):** `sidekiq_jobs_waiting_count`,
+  `sidekiq_queue_latency`, `sidekiq_active_processes`,
+  `sidekiq_active_workers_count`, `sidekiq_jobs_retry_count`,
+  `sidekiq_jobs_dead_count`, `sidekiq_jobs_scheduled_count`.
+
+Series are intentionally **untagged**: a scraping agent adds
+`service`/`env`/`version` and `kube_*` tags at scrape time, so the gem doesn't
+duplicate them.
+
+## Datadog naming — the canonical metric set
+
+The gem emits the **untagged native Prometheus names** above (`puma_running`,
+`sidekiq_queue_latency`, …). To get a clean, **org-shared** metric set every
+adopter must use the **same Datadog OpenMetrics check config**, so all series
+differ only by `service` / `env` (+ the `kube_*`/`host`/`pid` tags the Agent adds
+at scrape time) and dashboards/monitors are reusable across projects.
+
+The check `namespace` prepends `puma.` / `sidekiq.`; left alone that would
+**double-prefix** the native names (`puma.puma_running`). `raw_metric_prefix`
+strips the redundant native segment *before* the namespace is applied, so series
+land under the canonical `puma.<name>` / `sidekiq.<name>`:
+
+```yaml
+# Puma (web pod) — :9394/metrics
+instances:
+  - openmetrics_endpoint: "http://%%host%%:9394/metrics"
+    namespace: "puma"
+    raw_metric_prefix: "puma_"      # puma_running -> puma.running
+    metrics: [".*"]
+    tag_by_endpoint: false
+
+# Sidekiq (worker pod + dedicated global exporter) — :9394/metrics
+instances:
+  - openmetrics_endpoint: "http://%%host%%:9394/metrics"
+    namespace: "sidekiq"
+    raw_metric_prefix: "sidekiq_"   # sidekiq_queue_latency -> sidekiq.queue_latency
+    metrics: [".*"]
+    tag_by_endpoint: false
+```
+
+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
+
+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:
+
+- the gem registers only the `:puma` and `:sidekiq` 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.
+
+> ⚠️ Renaming the namespace prefix is a **breaking metric rename** — existing
+> dashboards/monitors built on the old `puma.puma_*` / `sidekiq.sidekiq_*` series
+> must be migrated.
+
+### Canonical catalog
+
+Functional (non-technical) tags only; `service`/`env`/`kube_*`/`pid`/… are added
+by the Agent. `index` = Puma worker index (`0` in single-mode); `worker` = the
+Sidekiq job class.
+
+**Puma** (web pod, `namespace: puma`):
+
+| canonical Datadog metric | functional tags |
+|---|---|
+| `puma.running` | `index` |
+| `puma.backlog` | `index` |
+| `puma.busy_threads` | `index` |
+| `puma.pool_capacity` | `index` |
+| `puma.max_threads` | `index` |
+| `puma.requests_count` | `index` |
+
+**Sidekiq — global / Redis-wide** (dedicated global-exporter pod, `namespace: sidekiq`):
+
+| canonical Datadog metric | functional tags |
+|---|---|
+| `sidekiq.jobs_waiting_count` | `queue` |
+| `sidekiq.queue_latency` | `queue` |
+| `sidekiq.jobs_scheduled_count` | — |
+| `sidekiq.jobs_retry_count` | — (`queue` if `retries_segmented_by_queue`) |
+| `sidekiq.jobs_dead_count` | — |
+| `sidekiq.active_processes` | — |
+| `sidekiq.active_workers_count` | — |
+
+**Sidekiq — per-process / job** (worker pod, `namespace: sidekiq`; emitted on job activity):
+
+| canonical Datadog metric | type | functional tags |
+|---|---|---|
+| `sidekiq.jobs_executed_total` | counter | `queue`, `worker` |
+| `sidekiq.jobs_success_total` | counter | `queue`, `worker` |
+| `sidekiq.jobs_failed_total` | counter | `queue`, `worker` |
+| `sidekiq.jobs_enqueued_total` | counter | `queue`, `worker` |
+| `sidekiq.jobs_rerouted_total` | counter | `from_queue`, `to_queue`, `worker` |
+| `sidekiq.running_job_runtime` | gauge | `queue`, `worker` |
+| `sidekiq.job_runtime` | histogram | `queue`, `worker` |
+| `sidekiq.job_latency` | histogram | `queue`, `worker` |
+
+### Where Sidekiq global metrics come from
+
+The global (Redis-wide) queue gauges — `sidekiq_jobs_waiting_count`,
+`sidekiq_queue_latency`, … — are read from Redis and are identical regardless of
+which process reads them. The default **`:web`** policy collects them only in the
+always-on **web** process (which already has the Sidekiq client / Redis access),
+so there's a **single source and no per-worker duplication**: workers export only
+their own per-process job metrics. Workers can scale (even to zero) without
+losing the queue metrics.
+
+Alternatives via `c.sidekiq_global_metrics`:
+
+- **`:all`** — every worker pod exports the global gauges (the legacy behaviour).
+  Datadog then has one series **per pod**, so aggregate in dashboards/monitors
+  with `max:sidekiq.queue_latency{*} by {queue}` (Datadog space aggregation —
+  never `sum`, which would multiply by pod count).
+- **`:off`** — neither web nor workers collect them. Use this with a **dedicated
+  exporter** (below) so the gauges still come from somewhere — exactly once.
+
+> Under `:web`, if the web Deployment runs more than one replica the gauges are
+> duplicated across those (few, stable) web pods — apply the same
+> `max:… by {queue}` aggregation, or use the dedicated exporter for one series.
+
+### Dedicated global-metrics exporter (recommended for multi-replica / KEDA)
+
+When the web and worker pods are autoscaled (e.g. KEDA, possibly to zero), the
+cleanest single source for the Redis-wide queue gauges is a **dedicated 1-replica
+Deployment** that does nothing but read them from Redis and expose them. It is
+decoupled from web/worker scaling and yields exactly **one series** per gauge.
+
+Set `c.sidekiq_global_metrics = :off` (so web/workers don't collect them), then
+run a 1-replica Deployment with a thin, **host-owned** entrypoint — the gem
+deliberately ships no executable, so the Redis connection config stays with the
+host. E.g. `bin/pod-exporter`:
+
+```ruby
+#!/usr/bin/env ruby
+# bundler/setup only wires the $LOAD_PATH from the lockfile — nothing is
+# required beyond the lines below, so the process stays tiny.
+require 'bundler/setup'
+require 'rails_pod_kit/global_exporter'
+
+RailsPodKit::GlobalExporter.run!(redis: { url: ENV['REDIS_URL'] })
+```
+
+```
+command: ["bin/pod-exporter"]
+```
+
+The entrypoint is deliberately **Rails-free**: `run!` only wires the Sidekiq
+client's Redis connection from the injected options plus the yabeda stack,
+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.
+
+## Caveats
+
+- **Puma only.** The Puma plugins only activate under Puma; under any other
+  app server the in-process `/metrics` endpoint is **not** exposed.
+- **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).
+- **Rack version.** Under **Rack 3+** the mmap exporter's WEBrick handler also
+  needs the `rackup` gem. Under Rack 2.x `webrick` alone is enough, but on
+  Ruby ≥ 3.5 make sure `ostruct` is in the bundle (Rack 2.2 requires it
+  without declaring it, and it's no longer a default gem).
+- **Two kinds of entry point.** The main file (`require 'rails_pod_kit'`,
+  what Bundler.require loads in a Rails app) pulls in every integration
+  unconditionally — including the health-monitor-rails engine and its
+  railties foundation — regardless of Gemfile declaration order. The
+  sub-entry points (`rails_pod_kit/puma`, `rails_pod_kit/global_exporter`)
+  require only the config core, so the Rails-free exporter stays
+  railties-free and a `puma -C config/puma.rb` boot (which evaluates
+  `config/puma.rb` before Rails) still gets the integrations once
+  `Bundler.require` runs.
+
+## Local verification
+
+Boot each process with the exporter enabled and scrape `:9394/metrics`:
+
+```bash
+# Web (Puma): puma_* series
+bundle exec rails server
+curl -s localhost:9394/metrics | grep '^puma_'
+
+# Worker (Sidekiq): sidekiq_* series (run a job first so per-process counters appear)
+bundle exec sidekiq
+curl -s localhost:9394/metrics | grep '^sidekiq_'
+
+# Health endpoint
+curl -s localhost:3000/healthz -H 'Accept: application/json'
+```
+
+## Tests
+
+The gem's specs run in isolation (they do not load a host Rails app):
+
+```bash
+bundle install
+bundle exec rspec
+```
+
+The suite runs against a matrix of Rails/Rack versions via
+[Appraisal](https://github.com/thoughtbot/appraisal):
+
+```bash
+bundle exec appraisal install
+bundle exec appraisal rails-8.1 rspec
+```
+
+## License
+
+Released under the [MIT License](LICENSE.txt).

data/VERSION

@@ -0,0 +1 @@
+0.0.1

data/lib/rails_pod_kit/config.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require 'anyway_config'
+
+require 'rails_pod_kit/version'
+
+# Configuration core, shared by every entry point. The sub-entry points
+# (rails_pod_kit/puma, rails_pod_kit/global_exporter, …) require this file —
+# not the gem's main file — so they can run in Rails-free processes without
+# pulling in railties.
+module RailsPodKit
+  class Error < StandardError; end
+
+  DEFAULT_PORT = 9394
+
+  # Backed by anyway_config: every attribute can also come from RAILS_POD_KIT_*
+  # env vars or an optional config/rails_pod_kit.yml in the host, with the
+  # `RailsPodKit.configure` block (running last, from an initializer) winning
+  # over both. A single instance is memoized on the module.
+  class Config < Anyway::Config
+    config_name :rails_pod_kit
+    env_prefix 'RAILS_POD_KIT'
+
+    # enabled: master switch — when false the gem is a complete no-op: no
+    #   exporter server is started and no port is bound. Defaults to off in the
+    #   `test` environment so specs and CI never try to bind port 9394.
+    #
+    # port: TCP port the in-process exporter binds for both Puma and Sidekiq.
+    #   Defaults to PROMETHEUS_EXPORTER_PORT (the yabeda-native env var) or 9394.
+    #
+    # sidekiq_global_metrics: policy for Sidekiq global (Redis-wide) queue
+    #   metrics — queue latency, jobs waiting, etc. These are read from Redis
+    #   and are identical across processes, so exporting them from every worker
+    #   just duplicates series downstream.
+    #     :web (default) -> collect them only in the always-on web (Puma)
+    #                       process; workers export only their per-process job
+    #                       metrics. One source, no per-worker duplication.
+    #     :all           -> every worker pod exports them (legacy). Aggregate
+    #                       with `max ... by {queue}` downstream, never `sum`.
+    #     :off           -> nobody collects them (per-process metrics
+    #                       unaffected). Pair with the dedicated global exporter
+    #                       (GlobalExporter) so the gauges still come from
+    #                       somewhere — exactly once.
+    #
+    # puma_control_url: Puma control-app URL. yabeda-puma-plugin reads the Puma
+    #   thread-pool stats through the control app, so `Puma.activate` makes sure
+    #   one is running. Defaults to PUMA_CONTROL_URL or a localhost-only TCP
+    #   socket (not network-exposed in the pod).
+    #
+    # retries_segmented_by_queue: when true, the Sidekiq global retry gauge
+    #   (`sidekiq_jobs_retry_count`) is broken down with a `queue` tag instead
+    #   of a single global scalar. Maps to yabeda-sidekiq's setting of the same
+    #   name. Off by default: per-queue retries multiply series cardinality, and
+    #   the global scalar is enough for a failing-jobs anomaly monitor.
+    #
+    # silence_exporter_access_log: when true (default), the in-process /metrics
+    #   exporter emits NO access log line per scrape. The endpoint is
+    #   pod-internal and scraped on a fixed interval by the metrics agent, so a
+    #   `GET /metrics` line per scrape per pod is pure noise. Silenced at both
+    #   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.
+    attr_config :enabled,
+                :port,
+                :puma_control_url,
+                sidekiq_global_metrics: :web,
+                retries_segmented_by_queue: false,
+                silence_exporter_access_log: true
+
+    coerce_types port: :integer,
+                 enabled: :boolean,
+                 retries_segmented_by_queue: :boolean,
+                 silence_exporter_access_log: :boolean
+
+    def initialize(overrides = nil)
+      super
+
+      # Env/YAML sources deliver the policy as a string; the API is symbols.
+      self.sidekiq_global_metrics = sidekiq_global_metrics.to_sym if sidekiq_global_metrics
+      # Dynamic defaults anyway_config can't express statically.
+      self.enabled = self.class.default_enabled? if enabled.nil?
+      self.port ||= Integer(ENV.fetch('PROMETHEUS_EXPORTER_PORT', DEFAULT_PORT))
+      self.puma_control_url ||= ENV.fetch('PUMA_CONTROL_URL', 'tcp://127.0.0.1:9293')
+    end
+
+    def enabled?
+      !!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.
+    def self.default_enabled?
+      env = ENV['RAILS_ENV'] || ENV['RACK_ENV']
+      env != 'test'
+    end
+  end
+
+  class << self
+    def config
+      @config ||= Config.new
+    end
+
+    def configure
+      yield config if block_given?
+      config
+    end
+
+    # Test/reset hook — drops the memoized config so a fresh one is built.
+    def reset_config!
+      @config = nil
+    end
+
+    def enabled?
+      config.enabled?
+    end
+  end
+end

data/lib/rails_pod_kit/global_exporter.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require 'rails_pod_kit/config'
+
+module RailsPodKit
+  # Standalone, always-on exporter for the Sidekiq global (Redis-wide) queue
+  # metrics (queue latency, jobs waiting, scheduled/retry/dead counts, …).
+  #
+  # Runs as its own 1-replica Deployment so those series come from a single
+  # source, fully decoupled from web/worker autoscaling: KEDA can scale the web
+  # and worker pods (even to zero) without the queue metrics disappearing or
+  # being duplicated per pod. It is NOT a Sidekiq server and serves no web
+  # traffic — it just reads the cluster stats from Redis and exposes them on the
+  # exporter port.
+  #
+  # Deliberately Rails-free. The whole job is reading a handful of counters from
+  # Redis, so booting the host app (every gem, every initializer) just to
+  # inherit the connection config would cost hundreds of Mi RSS for nothing.
+  # Instead the host injects its Redis options into `run!`, which configures the
+  # Sidekiq client itself — the process sits at ~60Mi.
+  #
+  # Entry point: a thin, host-owned executable (the gem ships none, so the host
+  # keeps full ownership of its connection config), e.g. `bin/pod-exporter`:
+  #
+  #   #!/usr/bin/env ruby
+  #   require 'bundler/setup'
+  #   require 'rails_pod_kit/global_exporter'
+  #   RailsPodKit::GlobalExporter.run!(redis: { url: ENV['REDIS_URL'] })
+  module GlobalExporter
+    module_function
+
+    # Force-enable cluster collection so yabeda declares the global gauges when
+    # it configures. Force-on regardless of the host's `sidekiq_global_metrics`
+    # policy — collecting them is this process's whole job; the web/worker pods
+    # stay :off so they don't duplicate it.
+    def install!
+      require 'rails_pod_kit/sidekiq'
+      require 'yabeda/prometheus/mmap'
+      RailsPodKit::Sidekiq.enable_global_collection!
+    end
+
+    # Boots the exporter and blocks. Self-sufficient: no Rails environment is
+    # required — it wires the Sidekiq client's Redis connection from the
+    # host-injected options, declares and configures the gauges, starts the
+    # metrics server, then sleeps.
+    #
+    # `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
+
+      configure_redis!(redis)
+      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
+    # can read the cluster stats.
+    def configure_redis!(redis_options)
+      require 'sidekiq'
+      ::Sidekiq.configure_client do |config|
+        config.redis = redis_options
+      end
+    end
+  end
+end

data/lib/rails_pod_kit/health.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require 'rails_pod_kit/config'
+
+# health-monitor-rails subclasses ::Rails::Engine and its provider registry
+# leans on ActiveSupport core extensions without requiring either itself;
+# `rails` (railties' entry file, not the full framework) sets both up in the
+# right order.
+require 'rails'
+require 'active_support/core_ext/string'
+require 'rails/engine'
+require 'health-monitor-rails'
+
+module RailsPodKit
+  # Opinionated health-monitor-rails configuration for a Rails pod's probe
+  # endpoint. One call from an initializer:
+  #
+  #   RailsPodKit::Health.install!(
+  #     redis:   { url: ENV['REDIS_URL'] },
+  #     sidekiq: { queue_size: 200, latency: 10.minutes }
+  #   )
+  #
+  # gives the app a /healthz endpoint checking database (health_monitor's
+  # default), cache, Redis and (optionally) Sidekiq — suitable as a k8s startup
+  # probe. For liveness/readiness, probe `/healthz?providers[]=none` to
+  # short-circuit the dependency checks once the pod is live, so a transient
+  # Redis hiccup doesn't restart the app. Same trick for a manual basic check:
+  #
+  #   curl '/healthz?providers[]=none' -H 'Accept: application/json'
+  #
+  # The Redis connection is injected by the host — the gem never reads
+  # REDIS_URL or makes TLS decisions.
+  module Health
+    module_function
+
+    # Configures HealthMonitor with the kit's defaults.
+    #
+    # redis:   Redis connection options hash (same shape the host passes to
+    #          Sidekiq) or a ready connection object (Redis / ConnectionPool).
+    # path:    mount-relative endpoint path (default :healthz).
+    # sidekiq: optional thresholds hash; when given the Sidekiq provider is
+    #          added with the provided `queue_size:` / `latency:` overrides
+    #          (health_monitor defaults apply for missing keys). Omit entirely
+    #          on hosts without Sidekiq.
+    # silence_controller_log: drop the per-probe INFO request logging (default
+    #          true) — kubelet probes hit the endpoint every few seconds and
+    #          would drown real request logs.
+    # mount:   when true (default) the gem's Railtie mounts
+    #          HealthMonitor::Engine at '/' automatically; pass false to keep
+    #          route ownership and mount it yourself in config/routes.rb.
+    #
+    # Any further host-specific tuning (extra providers, error callback, …) can
+    # be done in the block, which receives the HealthMonitor configuration.
+    def install!(redis:, path: :healthz, sidekiq: nil, silence_controller_log: true, mount: true)
+      @auto_mount = mount
+
+      HealthMonitor.configure do |config|
+        config.path = path
+        config.cache
+        config.redis.configure do |redis_config|
+          redis_config.connection = build_connection(redis)
+        end
+
+        if sidekiq
+          config.sidekiq.configure do |sidekiq_config|
+            sidekiq_config.queue_size = sidekiq[:queue_size] if sidekiq[:queue_size]
+            sidekiq_config.latency    = sidekiq[:latency]    if sidekiq[:latency]
+          end
+        end
+
+        yield config if block_given?
+      end
+
+      silence_controller_log! if silence_controller_log
+    end
+
+    # Read by the Railtie's deferred routes block: true only once install! ran
+    # (initializers run before the route set is drawn) and mount wasn't opted
+    # out.
+    def auto_mount?
+      !!@auto_mount
+    end
+
+    def build_connection(redis)
+      return redis unless redis.is_a?(Hash)
+
+      require 'redis'
+      ::Redis.new(**redis)
+    end
+
+    # Quiet the engine controller so kubelet probes don't emit an INFO line per
+    # hit. Deferred to to_prepare because the engine controller is autoloaded.
+    def silence_controller_log!
+      return unless defined?(Rails.application) && Rails.application
+
+      Rails.application.reloader.to_prepare do
+        HealthMonitor::HealthController.logger.level = :warn
+      end
+    end
+  end
+end

data/lib/rails_pod_kit/puma.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require 'rails_pod_kit/config'
+
+module RailsPodKit
+  # Puma integration. Encapsulates the Puma plugins the yabeda stack needs so
+  # that `config/puma.rb` stays a one-liner:
+  #
+  #   require 'rails_pod_kit/puma'
+  #   RailsPodKit::Puma.activate(self)
+  #
+  # - control app             yabeda-puma-plugin reads the Puma thread-pool
+  #                           stats through Puma's control app, so we activate
+  #                           one (localhost-only, no token) if the app hasn't.
+  # - `plugin :yabeda`        (yabeda-puma-plugin) registers a Yabeda collector
+  #                           for Puma thread-pool / worker stats.
+  # - `plugin :yabeda_prometheus` (yabeda-puma-plugin) starts the in-process
+  #                           HTTP server that serves /metrics, fork-safe under
+  #                           `preload_app!` + clustered workers.
+  #
+  # No-op when disabled or in the test env so the suite never binds the port.
+  module Puma
+    module_function
+
+    def activate(puma_config)
+      return unless RailsPodKit.enabled?
+
+      ENV['PROMETHEUS_EXPORTER_PORT'] ||= RailsPodKit.config.port.to_s
+
+      # The Puma plugin only pulls in the exporter class; we must also load the
+      # full mmap module so `Yabeda::Prometheus::Mmap.registry` exists and the
+      # mmap adapter is registered (it's a transitive dep, so Bundler.require in
+      # the host app doesn't auto-require it).
+      require 'yabeda/prometheus/mmap'
+
+      # The control app exposes Puma's /stats over a localhost-only socket that
+      # the yabeda collector queries. `no_token: true` is safe because the
+      # socket is never exposed outside the pod.
+      puma_config.activate_control_app(RailsPodKit.config.puma_control_url, no_token: true)
+
+      puma_config.plugin :yabeda
+      puma_config.plugin :yabeda_prometheus
+
+      # Silence the exporter's per-scrape access log. The `prometheus_silence_logger`
+      # DSL method is defined by the :yabeda_prometheus plugin, so this must run
+      # after the plugin is loaded above. See Config#silence_exporter_access_log.
+      puma_config.prometheus_silence_logger(true) if RailsPodKit.config.silence_exporter_access_log
+
+      # `config/puma.rb` is evaluated before Rails is loaded, so requiring this
+      # gem here loads yabeda *before* `defined?(Rails)`, and yabeda's Railtie
+      # (which would call `Yabeda.configure!` at after_initialize) never
+      # registers. So we drive configuration ourselves from the exporter-boot
+      # hook, which runs after Rails has booted and after the Puma plugin has
+      # registered its collector.
+      puma_config.on_prometheus_exporter_boot do
+        # Under the :web policy the always-on web process is the single source of
+        # Sidekiq global (Redis-wide) queue metrics, so workers don't duplicate
+        # them. Done here (not in activate) because requiring yabeda-sidekiq —
+        # which pulls in Sidekiq — before Rails boots corrupts Sidekiq's
+        # ActiveJob adapter load order. By exporter-boot, Rails has loaded
+        # Sidekiq properly and the web's Sidekiq client (Redis) is configured.
+        if RailsPodKit.config.sidekiq_global_metrics == :web
+          require 'rails_pod_kit/sidekiq'
+          RailsPodKit::Sidekiq.enable_global_collection!
+        end
+
+        require 'yabeda'
+        Yabeda.configure! unless Yabeda.already_configured?
+      end
+    end
+  end
+end

data/lib/rails_pod_kit/railtie.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'rails_pod_kit/config'
+
+require 'rails'
+require 'rails/railtie'
+
+module RailsPodKit
+  # Mounts the health endpoint automatically so the host doesn't have to touch
+  # config/routes.rb. The append block is evaluated when the route set is
+  # drawn (and on every reload) — after the initializers have run — so the
+  # guard sees whether Health.install! was called and with which `mount:`
+  # option. Hosts that want route ownership (custom mount point, constraints)
+  # pass `mount: false` to install! and mount HealthMonitor::Engine themselves.
+  class Railtie < ::Rails::Railtie
+    initializer 'rails_pod_kit.mount_health_endpoint' do |app|
+      app.routes.append do
+        mount HealthMonitor::Engine, at: '/' if RailsPodKit::Health.auto_mount?
+      end
+    end
+  end
+end

data/lib/rails_pod_kit/sidekiq.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require 'rails_pod_kit/config'
+
+module RailsPodKit
+  # Sidekiq integration. Called from inside `Sidekiq.configure_server`:
+  #
+  #   RailsPodKit::Sidekiq.install!(config)
+  #
+  # It:
+  #   - requires yabeda-sidekiq (registers the server middleware + metrics),
+  #   - applies the global-metrics policy (see Config#sidekiq_global_metrics),
+  #   - starts the in-process Prometheus exporter (WEBrick) bound to the
+  #     configured port so the worker pod serves /metrics itself.
+  #
+  # No-op when disabled or in the test env so specs never bind the port.
+  module Sidekiq
+    module_function
+
+    def install!(sidekiq_config = nil)
+      return unless RailsPodKit.enabled?
+
+      require 'yabeda/sidekiq'
+      require 'yabeda/prometheus/mmap'
+
+      # Must run before Yabeda.configure! so the cluster-metric gauges are gated
+      # correctly (they are only declared when the policy leaves them enabled).
+      apply_global_metrics_policy!
+
+      # We can't rely on yabeda's Railtie to call Yabeda.configure!: depending on
+      # boot order it may never register. Drive it from Sidekiq's :startup
+      # lifecycle event, which fires after every initializer (so the sidekiq
+      # collector is registered) but before any job runs.
+      install_configure_hook(sidekiq_config)
+
+      start_metrics_server!
+    end
+
+    # Registers the Yabeda.configure! driver on Sidekiq's :startup event. The
+    # real app always passes a Sidekiq config that responds to :on; when it
+    # doesn't (e.g. unit specs that pass nil) we skip, so the global Yabeda
+    # singleton isn't configured as a test side effect.
+    def install_configure_hook(sidekiq_config)
+      return unless sidekiq_config.respond_to?(:on)
+
+      sidekiq_config.on(:startup) do
+        require 'yabeda'
+        Yabeda.configure! unless Yabeda.already_configured?
+      end
+    end
+
+    # Decide whether this Sidekiq worker collects the global (Redis-wide) queue
+    # metrics. Only the :all policy keeps every worker collecting them; under
+    # :web they come from the web process instead, and under :off nobody does.
+    # Either way per-process job metrics are unaffected.
+    def apply_global_metrics_policy!
+      collect = RailsPodKit.config.sidekiq_global_metrics == :all
+      Yabeda::Sidekiq.config.collect_cluster_metrics = collect
+      apply_retries_segmentation!
+    end
+
+    # Mirror the gem's `retries_segmented_by_queue` flag onto yabeda-sidekiq. Must
+    # run before Yabeda.configure! so the retry gauge is declared with (or without)
+    # the `queue` tag. Off by default — see RailsPodKit::Config.
+    def apply_retries_segmentation!
+      Yabeda::Sidekiq.config.retries_segmented_by_queue =
+        RailsPodKit.config.retries_segmented_by_queue
+    end
+
+    # Enables global queue-metric collection in a process that is NOT a Sidekiq
+    # server — i.e. the web (Puma) process under the :web policy. The web has the
+    # Sidekiq client configured (Redis access), so yabeda-sidekiq can read the
+    # cluster stats there. We force `collect_cluster_metrics` on and keep
+    # `declare_process_metrics` off (the web runs no jobs). Must run before
+    # Yabeda.configure! so the gauges are declared.
+    def enable_global_collection!
+      require 'yabeda/sidekiq'
+
+      Yabeda::Sidekiq.config.collect_cluster_metrics = true
+      Yabeda::Sidekiq.config.declare_process_metrics = false
+      apply_retries_segmentation!
+    end
+
+    # Starts the background WEBrick exporter. `start_metrics_server!` reads the
+    # bind port from PROMETHEUS_EXPORTER_PORT, so we set it from config first.
+    # Guarded so a re-entrant Sidekiq boot doesn't try to double-bind the port.
+    def start_metrics_server!
+      return if @server_started
+
+      ENV['PROMETHEUS_EXPORTER_PORT'] ||= RailsPodKit.config.port.to_s
+      # Drop the WEBrick 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!
+      @server_started = true
+    end
+  end
+end

data/lib/rails_pod_kit/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RailsPodKit
+  VERSION = File.read(File.expand_path('../../VERSION', __dir__)).chomp.freeze
+end

data/lib/rails_pod_kit.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'rails_pod_kit/version'
+require 'rails_pod_kit/config'
+
+# RailsPodKit packages the operational endpoints a Rails pod needs to be a good
+# Kubernetes citizen behind a single, opinionated entry point:
+#
+# - Prometheus metrics: Puma and Sidekiq runtime metrics in Prometheus text
+#   format on an in-process /metrics endpoint (default port 9394) — no sidecar,
+#   no separate collector process. A thin wrapper around the yabeda ecosystem.
+# - Health checks: an opinionated health-monitor-rails configuration serving
+#   liveness/readiness/startup probes on /healthz (see RailsPodKit::Health),
+#   auto-mounted by the gem's Railtie.
+#
+# Metric series are intentionally left untagged here: a scraping agent (e.g.
+# the Datadog Agent) adds service/env/version and kube_* tags at scrape time,
+# so the gem doesn't duplicate them.
+#
+# Wiring (see README) is three one-liners:
+#   - config/puma.rb                          -> RailsPodKit::Puma.activate(self)
+#   - config/initializers/sidekiq.rb          -> RailsPodKit::Sidekiq.install!(config)
+#   - config/initializers/rails_pod_kit.rb    -> RailsPodKit.configure { ... }
+#                                                RailsPodKit::Health.install!(redis: ...)
+# plus, only when running the dedicated global exporter, a host-owned
+# entrypoint (e.g. bin/pod-exporter) calling GlobalExporter.run!(redis: ...).
+#
+# The gem is deliberately connection-agnostic: it never reads REDIS_URL or
+# makes TLS decisions. The host injects its Redis options where needed
+# (GlobalExporter.run!, Health.install!).
+
+# This is the Rails-app entry point: it loads every integration
+# unconditionally (each file requires what it needs, so nothing here depends
+# on Gemfile declaration order or on which constants happen to be defined
+# yet). The Sidekiq integration is inert until install! is called and pulls in
+# yabeda-sidekiq only then; health + railtie load the health-monitor-rails
+# engine and railties.
+#
+# The sub-entry points deliberately require only rails_pod_kit/config instead
+# of this file, with two effects:
+#   - a Rails-free process (bin/pod-exporter requiring
+#     rails_pod_kit/global_exporter) never pulls in railties or Sidekiq;
+#   - under `puma -C config/puma.rb` — where Puma evaluates config/puma.rb
+#     (and thus rails_pod_kit/puma) before Rails exists — this file is still
+#     fresh for Bundler.require, so the integrations load once Rails is up.
+require 'rails_pod_kit/sidekiq'
+require 'rails_pod_kit/health'
+require 'rails_pod_kit/railtie'

metadata

@@ -0,0 +1,172 @@
+--- !ruby/object:Gem::Specification
+name: rails_pod_kit
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Fabio Napoleoni
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: yabeda
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.16'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.16'
+- !ruby/object:Gem::Dependency
+  name: yabeda-sidekiq
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.12'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.12'
+- !ruby/object:Gem::Dependency
+  name: yabeda-puma-plugin
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: yabeda-prometheus-mmap
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+- !ruby/object:Gem::Dependency
+  name: webrick
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+- !ruby/object:Gem::Dependency
+  name: anyway_config
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: health-monitor-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '12.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '12.8'
+- !ruby/object:Gem::Dependency
+  name: redis
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: |
+  Packages the yabeda ecosystem and health-monitor-rails into a single,
+  opinionated kit for running Rails applications on Kubernetes: Puma and
+  Sidekiq runtime metrics in Prometheus text format on an in-process /metrics
+  endpoint (default port 9394), plus a /healthz endpoint wired for
+  liveness/readiness/startup probes. No sidecar, no separate collector.
+email:
+- f.napoleoni@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- VERSION
+- lib/rails_pod_kit.rb
+- lib/rails_pod_kit/config.rb
+- lib/rails_pod_kit/global_exporter.rb
+- lib/rails_pod_kit/health.rb
+- lib/rails_pod_kit/puma.rb
+- lib/rails_pod_kit/railtie.rb
+- lib/rails_pod_kit/sidekiq.rb
+- lib/rails_pod_kit/version.rb
+homepage: https://github.com/fabn/rails_pod_kit
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/fabn/rails_pod_kit
+  changelog_uri: https://github.com/fabn/rails_pod_kit/releases
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: 'Operational endpoints for Rails pods: Prometheus metrics (Puma + Sidekiq)
+  and health checks'
+test_files: []