solid_queue_guard 0.1.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bd60b98c25c507b3069f98b6b69282f627a398e96bd43d7a5d0713f0499c8610
-  data.tar.gz: c60a8995c311f4935456f58ca950e1d4cdb4b7e601dc1e6290f62f9d06931cb0
+  metadata.gz: c3b3fded32011114a722d7207eb15c44dad0d1be1e0c5b3202bdaf32f84ea819
+  data.tar.gz: 6ef2779a3372987138feb9a2dc9730ba7750c67a544a2c821029988877feb8de
 SHA512:
-  metadata.gz: ac5fbbb57df0cb133466076f0c4c1b698a13004b3f44e22bc64139e04e8c4bb51973a22e534ff0617329709a154a92a7a93ac9e083ea0087d86dadc73c6e89cf
-  data.tar.gz: b16bc3883213b26928b0cfa2c4d0b355ce43bd956a4c3df27e4cad4f8f71534748a15e5f9c892190a018741df8c9f1fbe4aaaa577e960f4e39a2a28c00a823ed
+  metadata.gz: 39c815be31c9ec06116840f813f57a6a9ebcb2dcad7c3747bf47d87cb59304fbdc6e629be2ffbb725eb649c913a75409c6b1e39bcb9c3e627ac00707af579e90
+  data.tar.gz: c338648964e042b7d5fb485c8281bc1337ab54acfe693b886e9f8ed656135aa924fe8cbc89af3382003dafea8844ab01497e4205b92ae474b376b1419751d68d

data/README.md

@@ -138,7 +138,7 @@ Perfect for deploy pipelines:
   run: SOLID_QUEUE_GUARD_STRICT=1 bin/rails solid_queue_guard:doctor
 ```
 
-### HTTP health (v0.2)
+### HTTP health
 
 ```ruby
 # config/routes.rb
@@ -150,6 +150,13 @@ 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" ...
+```
+
 Works with **Kamal**, **Heroku**, **Fly.io**, **ECS/Fargate**, **Kubernetes**, **Better Stack**, **UptimeRobot**.
 
 ---
@@ -197,11 +204,11 @@ end
 
 | Version | Ships |
 | ------- | ----- |
-| **v0.1** | `doctor` — config checks, CI integration, install generator |
-| **v0.2** | Runtime health, queue lag, dispatcher/blocked jobs, HTTP endpoint |
-| **v0.3** | Slack, Datadog, webhook notifications |
-| **v0.4** | StatsD, Prometheus, OpenTelemetry metrics |
-| **v0.5** | Auto-recommendations for `queue.yml` topology |
+| **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 |
 
 ---
 
@@ -210,6 +217,7 @@ end
 | Gem version | Ruby | Rails |
 | ----------- | ---- | ----- |
 | 0.1.x       | 3.1+ | 7.1, 7.2, 8.0 |
+| 0.5.x       | 3.1+ | 7.1, 7.2, 8.0 |
 
 ## Requirements
 

data/app/controllers/solid_queue_guard/application_controller.rb

@@ -2,5 +2,6 @@
 
 module SolidQueueGuard
   class ApplicationController < ActionController::Base
+    protect_from_forgery with: :null_session
   end
 end

data/app/controllers/solid_queue_guard/health_controller.rb

@@ -2,8 +2,32 @@
 
 module SolidQueueGuard
   class HealthController < ApplicationController
+    before_action :authenticate_token!
+
     def show
-      render json: { status: 'not_implemented', message: 'HTTP health checks ship in v0.2' }, status: :not_implemented
+      payload = Health::Cache.fetch
+      status_code = http_status_for(payload[:status])
+
+      render json: payload, status: status_code
+    end
+
+    private
+
+    def authenticate_token!
+      token = SolidQueueGuard.config.health_token
+      return if token.blank?
+
+      provided = request.headers['X-Solid-Queue-Guard-Token'].presence || params[:token]
+      return if ActiveSupport::SecurityUtils.secure_compare(provided.to_s, token.to_s)
+
+      render json: { status: 'unauthorized' }, status: :unauthorized
+    end
+
+    def http_status_for(status)
+      case status.to_s
+      when 'unhealthy' then :service_unavailable
+      else :ok
+      end
     end
   end
 end

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

@@ -11,7 +11,11 @@ SolidQueueGuard.configure do |config|
 
   config.failed_jobs_threshold = 20
   config.stale_process_threshold = 5.minutes
+  config.health_cache_ttl = 15.seconds
+  config.scheduled_backlog_threshold = 100
 
   # config.health_token = ENV["SOLID_QUEUE_GUARD_TOKEN"]
-  # config.notify_with = [ :rails_logger ]
+  # config.integrate_rails_health = true
+  # config.notify_with = [:rails_logger, :slack, :datadog, :webhook]
+  # config.metrics_backends = [:statsd, :prometheus, :opentelemetry]
 end

data/lib/solid_queue_guard/checks/config/topology_recommendation_check.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module SolidQueueGuard
+  module Checks
+    module Config
+      class TopologyRecommendationCheck < Base
+        def call
+          recommendations = Recommendations::Topology.analyze
+
+          if recommendations.empty?
+            pass('topology_recommendation', 'No queue.yml topology changes recommended')
+          else
+            warn(
+              'topology_recommendation',
+              recommendations.join('; '),
+              suggestion: 'Review config/queue.yml worker and database pool settings',
+              metadata: { recommendations: recommendations }
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/solid_queue_guard/checks/registry.rb

@@ -14,7 +14,8 @@ module SolidQueueGuard
         Config::SchedulerConfigCheck,
         Config::EnvFlagsCheck,
         Config::ProcessHeartbeatConfigCheck,
-        Config::PumaColocatedCheck
+        Config::PumaColocatedCheck,
+        Config::TopologyRecommendationCheck
       ].freeze
 
       RUNTIME_CHECKS = [

data/lib/solid_queue_guard/checks/runtime/base.rb

@@ -4,11 +4,7 @@ module SolidQueueGuard
   module Checks
     module Runtime
       class Base < Checks::Base
-        NOT_IMPLEMENTED_MESSAGE = 'Runtime check not implemented until v0.2'
-
-        def call
-          skip(check_id, NOT_IMPLEMENTED_MESSAGE)
-        end
+        include DatabaseSupport
 
         private
 

data/lib/solid_queue_guard/checks/runtime/blocked_jobs_check.rb

@@ -3,7 +3,26 @@
 module SolidQueueGuard
   module Checks
     module Runtime
-      class BlockedJobsCheck < Base; end
+      class BlockedJobsCheck < Base
+        def call
+          with_queue_database do
+            blocked = SolidQueue::BlockedExecution.count
+            expired = SolidQueue::BlockedExecution.expired.count
+
+            if expired.positive?
+              warn(
+                check_id,
+                "#{expired} blocked job(s) have expired concurrency locks",
+                suggestion: 'Verify concurrency release maintenance is running'
+              )
+            elsif blocked.positive?
+              pass(check_id, "#{blocked} job(s) blocked by concurrency control")
+            else
+              pass(check_id, 'No blocked jobs')
+            end
+          end
+        end
+      end
     end
   end
 end

data/lib/solid_queue_guard/checks/runtime/database_support.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module SolidQueueGuard
+  module Checks
+    module Runtime
+      module DatabaseSupport
+        private
+
+        def queue_database_available?
+          pool = SolidQueue::Record.connection_pool
+          return false if pool.nil?
+
+          pool.with_connection(&:active?)
+        rescue StandardError
+          false
+        end
+
+        def with_queue_database
+          return skip(check_id, 'Queue database is not available') unless queue_database_available?
+
+          yield
+        rescue StandardError => e
+          skip(check_id, "Queue database query failed: #{e.class}")
+        end
+
+        def config
+          SolidQueueGuard.config
+        end
+
+        def lag_threshold_for(queue_name)
+          thresholds = config.queue_lag_thresholds
+          thresholds[queue_name.to_sym] || thresholds[queue_name] || thresholds[:default]
+        end
+      end
+    end
+  end
+end

data/lib/solid_queue_guard/checks/runtime/dispatcher_check.rb

@@ -3,7 +3,30 @@
 module SolidQueueGuard
   module Checks
     module Runtime
-      class DispatcherCheck < Base; end
+      class DispatcherCheck < Base
+        def call
+          with_queue_database do
+            dispatchers = SolidQueue::Process.where(kind: 'Dispatcher')
+            due_count = SolidQueue::ScheduledExecution.due.count
+
+            if dispatchers.none? && due_count.positive?
+              failure(
+                check_id,
+                "#{due_count} scheduled job(s) are due but no dispatcher is running",
+                suggestion: 'Start a dispatcher process or verify bin/jobs is running'
+              )
+            elsif due_count > config.scheduled_backlog_threshold
+              warn(
+                check_id,
+                "#{due_count} scheduled executions are due (threshold: #{config.scheduled_backlog_threshold})",
+                suggestion: 'Verify the dispatcher is keeping up with scheduled work'
+              )
+            else
+              pass(check_id, "Dispatcher healthy (#{due_count} due scheduled executions)")
+            end
+          end
+        end
+      end
     end
   end
 end

data/lib/solid_queue_guard/checks/runtime/failed_jobs_check.rb

@@ -3,7 +3,27 @@
 module SolidQueueGuard
   module Checks
     module Runtime
-      class FailedJobsCheck < Base; end
+      class FailedJobsCheck < Base
+        WINDOW = 1.hour
+
+        def call
+          with_queue_database do
+            count = SolidQueue::FailedExecution.where(created_at: WINDOW.ago..).count
+            threshold = config.failed_jobs_threshold
+
+            if count > threshold
+              warn(
+                check_id,
+                "#{count} failed job(s) in the last hour (threshold: #{threshold})",
+                suggestion: 'Review failed jobs in Mission Control or solid_queue_failed_executions',
+                metadata: { failed_jobs_last_hour: count }
+              )
+            else
+              pass(check_id, "#{count} failed job(s) in the last hour")
+            end
+          end
+        end
+      end
     end
   end
 end

data/lib/solid_queue_guard/checks/runtime/finished_jobs_growth_check.rb

@@ -3,7 +3,26 @@
 module SolidQueueGuard
   module Checks
     module Runtime
-      class FinishedJobsGrowthCheck < Base; end
+      class FinishedJobsGrowthCheck < Base
+        WINDOW = 24.hours
+        GROWTH_THRESHOLD = 10_000
+
+        def call
+          with_queue_database do
+            recent_finished = SolidQueue::Job.where(finished_at: WINDOW.ago..).count
+
+            if recent_finished > GROWTH_THRESHOLD
+              warn(
+                check_id,
+                "#{recent_finished} finished jobs in the last 24 hours",
+                suggestion: 'Ensure a recurring cleanup task runs (SolidQueue::Job.clear_finished_in_batches)'
+              )
+            else
+              pass(check_id, "#{recent_finished} finished jobs in the last 24 hours")
+            end
+          end
+        end
+      end
     end
   end
 end

data/lib/solid_queue_guard/checks/runtime/orphaned_claims_check.rb

@@ -3,7 +3,24 @@
 module SolidQueueGuard
   module Checks
     module Runtime
-      class OrphanedClaimsCheck < Base; end
+      class OrphanedClaimsCheck < Base
+        def call
+          with_queue_database do
+            alive_process_ids = SolidQueue::Process.pluck(:id)
+            orphaned = SolidQueue::ClaimedExecution.where.not(process_id: alive_process_ids)
+
+            if orphaned.none?
+              pass(check_id, 'No orphaned claimed executions')
+            else
+              warn(
+                check_id,
+                "#{orphaned.count} claimed execution(s) belong to dead processes",
+                suggestion: 'Restart workers; Solid Queue maintenance should release orphaned claims'
+              )
+            end
+          end
+        end
+      end
     end
   end
 end

data/lib/solid_queue_guard/checks/runtime/paused_queue_lag_check.rb

@@ -3,7 +3,28 @@
 module SolidQueueGuard
   module Checks
     module Runtime
-      class PausedQueueLagCheck < Base; end
+      class PausedQueueLagCheck < Base
+        def call
+          with_queue_database do
+            paused_queues = SolidQueue::Pause.pluck(:queue_name)
+            return pass(check_id, 'No paused queues') if paused_queues.empty?
+
+            growing = paused_queues.select do |queue_name|
+              SolidQueue::ReadyExecution.exists?(queue_name: queue_name)
+            end
+
+            if growing.any?
+              warn(
+                check_id,
+                "Paused queue(s) still have ready jobs: #{growing.join(', ')}",
+                suggestion: 'Unpause queues or drain jobs before pausing'
+              )
+            else
+              pass(check_id, "Paused queues have no ready backlog: #{paused_queues.join(', ')}")
+            end
+          end
+        end
+      end
     end
   end
 end

data/lib/solid_queue_guard/checks/runtime/pidfile_check.rb

@@ -3,7 +3,39 @@
 module SolidQueueGuard
   module Checks
     module Runtime
-      class PidfileCheck < Base; end
+      class PidfileCheck < Base
+        def call
+          pidfile = ENV['SOLID_QUEUE_PIDFILE'] || default_pidfile
+          return pass(check_id, 'No Solid Queue pidfile configured') if pidfile.blank?
+
+          path = Pathname(pidfile)
+          unless path.exist?
+            return warn(check_id, "Pidfile not found at #{path}",
+                        suggestion: 'Verify Solid Queue supervisor is running')
+          end
+
+          pid = path.read.strip.to_i
+          if process_alive?(pid)
+            pass(check_id, "Solid Queue supervisor pidfile present (pid #{pid})")
+          else
+            failure(check_id, "Pidfile exists but process #{pid} is not running",
+                    suggestion: 'Restart the Solid Queue supervisor')
+          end
+        end
+
+        private
+
+        def default_pidfile
+          rails_root.join('tmp/pids/solid_queue.pid').to_s
+        end
+
+        def process_alive?(pid)
+          Process.getpgid(pid)
+          true
+        rescue Errno::ESRCH
+          false
+        end
+      end
     end
   end
 end

data/lib/solid_queue_guard/checks/runtime/process_topology_check.rb

@@ -3,7 +3,37 @@
 module SolidQueueGuard
   module Checks
     module Runtime
-      class ProcessTopologyCheck < Base; end
+      class ProcessTopologyCheck < Base
+        EXPECTED_KINDS = %w[Supervisor Worker Dispatcher Scheduler].freeze
+
+        def call
+          with_queue_database do
+            kinds = SolidQueue::Process.distinct.pluck(:kind)
+            missing = EXPECTED_KINDS - kinds
+
+            if missing == EXPECTED_KINDS
+              warn(check_id, 'No Solid Queue processes are running',
+                   suggestion: 'Start bin/jobs or the Solid Queue supervisor')
+            elsif missing.include?('Worker')
+              warn(check_id, 'No worker processes detected',
+                   suggestion: 'Ensure workers are configured in queue.yml and running')
+            elsif missing.include?('Dispatcher') && scheduled_work_expected?
+              warn(check_id, 'No dispatcher process detected with scheduled work configured')
+            else
+              pass(check_id, "Solid Queue processes running: #{kinds.sort.join(', ')}")
+            end
+          end
+        end
+
+        private
+
+        def scheduled_work_expected?
+          solid_queue_configuration.send(:recurring_tasks).any? ||
+            SolidQueue::ScheduledExecution.exists?
+        rescue StandardError
+          false
+        end
+      end
     end
   end
 end

data/lib/solid_queue_guard/checks/runtime/queue_lag_check.rb

@@ -3,7 +3,36 @@
 module SolidQueueGuard
   module Checks
     module Runtime
-      class QueueLagCheck < Base; end
+      class QueueLagCheck < Base
+        def call
+          with_queue_database do
+            lags = SolidQueue::ReadyExecution.group(:queue_name).minimum(:created_at)
+            return pass(check_id, 'No jobs waiting in ready queues') if lags.empty?
+
+            worst = lags.map do |queue_name, oldest|
+              lag = Time.current - oldest
+              { queue: queue_name, lag: lag, threshold: lag_threshold_for(queue_name) }
+            end.max_by { |entry| entry[:lag] }
+
+            if worst[:lag] > worst[:threshold]
+              failure(
+                check_id,
+                "#{worst[:queue]} queue lag is #{worst[:lag].to_i} seconds",
+                suggestion: "Investigate worker coverage and throughput for the #{worst[:queue]} queue",
+                metadata: { queue_lag_seconds: worst[:lag].to_i, queue_name: worst[:queue] }
+              )
+            elsif worst[:lag] > worst[:threshold] / 2
+              warn(
+                check_id,
+                "#{worst[:queue]} queue lag is #{worst[:lag].to_i} seconds",
+                metadata: { queue_lag_seconds: worst[:lag].to_i, queue_name: worst[:queue] }
+              )
+            else
+              pass(check_id, "Queue lag within thresholds (worst: #{worst[:queue]} at #{worst[:lag].to_i}s)")
+            end
+          end
+        end
+      end
     end
   end
 end

data/lib/solid_queue_guard/checks/runtime/recurring_stale_check.rb

@@ -3,7 +3,35 @@
 module SolidQueueGuard
   module Checks
     module Runtime
-      class RecurringStaleCheck < Base; end
+      class RecurringStaleCheck < Base
+        def call
+          with_queue_database do
+            tasks = SolidQueue::RecurringTask.static
+            return pass(check_id, 'No recurring tasks configured') if tasks.none?
+
+            stale_tasks = tasks.select do |task|
+              last_run = SolidQueue::RecurringExecution.where(task_key: task.key).maximum(:run_at)
+              last_run.nil? || last_run < expected_staleness.ago
+            end
+
+            if stale_tasks.any?
+              warn(
+                check_id,
+                "#{stale_tasks.size} recurring task(s) may be stale: #{stale_tasks.map(&:key).join(', ')}",
+                suggestion: 'Verify the scheduler process is running'
+              )
+            else
+              pass(check_id, 'Recurring tasks have recent executions')
+            end
+          end
+        end
+
+        private
+
+        def expected_staleness
+          config.stale_process_threshold * 2
+        end
+      end
     end
   end
 end

data/lib/solid_queue_guard/checks/runtime/scheduled_backlog_check.rb

@@ -3,7 +3,24 @@
 module SolidQueueGuard
   module Checks
     module Runtime
-      class ScheduledBacklogCheck < Base; end
+      class ScheduledBacklogCheck < Base
+        def call
+          with_queue_database do
+            due_count = SolidQueue::ScheduledExecution.due.count
+            threshold = config.scheduled_backlog_threshold
+
+            if due_count > threshold
+              warn(
+                check_id,
+                "Scheduled backlog is #{due_count} (threshold: #{threshold})",
+                suggestion: 'Check dispatcher health and scheduled job volume'
+              )
+            else
+              pass(check_id, "Scheduled backlog is #{due_count}")
+            end
+          end
+        end
+      end
     end
   end
 end

data/lib/solid_queue_guard/checks/runtime/stale_process_check.rb

@@ -3,7 +3,25 @@
 module SolidQueueGuard
   module Checks
     module Runtime
-      class StaleProcessCheck < Base; end
+      class StaleProcessCheck < Base
+        def call
+          with_queue_database do
+            threshold = config.stale_process_threshold
+            stale = SolidQueue::Process.where(last_heartbeat_at: ...threshold.ago)
+
+            if stale.none?
+              pass(check_id, 'All Solid Queue processes have recent heartbeats')
+            else
+              failure(
+                check_id,
+                "#{stale.count} Solid Queue process(es) have stale heartbeats",
+                suggestion: 'Restart the Solid Queue supervisor and verify workers are running',
+                metadata: { stale_processes: stale.count }
+              )
+            end
+          end
+        end
+      end
     end
   end
 end

data/lib/solid_queue_guard/cli.rb

@@ -18,9 +18,12 @@ module SolidQueueGuard
       strict = strict_flag?(argv) if strict.nil?
 
       report = Runner.new(scope: scope).run
+      Notifier.deliver_all(report) if notify?(report)
+      Metrics::Exporter.export(report) if SolidQueueGuard.config.metrics_backends.any?
+
       output = formatter_for(format).new(report).render
 
-      Rails.logger.debug output unless output.empty?
+      $stdout.puts(output) unless output.empty?
 
       exit report.exit_code(strict: strict)
     end
@@ -51,5 +54,11 @@ module SolidQueueGuard
         ENV.fetch('SOLID_QUEUE_GUARD_SCOPE', 'config').to_sym
       end
     end
+
+    def notify?(report)
+      return false unless SolidQueueGuard.config.notify_with.any?
+
+      report.status != :healthy
+    end
   end
 end

data/lib/solid_queue_guard/configuration.rb

@@ -11,7 +11,8 @@ module SolidQueueGuard
                   :health_cache_ttl,
                   :scheduled_backlog_threshold,
                   :integrate_rails_health,
-                  :notify_with
+                  :notify_with,
+                  :metrics_backends
 
     def initialize
       @enabled = true
@@ -24,6 +25,7 @@ module SolidQueueGuard
       @scheduled_backlog_threshold = 100
       @integrate_rails_health = false
       @notify_with = [:rails_logger]
+      @metrics_backends = []
     end
 
     def strict?

data/lib/solid_queue_guard/engine.rb

@@ -17,5 +17,17 @@ module SolidQueueGuard
         end
       end
     end
+
+    initializer 'solid_queue_guard.rails_health' do
+      next unless SolidQueueGuard.config.integrate_rails_health
+
+      ActiveSupport.on_load(:action_controller_base) do
+        Rails::HealthController.class_eval do
+          def solid_queue_guard_status
+            SolidQueueGuard::Health::Cache.fetch[:status]
+          end
+        end
+      end
+    end
   end
 end

data/lib/solid_queue_guard/formatters/terminal.rb

@@ -27,7 +27,7 @@ module SolidQueueGuard
       attr_reader :report
 
       def check_lines
-        report.results.map do |result|
+        report.results.reject(&:skip?).map do |result|
           icon = ICONS.fetch(result.status, '•')
           "#{icon} #{result.message}"
         end

data/lib/solid_queue_guard/health/cache.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module SolidQueueGuard
+  module Health
+    class Cache
+      def self.fetch
+        new.fetch
+      end
+
+      def fetch
+        Rails.cache.fetch(cache_key, expires_in: SolidQueueGuard.config.health_cache_ttl) do
+          build_payload
+        end
+      end
+
+      private
+
+      def cache_key
+        'solid_queue_guard/health'
+      end
+
+      def build_payload
+        report = Runner.new(scope: :all).run
+        Payload.new(report).to_h
+      end
+    end
+  end
+end

data/lib/solid_queue_guard/health/payload.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module SolidQueueGuard
+  module Health
+    class Payload
+      def initialize(report)
+        @report = report
+      end
+
+      def to_h
+        base = report.to_h.merge(
+          queue_lag_seconds: queue_lag_seconds,
+          failed_jobs_last_hour: failed_jobs_last_hour,
+          dead_processes: dead_processes
+        )
+
+        base[:recommendations] = topology_recommendations if topology_recommendations.any?
+        base
+      end
+
+      private
+
+      attr_reader :report
+
+      def queue_lag_seconds
+        metadata_value('queue_lag') { |metadata| metadata[:queue_lag_seconds] }
+      end
+
+      def failed_jobs_last_hour
+        metadata_value('failed_jobs') { |metadata| metadata[:failed_jobs_last_hour] } || 0
+      end
+
+      def dead_processes
+        metadata_value('stale_process') { |metadata| metadata[:stale_processes] } || 0
+      end
+
+      def metadata_value(check_id)
+        result = report.results.find { |entry| entry.id == check_id }
+        metadata = result&.metadata || {}
+        value = yield(metadata)
+        value unless value.nil?
+      end
+
+      def topology_recommendations
+        result = report.results.find { |entry| entry.id == 'topology_recommendation' }
+        result&.metadata&.fetch(:recommendations, []) || []
+      end
+    end
+  end
+end

data/lib/solid_queue_guard/metrics/exporter.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module SolidQueueGuard
+  module Metrics
+    class Exporter
+      STATUS_VALUES = { healthy: 0, degraded: 1, unhealthy: 2 }.freeze
+
+      def self.export(report, backends: SolidQueueGuard.config.metrics_backends)
+        new(report, backends: backends).export
+      end
+
+      def initialize(report, backends:)
+        @report = report
+        @backends = Array(backends)
+      end
+
+      def export
+        backends.each { |backend| export_backend(backend) }
+      end
+
+      private
+
+      attr_reader :report, :backends
+
+      def export_backend(backend)
+        case backend.to_sym
+        when :statsd then Statsd.export(report)
+        when :prometheus then Prometheus.export(report)
+        when :opentelemetry then OpenTelemetry.export(report)
+        end
+      end
+    end
+  end
+end

data/lib/solid_queue_guard/metrics/open_telemetry.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module SolidQueueGuard
+  module Metrics
+    module OpenTelemetry
+      module_function
+
+      def export(report)
+        return unless defined?(::OpenTelemetry)
+
+        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
+      end
+    end
+  end
+end

data/lib/solid_queue_guard/metrics/prometheus.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module SolidQueueGuard
+  module Metrics
+    module Prometheus
+      module_function
+
+      def export(report)
+        path = ENV.fetch('SOLID_QUEUE_GUARD_PROMETHEUS_FILE', Rails.root.join('tmp/solid_queue_guard.prom'))
+        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
+      end
+    end
+  end
+end

data/lib/solid_queue_guard/metrics/statsd.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module SolidQueueGuard
+  module Metrics
+    module Statsd
+      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)
+      ensure
+        socket&.close
+      end
+
+      def metric_line(report)
+        "solid_queue.guard.overall_status:#{STATUS_VALUES.fetch(report.status)}|g"
+      end
+
+      STATUS_VALUES = Exporter::STATUS_VALUES
+    end
+  end
+end

data/lib/solid_queue_guard/notifier.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module SolidQueueGuard
+  class Notifier
+    class << self
+      def deliver_all(report, adapters: SolidQueueGuard.config.notify_with)
+        Array(adapters).each do |adapter|
+          deliver(adapter, report)
+        end
+      end
+
+      def deliver(adapter, report)
+        case adapter.to_sym
+        when :slack then deliver_slack(report)
+        when :datadog then deliver_datadog(report)
+        when :webhook then deliver_webhook(report)
+        else deliver_rails_logger(report)
+        end
+      end
+
+      def post_json(url, payload, headers: {})
+        require 'net/http'
+        uri = URI(url)
+        request = Net::HTTP::Post.new(uri)
+        request['Content-Type'] = 'application/json'
+        headers.each { |key, value| request[key] = value }
+        request.body = JSON.generate(payload)
+        Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
+          http.request(request)
+        end
+      end
+
+      private
+
+      def deliver_rails_logger(report)
+        Rails.logger.warn("[SolidQueueGuard] status=#{report.status} warnings=#{report.warnings.join('; ')}")
+      end
+
+      def deliver_slack(report)
+        webhook_url = ENV.fetch('SOLID_QUEUE_GUARD_SLACK_WEBHOOK_URL', nil)
+        return if webhook_url.blank?
+
+        post_json(webhook_url, { text: "SolidQueueGuard status: *#{report.status}*\n#{report.warnings.join("\n")}" })
+      end
+
+      def deliver_datadog(report)
+        api_key = ENV.fetch('DD_API_KEY', nil)
+        return if api_key.blank?
+
+        alert_type = case report.status
+                     when :unhealthy then 'error'
+                     when :degraded then 'warning'
+                     else 'info'
+                     end
+
+        post_json(
+          'https://api.datadoghq.com/api/v1/events',
+          {
+            title: 'SolidQueueGuard alert',
+            text: report.warnings.join("\n"),
+            alert_type: alert_type,
+            tags: ["status:#{report.status}"]
+          },
+          headers: { 'DD-API-KEY' => api_key }
+        )
+      end
+
+      def deliver_webhook(report)
+        webhook_url = ENV.fetch('SOLID_QUEUE_GUARD_WEBHOOK_URL', nil)
+        return if webhook_url.blank?
+
+        post_json(webhook_url, report.to_h)
+      end
+    end
+  end
+end

data/lib/solid_queue_guard/notifiers/base.rb

@@ -4,14 +4,9 @@ module SolidQueueGuard
   module Notifiers
     # @api private
     class Base
-      def self.deliver(_report)
-        raise NotImplementedError, 'Notification adapters ship in v0.3'
+      def self.deliver(report)
+        Notifier.deliver(:rails_logger, report)
       end
     end
-
-    class RailsLogger < Base; end
-    class Slack < Base; end
-    class Datadog < Base; end
-    class Webhook < Base; end
   end
 end

data/lib/solid_queue_guard/recommendations/topology.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module SolidQueueGuard
+  module Recommendations
+    class Topology
+      def self.analyze(configuration: SolidQueue::Configuration.new)
+        new(configuration: configuration).analyze
+      end
+
+      def initialize(configuration:)
+        @configuration = configuration
+      end
+
+      def analyze
+        recommendations = []
+        recommendations.concat(worker_recommendations)
+        recommendations.concat(pool_recommendations)
+        recommendations.uniq
+      end
+
+      private
+
+      attr_reader :configuration
+
+      def worker_recommendations
+        worker_queues = QueueCoverage.worker_queues_from_configuration(configuration)
+        uncovered = uncovered_queues(worker_queues)
+        return [] if uncovered.empty?
+
+        ["Add worker coverage for: #{uncovered.join(', ')}"]
+      end
+
+      def pool_recommendations
+        required_threads = configuration.estimated_number_of_threads
+        pool_size = SolidQueue::Record.connection_pool&.size
+        return [] if pool_size.nil? || required_threads <= pool_size
+
+        ["Increase queue DB pool to at least #{required_threads + 2} (currently #{pool_size})"]
+      rescue StandardError
+        []
+      end
+
+      def uncovered_queues(assigned_queues)
+        observed = observed_queues
+        (observed - assigned_queues).sort
+      end
+
+      def observed_queues
+        return [] unless database_available?
+
+        SolidQueue::Job.distinct.pluck(:queue_name)
+      rescue StandardError
+        []
+      end
+
+      def database_available?
+        SolidQueue::Record.connection_pool&.with_connection(&:active?)
+      rescue StandardError
+        false
+      end
+    end
+  end
+end

data/lib/solid_queue_guard/tasks.rb

@@ -17,7 +17,7 @@ namespace :solid_queue_guard do
 
   desc 'Print machine-readable health status'
   task health: :environment do
-    SolidQueueGuard::CLI.run!(scope: :config, format: :json, strict: cli_strict)
+    SolidQueueGuard::CLI.run!(scope: :all, format: :json, strict: cli_strict)
   end
 
   desc 'Print full diagnostic report. Usage: report[json]'

data/lib/solid_queue_guard/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: solid_queue_guard
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Rafael Pissardo
@@ -290,10 +290,12 @@ files:
 - lib/solid_queue_guard/checks/config/queue_schema_check.rb
 - lib/solid_queue_guard/checks/config/scheduler_config_check.rb
 - lib/solid_queue_guard/checks/config/thread_pool_check.rb
+- lib/solid_queue_guard/checks/config/topology_recommendation_check.rb
 - lib/solid_queue_guard/checks/config/worker_coverage_check.rb
 - lib/solid_queue_guard/checks/registry.rb
 - lib/solid_queue_guard/checks/runtime/base.rb
 - lib/solid_queue_guard/checks/runtime/blocked_jobs_check.rb
+- lib/solid_queue_guard/checks/runtime/database_support.rb
 - lib/solid_queue_guard/checks/runtime/dispatcher_check.rb
 - lib/solid_queue_guard/checks/runtime/failed_jobs_check.rb
 - lib/solid_queue_guard/checks/runtime/finished_jobs_growth_check.rb
@@ -310,8 +312,16 @@ files:
 - lib/solid_queue_guard/engine.rb
 - lib/solid_queue_guard/formatters/json.rb
 - lib/solid_queue_guard/formatters/terminal.rb
+- lib/solid_queue_guard/health/cache.rb
+- lib/solid_queue_guard/health/payload.rb
+- lib/solid_queue_guard/metrics/exporter.rb
+- lib/solid_queue_guard/metrics/open_telemetry.rb
+- lib/solid_queue_guard/metrics/prometheus.rb
+- lib/solid_queue_guard/metrics/statsd.rb
+- lib/solid_queue_guard/notifier.rb
 - lib/solid_queue_guard/notifiers/base.rb
 - lib/solid_queue_guard/queue_coverage.rb
+- lib/solid_queue_guard/recommendations/topology.rb
 - lib/solid_queue_guard/report.rb
 - lib/solid_queue_guard/runner.rb
 - lib/solid_queue_guard/tasks.rb