solid_queue_guard 1.4.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0f68d16b641aa34f7cf2cda0731e1f279d4078466271f25bdac801d812a1c050
-  data.tar.gz: d9765f83f9e100ec1508603cc6e6c461ca5835a925d32ef30b993d122eafb6ce
+  metadata.gz: 5d166e1caf2f2d8d5b70a3e3286eae29fcc54d86aa13d75d98d22c66948461f3
+  data.tar.gz: cf506ca78e106a3471afb9d7b5d76c316390d32c534ca57a0ea14bd94e4212e0
 SHA512:
-  metadata.gz: 24f148012d857a399cb27ceab0ca17ed9b09e4215610e82aa96d9bbb2fa9b84b05b85e63723ffbe7edd57d65cb8c3ed81305ee0e2650ffb798aeffd55bbc1c11
-  data.tar.gz: bcd5ab443291828fbf19100ded2010d54d5d57cf764390623ca5e67d4291fb80c1fca37e5498ada656dfc95e184d8484e0a17e4763a0052f634a186980961bff
+  metadata.gz: 4ebab9e0becb3c9f275b2797e6e51eb71fc79fe8af88a1c088e307840ec11568fbe975f0b9015168aaf0e6eb1cf6eff05e3ab8e59cad1733d6cd650003d14941
+  data.tar.gz: 78cfc87e754be0ae63ee59ca41c79d905a37af6b4c1b7c2b67f47b51ddb55813368b4048855a02cdb10922717e6151642c919ff1c765dd5a6bfefbb0eb548449

data/CHANGELOG.md

@@ -5,6 +5,21 @@ 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.5.0] - 2026-08-04
+
+### Added
+
+- Operational Datadog metrics for Solid Queue depth and job events (opt-in):
+  - `config.emit_depth_metrics` — recurring gauges `solid_queue.ready.count`,
+    `solid_queue.ready.oldest_age_seconds`, `failed` / `claimed` / `scheduled` counts
+    via `SolidQueueGuard::Metrics::EmitDepthJob` (same DB source as Mission Control)
+  - `config.emit_event_metrics` — Active Job + Solid Queue lifecycle counters
+    (`solid_queue.jobs.*`, `solid_queue.job.duration_ms`, `solid_queue.process.active`)
+  - `config.statsd_service_name` (falls back to `DD_SERVICE` / `SOLID_QUEUE_GUARD_SERVICE`)
+  - Generator: `bin/rails generate solid_queue_guard:metrics` wires flags + `recurring.yml`
+- Requires optional gem `dogstatsd-ruby` (`Datadog::Statsd`). Distinct from
+  `config.metrics_backends` health-check export (`solid_queue.guard.*`).
+
 ## [1.4.0] - 2026-08-03
 
 ### Changed

data/Gemfile.lock

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

data/README.md

@@ -124,6 +124,19 @@ Requires `mission_control-jobs` and an asset pipeline (Propshaft or Sprockets).
 
 ---
 
+## Operational Datadog metrics
+
+Opt-in continuous depth gauges (same DB source as Mission Control) plus Active Job event counters:
+
+```bash
+bundle add dogstatsd-ruby
+bin/rails generate solid_queue_guard:metrics
+```
+
+Emits `solid_queue.ready.count`, `solid_queue.ready.oldest_age_seconds`, failed/claimed/scheduled counts, and `solid_queue.jobs.*` — see [docs/configuration.md](docs/configuration.md).
+
+---
+
 ## Public API (v1.0+)
 
 Stable until `2.0` — [semantic versioning](https://semver.org/):
@@ -135,6 +148,8 @@ Stable until `2.0` — [semantic versioning](https://semver.org/):
 | `solid_queue_guard:report` | Full diagnostic report |
 | `mount SolidQueueGuard::Engine` | HTTP health endpoint |
 | `config.integrate_mission_control` | Guard tab (requires `mission_control-jobs`) |
+| `config.emit_depth_metrics` / `emit_event_metrics` | Operational Datadog gauges/counters (requires `dogstatsd-ruby`) |
+| `bin/rails generate solid_queue_guard:metrics` | Wire depth recurring job + event flags |
 
 Internal check classes and registry are `@api private`.
 

data/app/helpers/solid_queue_guard/mission_control/dashboard_helper.rb

@@ -8,7 +8,7 @@ module SolidQueueGuard
         when 'healthy', 'pass' then 'is-success'
         when 'degraded', 'warn' then 'is-warning'
         when 'unhealthy', 'fail' then 'is-danger'
-        else 'is-light'
+        else 'is-dark' # skip / unknown — is-light is unreadable on Mission Control dark theme
         end
       end
 

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

@@ -26,4 +26,10 @@ SolidQueueGuard.configure do |config|
   # config.on_status_change = ->(previous, current, report) { ... }
   # config.notify_with = [:rails_logger, :slack, :datadog, :webhook]
   # config.metrics_backends = [:statsd, :prometheus, :opentelemetry]
+
+  # Operational Datadog metrics (depth gauges + job event counters).
+  # Requires dogstatsd-ruby. Enable with: bin/rails generate solid_queue_guard:metrics
+  # config.emit_depth_metrics = true
+  # config.emit_event_metrics = true
+  # config.statsd_service_name = 'my-service' # or set DD_SERVICE
 end

data/lib/generators/solid_queue_guard/metrics/metrics_generator.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require 'rails/generators/base'
+
+module SolidQueueGuard
+  module Generators
+    class MetricsGenerator < Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+
+      RECURRING_SNIPPET = <<~YAML
+        emit_solid_queue_depth_metrics:
+          class: SolidQueueGuard::Metrics::EmitDepthJob
+          queue: solid_queue_recurring
+          schedule: every 15 seconds
+      YAML
+
+      CONFIG_SNIPPET = <<~RUBY
+
+        # Operational Datadog metrics (requires dogstatsd-ruby)
+        config.emit_depth_metrics = true
+        config.emit_event_metrics = true
+        # config.statsd_service_name = 'my-service' # or set DD_SERVICE
+      RUBY
+
+      desc 'Enables Solid Queue operational metrics (depth gauges + event counters) and wires recurring.yml'
+
+      def enable_config_flags
+        initializer = 'config/initializers/solid_queue_guard.rb'
+        full_path = File.expand_path(initializer, destination_root)
+
+        unless File.exist?(full_path)
+          say_status :error, "#{initializer} not found — run solid_queue_guard:install first", :red
+          return
+        end
+
+        contents = File.read(full_path)
+        if contents.include?('emit_depth_metrics')
+          say_status :identical, "#{initializer} already enables depth metrics", :blue
+          return
+        end
+
+        inject_into_file initializer, before: /\nend\s*\z/ do
+          CONFIG_SNIPPET
+        end
+      end
+
+      def add_recurring_task
+        relative = 'config/recurring.yml'
+        path = File.expand_path(relative, destination_root)
+
+        unless File.exist?(path)
+          say_status :skip, "#{relative} not found", :yellow
+          return
+        end
+
+        content = File.read(path)
+        if content.include?('emit_solid_queue_depth_metrics')
+          say_status :identical, "#{relative} already has emit_solid_queue_depth_metrics", :blue
+          return
+        end
+
+        updated = insert_recurring_snippet(content)
+        File.write(path, updated)
+        say_status :insert, "#{relative} (emit_solid_queue_depth_metrics)", :green
+      end
+
+      def remind_dependency
+        say <<~MSG
+
+          Add to your Gemfile if missing:
+            gem 'dogstatsd-ruby'
+
+          Ensure a Solid Queue worker consumes the `solid_queue_recurring` queue,
+          then deploy and verify:
+            solid_queue.ready.count{service:<your-service>}
+        MSG
+      end
+
+      private
+
+      def insert_recurring_snippet(content)
+        indented = RECURRING_SNIPPET.lines.map { |line| line == "\n" ? line : "  #{line}" }.join
+
+        if content.match?(/^default:/)
+          content.sub(/^(default:(?: &\w+)?\n(?:  .*\n)*)/) do |block|
+            "#{block.rstrip}\n#{indented}"
+          end
+        else
+          "#{content.rstrip}\n\n#{RECURRING_SNIPPET}"
+        end
+      end
+    end
+  end
+end

data/lib/solid_queue_guard/configuration.rb

@@ -22,7 +22,10 @@ module SolidQueueGuard
                   :checks,
                   :degraded_http_status,
                   :unhealthy_http_status,
-                  :on_status_change
+                  :on_status_change,
+                  :emit_depth_metrics,
+                  :emit_event_metrics,
+                  :statsd_service_name
 
     def initialize
       @enabled = true
@@ -42,6 +45,9 @@ module SolidQueueGuard
       @degraded_http_status = :ok
       @unhealthy_http_status = :service_unavailable
       @on_status_change = nil
+      @emit_depth_metrics = false
+      @emit_event_metrics = false
+      @statsd_service_name = nil
     end
 
     def validate!

data/lib/solid_queue_guard/engine.rb

@@ -51,5 +51,11 @@ module SolidQueueGuard
         SolidQueueGuard::MissionControl::Integration.install_navigation!
       end
     end
+
+    initializer 'solid_queue_guard.event_metrics' do
+      config.after_initialize do
+        SolidQueueGuard::Metrics::EventInstrumentation.install!
+      end
+    end
   end
 end

data/lib/solid_queue_guard/metrics/depth_emitter.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module SolidQueueGuard
+  module Metrics
+    # Snapshot gauges answering "are jobs stuck right now?"
+    # (same DB source as Mission Control /jobs).
+    module DepthEmitter
+      module_function
+
+      def emit!
+        return unless enabled?
+
+        emit_ready_gauges!
+        emit_execution_gauges!
+        statsd.flush if statsd.respond_to?(:flush)
+      end
+
+      def enabled?
+        SolidQueueGuard.config.emit_depth_metrics &&
+          %w[production staging].include?(Rails.env.to_s)
+      end
+
+      def statsd
+        DogstatsdClient.statsd
+      end
+
+      def emit_ready_gauges!
+        ready_counts = SolidQueue::ReadyExecution.group(:queue_name).count
+        oldest_by_queue = SolidQueue::ReadyExecution.group(:queue_name).minimum(:created_at)
+
+        if ready_counts.empty?
+          statsd.gauge('solid_queue.ready.count', 0)
+          statsd.gauge('solid_queue.ready.oldest_age_seconds', 0)
+          return
+        end
+
+        emit_ready_counts!(ready_counts)
+        emit_ready_ages!(oldest_by_queue)
+      end
+
+      def emit_ready_counts!(ready_counts)
+        ready_counts.each do |queue_name, count|
+          statsd.gauge('solid_queue.ready.count', count, tags: ["queue:#{queue_name}"])
+        end
+      end
+
+      def emit_ready_ages!(oldest_by_queue)
+        now = Time.current
+        oldest_by_queue.each do |queue_name, created_at|
+          age = created_at ? [(now - created_at).to_i, 0].max : 0
+          statsd.gauge('solid_queue.ready.oldest_age_seconds', age, tags: ["queue:#{queue_name}"])
+        end
+      end
+
+      def emit_execution_gauges!
+        statsd.gauge('solid_queue.failed.count', SolidQueue::FailedExecution.count)
+        statsd.gauge('solid_queue.claimed.count', SolidQueue::ClaimedExecution.count)
+        statsd.gauge('solid_queue.scheduled.count', SolidQueue::ScheduledExecution.count)
+      end
+    end
+  end
+end

data/lib/solid_queue_guard/metrics/dogstatsd_client.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module SolidQueueGuard
+  module Metrics
+    # Shared Datadog StatsD client for operational gauges/counters.
+    # Distinct from Metrics::Statsd (raw UDP export of guard check status).
+    module DogstatsdClient
+      module_function
+
+      def statsd
+        @statsd ||= build_client
+      end
+
+      def reset!
+        @statsd = nil
+        remove_instance_variable(:@available) if instance_variable_defined?(:@available)
+      end
+
+      def available?
+        return @available if instance_variable_defined?(:@available)
+
+        @available = OptionalDependency.require!('datadog/statsd', 'dogstatsd-ruby')
+      end
+
+      def service_name
+        SolidQueueGuard.config.statsd_service_name.presence ||
+          ENV['DD_SERVICE'].presence ||
+          ENV['SOLID_QUEUE_GUARD_SERVICE'].presence
+      end
+
+      def default_tags
+        tags = ["env:#{Rails.env}"]
+        tags << "service:#{service_name}" if service_name
+        tags
+      end
+
+      def job_tags(job)
+        ["job_class:#{job.class.name}", "queue:#{job.queue_name}"]
+      end
+
+      def process_tags(kind, process)
+        ["kind:#{kind}", "process:#{process.name}"]
+      end
+
+      def build_client
+        return NullStatsd.new unless available?
+
+        ::Datadog::Statsd.new(tags: default_tags)
+      end
+      private_class_method :build_client
+
+      # No-op client when dogstatsd-ruby is not installed.
+      class NullStatsd
+        def increment(*) = nil
+        def gauge(*) = nil
+        def timing(*) = nil
+        def flush = nil
+      end
+    end
+  end
+end

data/lib/solid_queue_guard/metrics/emit_depth_job.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module SolidQueueGuard
+  module Metrics
+    # Host apps have ApplicationJob; this gem job inherits ActiveJob::Base directly.
+    class EmitDepthJob < ::ActiveJob::Base # rubocop:disable Rails/ApplicationJob
+      queue_as :solid_queue_recurring
+
+      def perform
+        DepthEmitter.emit!
+      end
+    end
+  end
+end

data/lib/solid_queue_guard/metrics/event_instrumentation.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module SolidQueueGuard
+  module Metrics
+    # Subscribes to Active Job notifications and Solid Queue lifecycle hooks.
+    # Opt-in via config.emit_event_metrics = true.
+    module EventInstrumentation
+      class << self
+        def install!
+          return if @installed
+          return unless SolidQueueGuard.config.emit_event_metrics
+          return unless %w[production staging].include?(Rails.env.to_s)
+          return unless DogstatsdClient.available?
+
+          subscribe_active_job!
+          subscribe_solid_queue_lifecycle!
+          @installed = true
+        end
+
+        def reset!
+          @installed = false
+        end
+
+        private
+
+        def subscribe_active_job!
+          subscribe_enqueue!
+          subscribe_perform!
+          subscribe_retry_lifecycle!
+        end
+
+        def subscribe_enqueue!
+          ActiveSupport::Notifications.subscribe('enqueue.active_job') do |event|
+            job = event.payload.fetch(:job)
+            DogstatsdClient.statsd.increment(
+              'solid_queue.jobs.enqueued',
+              tags: DogstatsdClient.job_tags(job)
+            )
+          end
+        end
+
+        def subscribe_perform!
+          ActiveSupport::Notifications.subscribe('perform.active_job') do |event|
+            job = event.payload.fetch(:job)
+            status = event.payload[:exception_object] || event.payload[:exception] ? 'error' : 'success'
+            tags = [*DogstatsdClient.job_tags(job), "status:#{status}"]
+
+            DogstatsdClient.statsd.increment('solid_queue.jobs.performed', tags:)
+            DogstatsdClient.statsd.timing('solid_queue.job.duration_ms', event.duration, tags:)
+          end
+        end
+
+        def subscribe_retry_lifecycle!
+          %w[enqueue_retry retry_stopped discard].each do |event_name|
+            ActiveSupport::Notifications.subscribe("#{event_name}.active_job") do |event|
+              job = event.payload.fetch(:job)
+              DogstatsdClient.statsd.increment(
+                "solid_queue.jobs.#{event_name}",
+                tags: DogstatsdClient.job_tags(job)
+              )
+            end
+          end
+        end
+
+        def subscribe_solid_queue_lifecycle!
+          {
+            worker: %i[on_worker_start on_worker_stop],
+            dispatcher: %i[on_dispatcher_start on_dispatcher_stop],
+            scheduler: %i[on_scheduler_start on_scheduler_stop]
+          }.each do |kind, (start_hook, stop_hook)|
+            SolidQueue.public_send(start_hook) do |process|
+              DogstatsdClient.statsd.gauge(
+                'solid_queue.process.active',
+                1,
+                tags: DogstatsdClient.process_tags(kind, process)
+              )
+            end
+            SolidQueue.public_send(stop_hook) do |process|
+              DogstatsdClient.statsd.gauge(
+                'solid_queue.process.active',
+                0,
+                tags: DogstatsdClient.process_tags(kind, process)
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/solid_queue_guard/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: solid_queue_guard
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.5.0
 platform: ruby
 authors:
 - Rafael Pissardo
@@ -325,6 +325,7 @@ files:
 - lib/generators/solid_queue_guard/install/install_generator.rb
 - lib/generators/solid_queue_guard/install/templates/solid_queue_guard.rb
 - lib/generators/solid_queue_guard/install/templates/solid_queue_guard.yml
+- lib/generators/solid_queue_guard/metrics/metrics_generator.rb
 - lib/solid_queue_guard.rb
 - lib/solid_queue_guard/check/result.rb
 - lib/solid_queue_guard/checks/base.rb
@@ -365,6 +366,10 @@ files:
 - lib/solid_queue_guard/health/cache.rb
 - lib/solid_queue_guard/health/payload.rb
 - lib/solid_queue_guard/http_status_policy.rb
+- lib/solid_queue_guard/metrics/depth_emitter.rb
+- lib/solid_queue_guard/metrics/dogstatsd_client.rb
+- lib/solid_queue_guard/metrics/emit_depth_job.rb
+- lib/solid_queue_guard/metrics/event_instrumentation.rb
 - lib/solid_queue_guard/metrics/exporter.rb
 - lib/solid_queue_guard/metrics/open_telemetry.rb
 - lib/solid_queue_guard/metrics/prometheus.rb