solid_queue_guard 1.1.4 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 45e502d91550c641928112f20c22aa917b5c9b4e8c315730503aa6d5e2f10532
-  data.tar.gz: bff2f2dd6c6fce14ead0b7f43a97635c6184abb5c6585a07673fcf502771f2ab
+  metadata.gz: 4ab3926371f9714622f421164d1436dcc74b17eb0d311627fff319c74a9369be
+  data.tar.gz: 13bd4acab34e3a6757bd5a4c445e471ab3021fc88d0748ca95a89a92cc597804
 SHA512:
-  metadata.gz: 942e9c4f60fe1eb30dd9a00fa4bb38e150c5fd964dac066429b1f805c448e470d12520da606218a4a163aa44f8cf52176f60b44de25a899e8e900530aee165d1
-  data.tar.gz: 539c14d133e1fa5d02d1407e3b951ca2565382f16a36dba34a895ee7ff44b5e7d0ee80165c0d91b0a2bf5c1ee50a3691429b1619f5a0f8e8949804378fec8526
+  metadata.gz: 02d75b6056ddd2f698441b892c16d29f4155a0d213d598c5b0f813d0094529b32a761461071ca302cf170c2d1acfbd0e39339e2818b260261c006ba11ad73581
+  data.tar.gz: 9e57de7cf88e4ab6ef5d5ded2b98cd15c09374f0a46ecc311fadbe02d2952f4097fef99025848454b0734af35ed734b61f7f54093df255ad27c9c8ff5cf15f1a

data/CHANGELOG.md

@@ -5,6 +5,27 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.0] - 2026-07-10
+
+### Added
+
+- `config.validate!` at boot — rejects invalid HTTP status codes, thresholds, and `on_status_change` types
+- `config.on_status_change` callback when `/solid_queue_guard/health` detects a status transition
+- Structured logging per check result (debug for pass/skip, warn/error for warn/fail)
+- `status_counts` in report and health JSON payload
+- Per-check metrics for StatsD, Prometheus, and OpenTelemetry exporters
+- `SolidQueueGuard::Checks::Registry.catalog` for listing check IDs
+- `bin/console` for dummy app debugging
+- `CONTRIBUTING.md`, `docs/configuration.md`, and `docs/checks.md`
+- CI: Ruby 3.1 matrix, dedicated Appraisal job, and `gem build` verification
+- Mission Control navigation integration test from recurring tasks page
+
+### Changed
+
+- README trimmed with links to dedicated docs
+- Mission Control screenshot shipped in gem package for RubyGems README rendering
+- OpenTelemetry exporter requires `opentelemetry-sdk` with clear log when missing
+
 ## [1.1.4] - 2026-07-10
 
 ### Fixed

data/CONTRIBUTING.md

@@ -0,0 +1,57 @@
+# Contributing
+
+Issues and PRs welcome. Keep changes focused on **production safety**, not another job dashboard.
+
+## Setup
+
+```bash
+git clone https://github.com/rafael-pissardo/solid_queue_guard.git
+cd solid_queue_guard
+bundle install
+cd test/dummy && bin/setup
+cd ../..
+bundle exec rake test
+bundle exec rubocop
+bundle exec appraisal install
+bundle exec appraisal rake test
+```
+
+Interactive console against the dummy app:
+
+```bash
+bin/console
+```
+
+## Adding a check
+
+1. Create `lib/solid_queue_guard/checks/config/my_check.rb` or `checks/runtime/my_check.rb`
+2. Register it in `lib/solid_queue_guard/checks/registry.rb`
+3. Add tests under `test/solid_queue_guard/checks/`
+4. Document the check ID in [docs/checks.md](docs/checks.md)
+
+Check IDs are derived from the class name (`MyFeatureCheck` → `my_feature`).
+
+## Testing against Revelo-style apps
+
+Use `script/validate_revelo.sh` to run the doctor and health tasks against local Revelo backends with a path gem:
+
+```bash
+./script/validate_revelo.sh
+```
+
+Edit the script to point at your checkout paths. The script temporarily adds a `path:` gem line, runs `solid_queue_guard:doctor` and `solid_queue_guard:health`, then restores the Gemfile.
+
+## Release checklist
+
+- [ ] Tests pass locally and in CI (matrix + Appraisal + `gem build`)
+- [ ] RuboCop clean
+- [ ] CHANGELOG updated
+- [ ] Version bumped in `lib/solid_queue_guard/version.rb` and lockfiles synced
+- [ ] README / docs updated for public API changes
+- [ ] Tag matches gem version: `git tag vX.Y.Z && git push origin vX.Y.Z`
+
+## Code style
+
+- Follow existing patterns: small checks, `Check::Result`, registry-driven runner
+- Mark internal APIs with `# @api private`
+- Public API changes require semver discipline (see README)

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    solid_queue_guard (1.1.4)
+    solid_queue_guard (1.2.0)
       actionpack (>= 7.1, < 9.0)
       activejob (>= 7.1, < 9.0)
       activerecord (>= 7.1, < 9.0)

data/README.md

@@ -15,18 +15,16 @@
 
 <p align="center">
   <a href="#-quick-start"><strong>Quick start</strong></a> ·
-  <a href="#-see-it-in-action"><strong>Demo output</strong></a> ·
-  <a href="#-mission-control-dashboard-opt-in"><strong>Mission Control tab</strong></a> ·
-  <a href="#-solid_queue_guard-vs-mission-control"><strong>vs Mission Control</strong></a>
+  <a href="docs/checks.md"><strong>Checks</strong></a> ·
+  <a href="docs/configuration.md"><strong>Configuration</strong></a> ·
+  <a href="#-mission-control-dashboard"><strong>Mission Control</strong></a>
 </p>
 
 ---
 
 Rails 8 ships with [Solid Queue](https://github.com/rails/solid_queue). Redis is optional. **Production config is not.**
 
-Your web tier can be **green** while your jobs are **dead**. Your queue can look **empty** while scheduled work is **stuck**. Your `queue.yml` can declare **10 threads** against a database pool of **5**.
-
-**solid_queue_guard** catches that *before* it becomes an incident.
+Your web tier can be **green** while your jobs are **dead**. **solid_queue_guard** catches that *before* it becomes an incident.
 
 > **Mission Control** shows what is happening.  
 > **solid_queue_guard** warns what is dangerous.
@@ -41,49 +39,20 @@ bin/rails solid_queue_guard:doctor
 
 ---
 
-## Table of contents
-
-- [Why this exists](#why-this-exists)
-- [See it in action](#-see-it-in-action)
-- [What it checks](#what-it-checks)
-- [Quick start](#-quick-start)
-- [Mission Control dashboard](#-mission-control-dashboard-opt-in)
-- [How to use it](#how-to-use-it)
-- [Runtime process checks](#runtime-process-checks)
-- [Configuration](#configuration)
-- [Public API (v1.0+)](#public-api-v10)
-- [solid_queue_guard vs Mission Control](#-solid_queue_guard-vs-mission-control)
-- [Roadmap](#roadmap)
-- [Compatibility](#compatibility)
-- [Development](#development)
-- [Contributing](#contributing)
-
----
-
 ## Why this exists
 
-Solid Queue is excellent. Operating it blindly is not.
-
 | Symptom | What actually happened |
 | ------- | ---------------------- |
 | "Site is up, emails stopped" | Workers dead, heartbeats stale |
 | "Only 3 jobs in the queue, why the panic?" | Oldest job waiting 40 minutes — **lag**, not depth |
-| "Recurring billing just… stopped" | Scheduler not running, nobody noticed for a week |
-| "Jobs hang after deploy" | Thread count > DB pool — connection starvation |
+| "Recurring billing just… stopped" | Scheduler not running |
+| "Jobs hang after deploy" | Thread count > DB pool |
 | "Health check passes, jobs don't" | `/up` doesn't know Solid Queue exists |
 
-You don't need another dashboard. You need a **doctor**.
-
 ---
 
 ## 👨‍⚕️ See it in action
 
-```bash
-bundle add solid_queue_guard
-bin/rails solid_queue_guard:install
-bin/rails solid_queue_guard:doctor
-```
-
 ```text
 SolidQueueGuard Report
 
@@ -91,109 +60,29 @@ Status: DEGRADED
 
 Checks:
 ✅ Active Job adapter is :solid_queue
-✅ Queue database configured in database.yml
-✅ Solid Queue connects_to queue database (pool: 10)
-✅ Solid Queue schema tables present
 ❌ Worker threads: 10, queue DB pool: 5
 ⚠️ No workers configured for "mailers" queue
-⚠️ recurring.yml exists but scheduler may not run
-✅ Solid Queue is not co-located with Puma
 
 Suggested fixes:
 - Increase queue DB pool to at least 12 or reduce worker threads
-- Add a worker for the mailers queue
-- Verify scheduler process is running in production
 ```
 
 **One command. Actionable output. No Datadog required to get started.**
 
----
-
-## What it checks
-
-### Configuration doctor
-
-Runs locally, in CI, or pre-deploy. **No extra infrastructure.**
-
-| Check | Catches |
-| ----- | ------- |
-| **Adapter** | Active Job not set to `:solid_queue` |
-| **Queue database** | Missing `queue` entry in `database.yml` |
-| **connects_to** | Solid Queue pointing at the wrong DB / pool |
-| **Queue schema** | Missing Solid Queue tables in schema files or queue database |
-| **Thread pool** | `threads` > available queue DB connections |
-| **Worker coverage** | Queues with no worker assigned |
-| **Scheduler** | `recurring.yml` tasks without a scheduler |
-| **Env flags** | `SOLID_QUEUE_SKIP_RECURRING=true` in production |
-| **Heartbeats** | Default thresholds that may not fit your deploy |
-| **Puma plugin** | Solid Queue co-located with web in production |
-| **Async supervisor** | `async` mode with thread/pool sizing risks |
-| **Topology** | `queue.yml` worker and pool recommendations |
-
-### Runtime guards
-
-| Check | Catches |
-| ----- | ------- |
-| **Queue lag** | Oldest ready job waiting too long |
-| **Stale processes** | Dead workers, dispatchers, schedulers |
-| **Dispatcher health** | Scheduled jobs never becoming ready |
-| **Blocked jobs** | Concurrency control silently holding jobs |
-| **Recurring staleness** | Cron tasks that stopped firing |
-| **Puma plugin runtime** | Plugin enabled but no active Solid Queue processes |
-| **HTTP `/health`** | Kamal, ECS, K8s, UptimeRobot integration |
+Full check list: [docs/checks.md](docs/checks.md)
 
 ---
 
 ## 🚀 Quick start
 
-### Install
-
 ```bash
 bundle add solid_queue_guard
 bin/rails solid_queue_guard:install
-bin/rails generate solid_queue_guard:install:ci   # optional GitHub Actions workflow
-```
-
-### Run the doctor
-
-```bash
-# Human-readable report
 bin/rails solid_queue_guard:doctor
-
-# JSON for scripts / CI
-bin/rails "solid_queue_guard:doctor[json]"
-SOLID_QUEUE_GUARD_FORMAT=json bin/rails solid_queue_guard:doctor
-
-# Fail CI on warnings too
-SOLID_QUEUE_GUARD_STRICT=1 bin/rails solid_queue_guard:doctor
-
-# Full report (config + runtime when available)
-bin/rails solid_queue_guard:report
-```
-
-### Exit codes
-
-| Code | Meaning |
-| ---- | ------- |
-| `0` | Healthy or degraded |
-| `1` | Unhealthy (or degraded in `--strict` / `SOLID_QUEUE_GUARD_STRICT=1`) |
-
-Perfect for deploy pipelines:
-
-```yaml
-# GitHub Actions
-- name: Solid Queue production readiness
-  run: SOLID_QUEUE_GUARD_STRICT=1 bin/rails solid_queue_guard:doctor
+SOLID_QUEUE_GUARD_STRICT=1 bin/rails solid_queue_guard:doctor   # CI gate
+bin/rails solid_queue_guard:report                              # config + runtime
 ```
 
-Or generate a workflow:
-
-```bash
-bin/rails generate solid_queue_guard:install:ci
-```
-
-### HTTP health
-
 ```ruby
 # config/routes.rb
 mount SolidQueueGuard::Engine, at: "/solid_queue_guard"
@@ -201,302 +90,66 @@ mount SolidQueueGuard::Engine, at: "/solid_queue_guard"
 
 ```bash
 curl localhost:3000/solid_queue_guard/health
-# => { "status": "degraded", "queue_lag_seconds": 245, "warnings": [...] }
-```
-
-Optional token protection:
-
-```ruby
-config.health_token = ENV["SOLID_QUEUE_GUARD_TOKEN"]
-# curl -H "X-Solid-Queue-Guard-Token: $TOKEN" ...
-```
-
-HTTP status policy (for Kamal, ECS, load balancers):
-
-```ruby
-config.degraded_http_status = 207   # or :ok (200), 503, etc.
-config.unhealthy_http_status = 503  # default
-```
-
-Works with **Kamal**, **Heroku**, **Fly.io**, **ECS/Fargate**, **Kubernetes**, **Better Stack**, **UptimeRobot**.
-
----
-
-## 🛡️ Mission Control dashboard (opt-in)
-
-Add a **Guard** tab to [Mission Control — Jobs](https://github.com/rails/mission_control-jobs) — same Bulma UI, same auth, same navigation:
-
-```ruby
-# Gemfile
-gem "mission_control-jobs"
-gem "solid_queue_guard"
-
-# config/initializers/solid_queue_guard.rb
-SolidQueueGuard.configure do |config|
-  config.integrate_mission_control = true
-end
-
-# config/routes.rb
-mount MissionControl::Jobs::Engine, at: "/jobs"
-mount SolidQueueGuard::Engine, at: "/solid_queue_guard" # keep /health for probes
 ```
 
-Open `/jobs/applications/:application_id/guard` (or click the **Guard** tab inside Mission Control):
+All configuration options: [docs/configuration.md](docs/configuration.md)
 
-![Guard tab in Mission Control — overall status, metrics, warnings, and checks table](docs/mission-control-guard-dashboard.png)
-
-| Section | Content |
-| ------- | ------- |
-| **Overall status** | `healthy` / `degraded` / `unhealthy` badge |
-| **Metrics** | Queue lag, failed jobs (1h), dead processes, check count |
-| **Warnings & suggestions** | Same messages as `doctor` / `/health` |
-| **Checks table** | Every check with status tag, message, and suggestion |
-
-**Authentication:** the Guard tab inherits Mission Control auth — HTTP basic (default) or your admin controller via `MissionControl::Jobs.base_controller_class`. No separate login.
-
-**Load balancers:** keep using `GET /solid_queue_guard/health` with optional `health_token`. Probes do not go through Mission Control.
-
-**Requirements:** an asset pipeline (Propshaft or Sprockets), same as Mission Control. `mission_control-jobs` is optional — only needed when `integrate_mission_control` is enabled.
-
----
-
-## How to use it
-
-Solid Queue does not show up in Rails `/up`. **solid_queue_guard** gives you four operational surfaces:
+### Operational surfaces
 
 | Surface | Command / URL | Best for |
 | ------- | ------------- | -------- |
 | **Doctor** | `bin/rails solid_queue_guard:doctor` | Local pre-deploy, config review |
-| **CI gate** | `SOLID_QUEUE_GUARD_STRICT=1 bin/rails solid_queue_guard:doctor` | Block merges with broken queue config |
-| **HTTP health** | `GET /solid_queue_guard/health` | Production uptime monitors (Kamal, ECS, UptimeRobot) |
-| **Guard tab** | `GET /jobs/applications/:application_id/guard` (with `integrate_mission_control`) | Human-readable checks inside Mission Control |
-
-**Mission Control** shows what is happening. **solid_queue_guard** warns what is dangerous. Use both.
+| **CI gate** | `SOLID_QUEUE_GUARD_STRICT=1 bin/rails solid_queue_guard:doctor` | Block bad merges |
+| **HTTP health** | `GET /solid_queue_guard/health` | Kamal, ECS, K8s, UptimeRobot |
+| **Guard tab** | `GET …/applications/:application_id/guard` | Human checks in Mission Control |
 
-### Local and pre-deploy
-
-Run before changing `queue.yml`, `database.yml`, or recurring tasks:
+---
 
-```bash
-bin/rails solid_queue_guard:doctor      # config checks (default scope)
-bin/rails solid_queue_guard:report      # config + runtime when the queue DB is available
-```
+## 🛡️ Mission Control dashboard
 
-By default the install generator sets `config.enabled = %w[production staging].include?(Rails.env)`, so in **development** and other non-deployed environments checks are skipped unless you enable them:
+Opt-in **Guard** tab for [Mission Control — Jobs](https://github.com/rails/mission_control-jobs):
 
 ```ruby
-SolidQueueGuard.configure { |c| c.enabled = true }
-```
-
-Or run with production config locally when validating deploy readiness.
-
-### CI pipelines
-
-Validate **configuration** before deploy. Process/runtime checks usually **skip** in CI because there is no `bin/jobs` supervisor on the runner.
-
-```yaml
-- name: Solid Queue production readiness
-  run: SOLID_QUEUE_GUARD_STRICT=1 bin/rails solid_queue_guard:doctor
-```
-
-`STRICT=1` turns warnings into exit code `1`, so the pipeline fails on misconfigured pools, missing worker coverage, or missing schema tables — not only hard failures.
-
-Generate a starter workflow:
-
-```bash
-bin/rails generate solid_queue_guard:install:ci
-```
-
-### Production monitoring
+gem "mission_control-jobs"
 
-Mount the engine and point your load balancer or Kamal health check at `/solid_queue_guard/health`:
+SolidQueueGuard.configure { |config| config.integrate_mission_control = true }
 
-```ruby
-# config/routes.rb
+mount MissionControl::Jobs::Engine, at: "/jobs"
 mount SolidQueueGuard::Engine, at: "/solid_queue_guard"
 ```
 
-Runtime checks matter here: queue lag, stale heartbeats, dispatcher health, and process topology reflect **live** Solid Queue state.
+![Guard tab in Mission Control](docs/mission-control-guard-dashboard.png)
 
-Optional hardening:
-
-```ruby
-config.health_token = ENV["SOLID_QUEUE_GUARD_TOKEN"]
-config.health_cache_ttl = 15.seconds
-config.degraded_http_status = 207   # or :ok (200), 503, etc.
-config.notify_with = [:rails_logger, :slack]
-```
-
-### Typical flow
-
-```text
-Developer          CI                    Production
-    │               │                         │
-    │ doctor        │ doctor --strict           │ GET /health (every 30–60s)
-    ▼               ▼                         ▼
- "pool wrong?"   block bad deploy          alert: worker dead
- "schema ok?"    before merge              alert: queue lag
-```
-
----
-
-## Runtime process checks
-
-Runtime checks query the **queue database** (via `SolidQueue::Record`). If `connects_to` is missing or the DB is unreachable, they **skip** — they do not pass silently as healthy.
-
-### `process_topology` — are the expected roles present?
-
-Reads distinct `kind` values from `solid_queue_processes`:
-
-| Kind | Role |
-| ---- | ---- |
-| `Supervisor` | Parent process (`bin/jobs`) |
-| `Worker` | Consumes ready jobs |
-| `Dispatcher` | Moves scheduled jobs to ready |
-| `Scheduler` | Runs recurring tasks |
-
-| Result | Meaning |
-| ------ | ------- |
-| ⚠️ No processes | Nothing registered — supervisor not running |
-| ⚠️ No Worker | Jobs will not be processed |
-| ⚠️ No Dispatcher | Scheduled work may stall (when recurring/scheduled jobs exist) |
-| ✅ Pass | Expected kinds are present |
-
-This check looks at **presence of records**, not heartbeat freshness.
-
-### `stale_process` — are heartbeats fresh?
-
-Finds processes where `last_heartbeat_at` is older than `stale_process_threshold` (default **5 minutes**):
-
-| Result | Meaning |
-| ------ | ------- |
-| ✅ Pass | All processes reported recently |
-| ❌ Fail | One or more workers/dispatchers look dead or stuck |
-
-Use this in production health to catch workers that died after deploy.
-
-### `pidfile` — optional supervisor liveness
-
-When `tmp/pids/solid_queue.pid` (or `SOLID_QUEUE_PIDFILE`) exists, verifies the PID is alive. Often **warns in development** where `bin/jobs` is not running. Disable if you do not use pidfiles:
-
-```ruby
-config.disabled_checks = [:pidfile]
-```
-
-### `puma_plugin_runtime` — Solid Queue inside Puma
-
-When `plugin :solid_queue` is in `config/puma.rb`, verifies active processes with recent heartbeats exist. **Skips** when the Puma plugin is not enabled.
-
-### Queue schema detection
-
-`QueueSchemaCheck` does **not** require `db/queue_schema.rb`. It validates that all tables for your installed **solid_queue** version exist in any of:
-
-- `db/queue_schema.rb`
-- `db/schema.rb`
-- `db/structure.sql`
-- the connected queue database
-
-Apps that keep Solid Queue tables only in `structure.sql` (common in Revelo-style repos) pass correctly.
-
-### Where each check type applies
-
-| Context | Config checks | Process / runtime checks |
-| ------- | ------------- | ------------------------ |
-| Local `doctor` | ✅ Primary value | ⚠️ Partial without `bin/jobs` |
-| CI `--strict` | ✅ Primary value | ⏭️ Usually skip |
-| Production `/health` | ✅ When DB up | ✅ Primary value |
-
----
-
-## Configuration
-
-```ruby
-# config/initializers/solid_queue_guard.rb
-SolidQueueGuard.configure do |config|
-  config.enabled = %w[production staging].include?(Rails.env)
-
-  config.queue_lag_thresholds = {
-    critical: 30.seconds,
-    default:  5.minutes,
-    mailers:  15.minutes
-  }
-
-  config.failed_jobs_threshold = 20
-  config.stale_process_threshold = 5.minutes
-
-  # Per-check overrides (v0.6+)
-  config.disabled_checks = [:pidfile]
-  config.checks.queue_lag = { threshold: 10.minutes }
-  config.checks.failed_jobs = { threshold: 5, enabled: true }
-
-  # HTTP status policy (v0.8+)
-  # config.degraded_http_status = 207
-  # config.unhealthy_http_status = 503
-
-  # config.health_token = ENV["SOLID_QUEUE_GUARD_TOKEN"]
-  # config.integrate_rails_health = true
-  # config.integrate_mission_control = true  # Guard tab in Mission Control (requires mission_control-jobs)
-  # config.notify_with = [:rails_logger, :slack, :datadog, :webhook]
-  # config.metrics_backends = [:statsd, :prometheus, :opentelemetry]
-end
-```
+Requires `mission_control-jobs` and an asset pipeline (Propshaft or Sprockets). Load balancers should keep using `/solid_queue_guard/health`.
 
 ---
 
 ## Public API (v1.0+)
 
-The following surface is **stable** until `2.0` and follows [semantic versioning](https://semver.org/):
+Stable until `2.0` — [semantic versioning](https://semver.org/):
 
 | API | Description |
 | --- | ----------- |
 | `SolidQueueGuard.configure` | Block-style configuration |
-| `SolidQueueGuard.config` | Current configuration object |
-| `SolidQueueGuard.enabled?` | Whether checks run |
 | `solid_queue_guard:doctor` | Config readiness report |
-| `solid_queue_guard:health` | Runtime health report |
 | `solid_queue_guard:report` | Full diagnostic report |
-| `solid_queue_guard:install` | Initializer generator |
-| `solid_queue_guard:install:ci` | GitHub Actions workflow generator |
 | `mount SolidQueueGuard::Engine` | HTTP health endpoint |
-| `config.integrate_mission_control` | Guard tab in Mission Control (opt-in, requires `mission_control-jobs`) |
-| `GET /jobs/applications/:application_id/guard` | Human-readable health dashboard (when integration enabled) |
-
-Configuration attributes, rake tasks, health JSON shape, and Mission Control integration are public. Internal check classes and registry are `@api private`.
+| `config.integrate_mission_control` | Guard tab (requires `mission_control-jobs`) |
 
-Breaking changes ship only in major versions (`2.0+`). Deprecations warn one minor version ahead.
+Internal check classes and registry are `@api private`.
 
 ---
 
-## ⚔️ solid_queue_guard vs Mission Control
+## ⚔️ vs Mission Control
 
-| | [Mission Control — Jobs](https://github.com/rails/mission_control-jobs) | solid_queue_guard |
+| | Mission Control | solid_queue_guard |
 | --- | --- | --- |
 | **Purpose** | Inspect & manage jobs | Detect production risk |
-| **UI** | Dashboard | CLI + JSON + health endpoint + optional Guard tab in Mission Control |
-| **Retry / discard** | Yes | No (use Mission Control) |
 | **Config doctor** | No | Yes |
-| **Queue lag alerts** | No | Yes |
 | **Pre-deploy checks** | No | Yes |
-| **Recurring job guard** | Manual inspection | Automatic |
-
-**Use both.** They solve different problems.
-
----
+| **Queue lag alerts** | No | Yes |
 
-## Roadmap
-
-| Version | Ships | Status |
-| ------- | ----- | ------ |
-| **v0.1** | `doctor` — config checks, CI integration, install generator | ✅ Released |
-| **v0.2** | Runtime health, queue lag, dispatcher/blocked jobs, HTTP endpoint | ✅ Released |
-| **v0.3** | Slack, Datadog, webhook notifications | ✅ Released |
-| **v0.4** | StatsD, Prometheus, OpenTelemetry metrics | ✅ Released |
-| **v0.5** | Auto-recommendations for `queue.yml` topology | ✅ Released |
-| **v0.6** | Per-check configuration (`disabled_checks`, `config.checks`) | ✅ Released |
-| **v0.7** | Puma plugin runtime check, async supervisor awareness | ✅ Released |
-| **v0.8** | HTTP status policy, `install:ci` generator | ✅ Released |
-| **v1.0** | Stable public API, strict semver | ✅ Released |
-| **v1.1** | Mission Control Guard tab (opt-in) | ✅ Released |
+**Use both.**
 
 ---
 
@@ -504,55 +157,26 @@ Breaking changes ship only in major versions (`2.0+`). Deprecations warn one min
 
 | Gem version | Ruby | Rails |
 | ----------- | ---- | ----- |
+| 1.2.x       | 3.1+ | 7.1, 7.2, 8.0 |
 | 1.1.x       | 3.1+ | 7.1, 7.2, 8.0 |
 | 1.0.x       | 3.1+ | 7.1, 7.2, 8.0 |
-| 0.5.x       | 3.1+ | 7.1, 7.2, 8.0 |
-| 0.1.x       | 3.1+ | 7.1, 7.2, 8.0 |
 
-## Requirements
-
-- Ruby >= 3.1
-- Rails >= 7.1, < 9.0
 - [solid_queue](https://github.com/rails/solid_queue) >= 1.0, < 2.0
-- [mission_control-jobs](https://github.com/rails/mission_control-jobs) >= 1.0 — optional, only for `integrate_mission_control`
+- [mission_control-jobs](https://github.com/rails/mission_control-jobs) — optional
 
 ---
 
 ## Development
 
+See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, `bin/console`, Appraisal matrix, and `script/validate_revelo.sh`.
+
 ```bash
-git clone https://github.com/rafael-pissardo/solid_queue_guard.git
-cd solid_queue_guard
-bundle install
-cd test/dummy && bin/setup
-cd ../.. && bundle exec rake test
+bundle exec rake test
 bundle exec rubocop
-bundle exec appraisal install
 bundle exec appraisal rake test
+gem build solid_queue_guard.gemspec
 ```
 
-Release a new version after CI passes:
-
-```bash
-# Tag must match lib/solid_queue_guard/version.rb (currently 1.1.4)
-git tag v1.1.4
-git push origin v1.1.4
-```
-
-Trusted Publishing on RubyGems publishes automatically when the tag is pushed.
-
----
-
-## Contributing
-
-Issues and PRs welcome. Keep it focused: **production safety**, not another job dashboard.
-
-1. Fork it
-2. Create your branch (`git checkout -b my-new-check`)
-3. Write a test first
-4. Make the check pass
-5. Open a PR
-
 ---
 
 ## License

data/bin/console

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require_relative '../test/dummy/config/environment'
+require 'rails/console'
+
+Rails.application.console

data/lib/generators/solid_queue_guard/install/templates/solid_queue_guard.rb

@@ -23,6 +23,7 @@ SolidQueueGuard.configure do |config|
   # config.health_token = ENV["SOLID_QUEUE_GUARD_TOKEN"]
   # config.integrate_rails_health = true
   # config.integrate_mission_control = true
+  # config.on_status_change = ->(previous, current, report) { ... }
   # config.notify_with = [:rails_logger, :slack, :datadog, :webhook]
   # config.metrics_backends = [:statsd, :prometheus, :opentelemetry]
 end

data/lib/solid_queue_guard/checks/registry.rb

@@ -40,6 +40,13 @@ module SolidQueueGuard
           check_class.check_id
         end
 
+        def catalog
+          {
+            config: CONFIG_CHECKS.map(&:check_id),
+            runtime: RUNTIME_CHECKS.map(&:check_id)
+          }
+        end
+
         def for(scope)
           case scope.to_sym
           when :config then CONFIG_CHECKS

data/lib/solid_queue_guard/configuration.rb

@@ -2,6 +2,10 @@
 
 module SolidQueueGuard
   class Configuration
+    class ValidationError < StandardError; end
+
+    HTTP_STATUS_OPTIONS = HttpStatusPolicy::STATUS_MAP.keys.freeze
+
     attr_accessor :enabled,
                   :queue_lag_thresholds,
                   :failed_jobs_threshold,
@@ -17,7 +21,8 @@ module SolidQueueGuard
                   :disabled_checks,
                   :checks,
                   :degraded_http_status,
-                  :unhealthy_http_status
+                  :unhealthy_http_status,
+                  :on_status_change
 
     def initialize
       @enabled = true
@@ -36,6 +41,18 @@ module SolidQueueGuard
       @checks = ActiveSupport::OrderedOptions.new
       @degraded_http_status = :ok
       @unhealthy_http_status = :service_unavailable
+      @on_status_change = nil
+    end
+
+    def validate!
+      validate_http_status!(:degraded_http_status, degraded_http_status)
+      validate_http_status!(:unhealthy_http_status, unhealthy_http_status)
+      validate_duration!(:stale_process_threshold, stale_process_threshold)
+      validate_duration!(:health_cache_ttl, health_cache_ttl)
+      validate_positive_integer!(:failed_jobs_threshold, failed_jobs_threshold)
+      validate_positive_integer!(:scheduled_backlog_threshold, scheduled_backlog_threshold)
+      validate_callback!(:on_status_change, on_status_change)
+      self
     end
 
     def strict?
@@ -66,5 +83,36 @@ module SolidQueueGuard
       value = settings[key.to_sym] if value.nil?
       value.nil? ? default : value
     end
+
+    private
+
+    def validate_http_status!(attribute, value)
+      return if HTTP_STATUS_OPTIONS.include?(normalize_http_status_key(value))
+
+      raise ValidationError,
+            "#{attribute} must be one of #{HTTP_STATUS_OPTIONS.inspect}, got #{value.inspect}"
+    end
+
+    def normalize_http_status_key(value)
+      value.is_a?(Integer) ? value : value.to_sym
+    end
+
+    def validate_duration!(attribute, value)
+      return if value.is_a?(ActiveSupport::Duration) && value.positive?
+
+      raise ValidationError, "#{attribute} must be a positive ActiveSupport::Duration"
+    end
+
+    def validate_positive_integer!(attribute, value)
+      return if value.is_a?(Integer) && value.positive?
+
+      raise ValidationError, "#{attribute} must be a positive Integer"
+    end
+
+    def validate_callback!(attribute, value)
+      return if value.nil? || value.respond_to?(:call)
+
+      raise ValidationError, "#{attribute} must respond to #call"
+    end
   end
 end

data/lib/solid_queue_guard/engine.rb

@@ -15,6 +15,7 @@ module SolidQueueGuard
         config.solid_queue_guard.each do |name, value|
           guard_config.public_send("#{name}=", value)
         end
+        guard_config.validate!
       end
     end
 

data/lib/solid_queue_guard/health/cache.rb

@@ -2,6 +2,7 @@
 
 module SolidQueueGuard
   module Health
+    # @api private
     class Cache
       def self.fetch
         new.fetch
@@ -9,7 +10,7 @@ module SolidQueueGuard
 
       def fetch
         Rails.cache.fetch(cache_key, expires_in: SolidQueueGuard.config.health_cache_ttl) do
-          build_payload
+          build_payload(previous_status: read_cached_status)
         end
       end
 
@@ -19,8 +20,13 @@ module SolidQueueGuard
         'solid_queue_guard/health'
       end
 
-      def build_payload
+      def read_cached_status
+        Rails.cache.read(cache_key)&.dig(:status)
+      end
+
+      def build_payload(previous_status: nil)
         report = Runner.new(scope: :all).run
+        Observability.notify_status_change(report, previous_status: previous_status&.to_sym)
         Payload.new(report).to_h
       end
     end

data/lib/solid_queue_guard/health/payload.rb

@@ -2,6 +2,7 @@
 
 module SolidQueueGuard
   module Health
+    # @api private
     class Payload
       def initialize(report)
         @report = report

data/lib/solid_queue_guard/metrics/exporter.rb

@@ -4,6 +4,7 @@ module SolidQueueGuard
   module Metrics
     class Exporter
       STATUS_VALUES = { healthy: 0, degraded: 1, unhealthy: 2 }.freeze
+      CHECK_STATUS_VALUES = { pass: 0, warn: 1, fail: 2, skip: 3 }.freeze
 
       def self.export(report, backends: SolidQueueGuard.config.metrics_backends)
         new(report, backends: backends).export
@@ -27,6 +28,8 @@ module SolidQueueGuard
         when :statsd then Statsd.export(report)
         when :prometheus then Prometheus.export(report)
         when :opentelemetry then OpenTelemetry.export(report)
+        else
+          OptionalDependency.log_missing("metrics backend #{backend}")
         end
       end
     end

data/lib/solid_queue_guard/metrics/open_telemetry.rb

@@ -6,14 +6,22 @@ module SolidQueueGuard
       module_function
 
       def export(report)
-        return unless defined?(::OpenTelemetry)
+        return unless OptionalDependency.require!('opentelemetry-sdk', 'opentelemetry-sdk')
 
         meter = ::OpenTelemetry.meter_provider.meter('solid_queue_guard')
-        gauge = meter.create_gauge('solid_queue.guard.overall_status', unit: 'status')
-        gauge.record(Exporter::STATUS_VALUES.fetch(report.status))
-      rescue StandardError
-        nil
+        overall_gauge = meter.create_gauge('solid_queue.guard.overall_status', unit: 'status')
+        overall_gauge.record(STATUS_VALUES.fetch(report.status))
+
+        check_gauge = meter.create_gauge('solid_queue.guard.check_status', unit: 'status')
+        report.results.each do |result|
+          check_gauge.record(CHECK_STATUS_VALUES.fetch(result.status), attributes: { 'check.id' => result.id })
+        end
+      rescue StandardError => e
+        Rails.logger.warn("[solid_queue_guard] OpenTelemetry export failed: #{e.class}: #{e.message}")
       end
+
+      STATUS_VALUES = Exporter::STATUS_VALUES
+      CHECK_STATUS_VALUES = Exporter::CHECK_STATUS_VALUES
     end
   end
 end

data/lib/solid_queue_guard/metrics/prometheus.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'fileutils'
+
 module SolidQueueGuard
   module Metrics
     module Prometheus
@@ -7,15 +9,27 @@ module SolidQueueGuard
 
       def export(report)
         path = ENV.fetch('SOLID_QUEUE_GUARD_PROMETHEUS_FILE', Rails.root.join('tmp/solid_queue_guard.prom'))
+        FileUtils.mkdir_p(File.dirname(path))
         File.write(path, render(report))
       end
 
       def render(report)
-        <<~PROM
-          # TYPE solid_queue_guard_overall_status gauge
-          solid_queue_guard_overall_status #{Exporter::STATUS_VALUES.fetch(report.status)}
-        PROM
+        lines = [
+          '# TYPE solid_queue_guard_overall_status gauge',
+          "solid_queue_guard_overall_status #{STATUS_VALUES.fetch(report.status)}",
+          '# TYPE solid_queue_guard_check_status gauge'
+        ]
+
+        report.results.each do |result|
+          value = CHECK_STATUS_VALUES.fetch(result.status)
+          lines << "solid_queue_guard_check_status{check=\"#{result.id}\"} #{value}"
+        end
+
+        "#{lines.join("\n")}\n"
       end
+
+      STATUS_VALUES = Exporter::STATUS_VALUES
+      CHECK_STATUS_VALUES = Exporter::CHECK_STATUS_VALUES
     end
   end
 end

data/lib/solid_queue_guard/metrics/statsd.rb

@@ -6,20 +6,32 @@ module SolidQueueGuard
       module_function
 
       def export(report)
-        require 'socket'
         host = ENV.fetch('SOLID_QUEUE_GUARD_STATSD_HOST', '127.0.0.1')
         port = ENV.fetch('SOLID_QUEUE_GUARD_STATSD_PORT', 8125).to_i
         socket = UDPSocket.new
-        socket.send(metric_line(report), 0, host, port)
+        metric_lines(report).each do |line|
+          socket.send(line, 0, host, port)
+        end
       ensure
         socket&.close
       end
 
-      def metric_line(report)
-        "solid_queue.guard.overall_status:#{STATUS_VALUES.fetch(report.status)}|g"
+      def metric_lines(report)
+        [
+          "solid_queue.guard.overall_status:#{STATUS_VALUES.fetch(report.status)}|g",
+          *check_status_lines(report)
+        ]
+      end
+
+      def check_status_lines(report)
+        report.results.map do |result|
+          value = CHECK_STATUS_VALUES.fetch(result.status)
+          "solid_queue.guard.check_status:#{value}|g|##{result.id}"
+        end
       end
 
       STATUS_VALUES = Exporter::STATUS_VALUES
+      CHECK_STATUS_VALUES = Exporter::CHECK_STATUS_VALUES
     end
   end
 end

data/lib/solid_queue_guard/mission_control/integration.rb

@@ -2,6 +2,7 @@
 
 module SolidQueueGuard
   module MissionControl
+    # @api private
     class Integration
       class << self
         def install!

data/lib/solid_queue_guard/mission_control/navigation_extension.rb

@@ -2,6 +2,7 @@
 
 module SolidQueueGuard
   module MissionControl
+    # @api private
     module NavigationExtension
       def navigation_sections
         super.tap do |sections|

data/lib/solid_queue_guard/notifier.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module SolidQueueGuard
+  # @api private
   class Notifier
     class << self
       def deliver_all(report, adapters: SolidQueueGuard.config.notify_with)

data/lib/solid_queue_guard/observability.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module SolidQueueGuard
+  # @api private
+  module Observability
+    module_function
+
+    def log_results(report)
+      return unless logger
+
+      report.results.each do |result|
+        message = "[SolidQueueGuard] #{result.status} check #{result.id}: #{result.message}"
+        case result.status
+        when :skip, :pass then logger.debug(message)
+        when :warn then logger.warn(message)
+        when :fail then logger.error(message)
+        end
+      end
+    end
+
+    def notify_status_change(report, previous_status: nil)
+      callback = SolidQueueGuard.config.on_status_change
+      return unless callback.respond_to?(:call)
+
+      current_status = report.status
+      return if previous_status == current_status
+
+      callback.call(previous_status, current_status, report)
+    end
+
+    def logger
+      defined?(Rails) && Rails.logger
+    end
+  end
+end

data/lib/solid_queue_guard/optional_dependency.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module SolidQueueGuard
+  # @api private
+  module OptionalDependency
+    module_function
+
+    def require!(feature, gem_name = feature)
+      require feature
+      true
+    rescue LoadError
+      log_missing(gem_name)
+      false
+    end
+
+    def log_missing(gem_name)
+      return unless defined?(Rails) && Rails.logger
+
+      Rails.logger.warn(
+        "[solid_queue_guard] Optional dependency #{gem_name} is not installed. " \
+        'Add it to your Gemfile to enable this integration.'
+      )
+    end
+  end
+end

data/lib/solid_queue_guard/report.rb

@@ -37,8 +37,13 @@ module SolidQueueGuard
         status: status.to_s,
         warnings: warnings,
         suggestions: suggestions,
+        status_counts: status_counts,
         checks: results.map(&:to_h)
       }
     end
+
+    def status_counts
+      results.group_by(&:status).transform_values(&:size)
+    end
   end
 end

data/lib/solid_queue_guard/runner.rb

@@ -15,7 +15,7 @@ module SolidQueueGuard
         run_check(check_class)
       end
 
-      Report.new(results)
+      Report.new(results).tap { |report| Observability.log_results(report) }
     end
 
     private

data/lib/solid_queue_guard/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SolidQueueGuard
-  VERSION = '1.1.4'
+  VERSION = '1.2.0'
 end

data/solid_queue_guard.gemspec

@@ -26,7 +26,8 @@ Gem::Specification.new do |spec|
 
   spec.files = Dir.chdir(File.expand_path(__dir__)) do
     `git ls-files -z`.split("\x0").reject do |file|
-      file.start_with?('test/', '.github/', 'docs/', 'script/', 'gemfiles/', 'Appraisals')
+      file.start_with?('test/', '.github/', 'script/', 'gemfiles/', 'Appraisals') ||
+        (file.start_with?('docs/') && file != 'docs/mission-control-guard-dashboard.png')
     end
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: solid_queue_guard
 version: !ruby/object:Gem::Version
-  version: 1.1.4
+  version: 1.2.0
 platform: ruby
 authors:
 - Rafael Pissardo
@@ -301,11 +301,13 @@ files:
 - ".rubocop.yml"
 - ".ruby-version"
 - CHANGELOG.md
+- CONTRIBUTING.md
 - Gemfile
 - Gemfile.lock
 - MIT-LICENSE
 - README.md
 - Rakefile
+- app/assets/images/solid_queue_guard/mission-control-guard-dashboard.png
 - app/controllers/solid_queue_guard/application_controller.rb
 - app/controllers/solid_queue_guard/health_controller.rb
 - app/controllers/solid_queue_guard/mission_control/base_controller.rb
@@ -314,7 +316,9 @@ files:
 - app/views/solid_queue_guard/mission_control/dashboard/_check.html.erb
 - app/views/solid_queue_guard/mission_control/dashboard/_summary_metrics.html.erb
 - app/views/solid_queue_guard/mission_control/dashboard/show.html.erb
+- bin/console
 - config/routes.rb
+- docs/mission-control-guard-dashboard.png
 - lib/generators/solid_queue_guard/install/USAGE
 - lib/generators/solid_queue_guard/install/USAGE.ci
 - lib/generators/solid_queue_guard/install/ci_generator.rb
@@ -368,6 +372,8 @@ files:
 - lib/solid_queue_guard/mission_control/navigation_extension.rb
 - lib/solid_queue_guard/notifier.rb
 - lib/solid_queue_guard/notifiers/base.rb
+- lib/solid_queue_guard/observability.rb
+- lib/solid_queue_guard/optional_dependency.rb
 - lib/solid_queue_guard/puma_plugin_support.rb
 - lib/solid_queue_guard/queue_coverage.rb
 - lib/solid_queue_guard/recommendations/topology.rb