okcomputer 1.19.2 → 1.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6b698c4f15d160137298b7023a1c8e661f6f4a49f2378a8aae23e2451e012306
-  data.tar.gz: 315252dc778cb44706720dbab9420f778e237e7350e388640889b06c260c9490
+  metadata.gz: ff40aaa50d94381ec00151daa8e8f06007dd371275c41606daf292a74f9a5b92
+  data.tar.gz: 8fdf9fe8d7fb3f3b12bc80f921bd240f883de707b8fa3960f2c3297436eda242
 SHA512:
-  metadata.gz: 2ded6dc9dfa8d24a9adb8fe80826e403a9cb408818ebb5d8bf504f7390e848e498448b50c5c4af4dfd60d28ab5ef975803b51126b48f53c40839968e5580945c
-  data.tar.gz: '087e5ae51b7fa551879135a86819dd2d95c28b1edaf35c716b4f9c4408fb9cf02238225f7ccd6fe214b117ee6eed0e16d9656a3a04a9a9370c76646b7f7136b0'
+  metadata.gz: 1e82ee5929483cd2dd98af763bfcd71e1a15a02d0e5d9800e6d14155563a73cf2a1d1cd3a181e603495089f713d250455030063d0ef391434d2be7ff0bea8817
+  data.tar.gz: 26c74cd196d72d6747b27eea7212efd49699dcb38ef1c848b1c85213f978f97fc80f32614f0c4969883670fadf2bff08a237c65db2dd5df0a796eb7d198f7c6d

data/README.markdown

@@ -15,22 +15,19 @@ your own custom checks.
 For more insight into why we built this, check out [our blog post introducing
 OkComputer](http://pulse.sportngin.com/news_article/show/267646?referrer_id=543230).
 
-OkComputer currently fully supports the following Rails versions:
+OkComputer supports the following Rails versions, as tested by the CI build matrix:
 
+* 8.1
+* 8.0
+* 7.2
+* 7.1
 * 7.0
 * 6.1
 * 6.0
 * 5.2
 * 5.1
-* 4.2
-
-In addition, the CI tests are passing on, but is not guaranteed to work with, the following Rails versions:
-
-* 8.1
-* 8.0
-* 7.2
-* 7.1
 * 5.0
+* 4.2
 * 4.1
 * 4.0
 
@@ -60,8 +57,43 @@ $ gem install okcomputer
 
 ## Usage
 
-To perform the default checks (application running and ActiveRecord database
-connection), do nothing other than adding to your application's Gemfile.
+Adding OkComputer to your Gemfile mounts its routes at `/okcomputer` and
+registers a simple application check named `default`. When ActiveRecord is
+loaded, it also registers an ActiveRecord connection check named
+`database`. If Sequel is loaded instead, it registers a Sequel database check.
+
+Test the application check without any additional configuration:
+
+```
+$ curl http://localhost:3000/okcomputer
+default: PASSED Application is running (0.000s)
+```
+
+### Endpoints
+
+| Endpoint | Checks performed |
+| --- | --- |
+| `/okcomputer` | The `default` application check |
+| `/okcomputer/database` | The registered `database` check, when present |
+| `/okcomputer/all` | All checks and collections in the default collection, except those registered with `skip_all: true` |
+| `/okcomputer/:name` | The registered check or collection named `:name` |
+
+A successful check returns HTTP 200. A failed check, or an aggregate containing
+a failed check, returns HTTP 500. Requesting an unregistered check returns HTTP
+404.
+
+Responses are plain text by default. Append `.json` or send an
+`Accept: application/json` header to receive JSON:
+
+```json
+{
+  "default": {
+    "message": "Application is running",
+    "success": true,
+    "time": 0.000123
+  }
+}
+```
 
 ### If Not Using ActiveRecord
 
@@ -141,6 +173,22 @@ OkComputer::Registry.register "resque_scheduler_down", OkComputer::ResqueSchedul
 
 # If you're using SolidCache instead of Memcached, use this check instead of CacheCheck
 OkComputer::Registry.register "cache", OkComputer::CacheCheckSolidCache.new
+
+# If you're using SolidQueue, these checks monitor its health and throughput.
+OkComputer::Registry.register "solid_queue", OkComputer::SolidQueueCheck.new
+
+# Optionally, alert when a specific queue's backlog of ready jobs gets too high:
+OkComputer::Registry.register "solid_queue_backed_up", OkComputer::SolidQueueBackedUpCheck.new("default", 100)
+
+# Optionally, alert when scheduled jobs are overdue — a sign the dispatcher has
+# stalled and is not promoting jobs to ready.
+OkComputer::Registry.register "solid_queue_scheduled_backed_up", OkComputer::SolidQueueScheduledBackedUpCheck.new(0, grace: 2.minutes)
+
+# Optionally, alert when too many jobs have failed in total:
+OkComputer::Registry.register "solid_queue_failed_jobs", OkComputer::SolidQueueFailedJobsCheck.new(25)
+
+# Optionally, alert on a rapid increase in failures (more than 10 failures in 300 sec)
+OkComputer::Registry.register "solid_queue_failed_jobs_rate", OkComputer::SolidQueueFailedJobsRateCheck.new(10, 300)
 ```
 
 ### Registering Custom Checks
@@ -166,6 +214,32 @@ end
 OkComputer::Registry.register "check_for_odds", MyCustomCheck.new
 ```
 
+### Grouping Checks
+
+Use a `CheckCollection` to expose several related checks from one endpoint. Register
+the collection with `skip_all: true` when the group should not run as part of the
+default `/okcomputer/all` endpoint:
+
+```ruby
+# config/initializers/okcomputer.rb
+versions = OkComputer::CheckCollection.new("Versions")
+
+OkComputer::Registry.register "versions", versions, skip_all: true
+OkComputer::Registry.register "ruby_version", OkComputer::RubyVersionCheck.new, "versions"
+OkComputer::Registry.register "app_version", OkComputer::AppVersionCheck.new, "versions"
+```
+
+The group is available at `/okcomputer/versions` and `/okcomputer/versions.json`.
+Its checks remain individually available, but neither the group nor its checks run
+at `/okcomputer/all`.
+
+An individual check can also be omitted from `/okcomputer/all` while retaining its
+own endpoint:
+
+```ruby
+OkComputer::Registry.register "ruby_version", OkComputer::RubyVersionCheck.new, skip_all: true
+```
+
 ### Registering Optional Checks
 
 Register an optional check like so:
@@ -196,16 +270,6 @@ By default, OkComputer runs checks in sequence. If you'd like to run them in par
 OkComputer.check_in_parallel = true
 ```
 
-## Performing Checks
-
-* Perform a simple up check: http://example.com/okcomputer
-* Perform all installed checks: http://example.com/okcomputer/all
-* Perform a specific installed check: http://example.com/okcomputer/database
-
-Checks are available as plain text (by default) or JSON by appending .json, e.g.:
-* http://example.com/okcomputer.json
-* http://example.com/okcomputer/all.json
-
 ## OkComputer NewRelic Ignore
 
 If NewRelic is installed, OkComputer automatically disables NewRelic monitoring for uptime checks,

data/lib/ok_computer/built_in_checks/action_mailer_check.rb

@@ -14,11 +14,34 @@ module OkComputer
 
     # Public: Return the status of the check
     def check
-      tcp_socket_request
-      mark_message "#{klass} check to #{host}:#{port} successful"
-    rescue => e
-      mark_message "#{klass} at #{host}:#{port} is not accepting connections: '#{e}'"
-      mark_failure
+      case klass.delivery_method
+      when :smtp
+        begin
+          tcp_socket_request
+          mark_message "#{klass} check to #{host}:#{port} successful"
+        rescue => e
+          mark_message "#{klass} at #{host}:#{port} is not accepting connections: '#{e}'"
+          mark_failure
+        end
+      when :sendmail
+        begin
+          location = klass.sendmail_settings[:location]
+          if File.executable?(location)
+            mark_message "#{klass} sendmail executable #{location} can be executed"
+          else
+            mark_message "#{klass} sendmail executable #{location} is not executable"
+            mark_failure
+          end
+        rescue => e
+          mark_message "#{klass} error checking sendmail executable: '#{e}'"
+          mark_failure
+        end
+      when :test
+        mark_message "#{klass} is in test mode"
+      else
+        mark_message "unknown delivery method #{klass.delivery_method}"
+        mark_failure
+      end
     end
   end
 end

data/lib/ok_computer/built_in_checks/solid_queue_backed_up_check.rb

@@ -0,0 +1,22 @@
+module OkComputer
+  class SolidQueueBackedUpCheck < SizeThresholdCheck
+    attr_accessor :queue
+    attr_accessor :threshold
+
+    # Public: Initialize a check for a backed-up SolidQueue queue
+    #
+    # queue - The name of the SolidQueue queue to check
+    # threshold - An Integer to compare the queue's number of ready jobs
+    #   against to consider it backed up
+    def initialize(queue, threshold)
+      self.queue = queue
+      self.threshold = Integer(threshold)
+      self.name = "SolidQueue queue '#{queue}'"
+    end
+
+    # Public: The number of ready (pending) jobs in the check's queue
+    def size
+      SolidQueue::Queue.new(queue).size
+    end
+  end
+end

data/lib/ok_computer/built_in_checks/solid_queue_check.rb

@@ -0,0 +1,66 @@
+module OkComputer
+  # Verifies that SolidQueue is up and processing jobs by confirming that at
+  # least one worker process has a recent heartbeat, and reports a summary of
+  # the current job counts.
+  #
+  # See https://github.com/rails/solid_queue
+  class SolidQueueCheck < Check
+    # Public: Check whether SolidQueue has live workers and a live dispatcher,
+    # and report job stats
+    def check
+      if live_workers.zero?
+        mark_failure
+        mark_message "SolidQueue is DOWN. No workers are alive. (#{stats})"
+      elsif live_dispatchers.zero?
+        mark_failure
+        mark_message "SolidQueue dispatcher is DOWN. Scheduled jobs will not run. (#{stats})"
+      else
+        mark_message "SolidQueue is up (#{live_workers} worker(s), #{live_dispatchers} dispatcher(s) alive). Job Counts: #{stats}"
+      end
+    rescue => e
+      mark_failure
+      mark_message "Error: '#{e}'"
+    end
+
+    # Public: The number of worker processes whose heartbeat is within
+    # SolidQueue's configured alive threshold (default: 5 minutes)
+    def live_workers
+      alive_processes.where(kind: "Worker").count
+    end
+
+    # Public: The number of dispatcher processes whose heartbeat is recent enough
+    # to be considered alive
+    def live_dispatchers
+      alive_processes.where(kind: "Dispatcher").count
+    end
+
+    # Public: A summary of the current job counts across SolidQueue
+    def stats
+      "ready: #{ready}, scheduled: #{scheduled}, in progress: #{in_progress}, failed: #{failed}"
+    end
+
+    private
+
+    # SolidQueue::Process records that have sent a heartbeat recently enough to
+    # be considered alive. Mirrors SolidQueue's own Prunable logic.
+    def alive_processes
+      SolidQueue::Process.where("last_heartbeat_at > ?", SolidQueue.process_alive_threshold.ago)
+    end
+
+    def ready
+      SolidQueue::ReadyExecution.count
+    end
+
+    def scheduled
+      SolidQueue::ScheduledExecution.count
+    end
+
+    def in_progress
+      SolidQueue::ClaimedExecution.count
+    end
+
+    def failed
+      SolidQueue::FailedExecution.count
+    end
+  end
+end

data/lib/ok_computer/built_in_checks/solid_queue_failed_jobs_check.rb

@@ -0,0 +1,19 @@
+module OkComputer
+  class SolidQueueFailedJobsCheck < SizeThresholdCheck
+    attr_accessor :threshold
+
+    # Public: Initialize a check for the total number of failed SolidQueue jobs
+    #
+    # threshold - An Integer to compare the failed job count against to
+    #   consider it over threshold
+    def initialize(threshold)
+      self.threshold = Integer(threshold)
+      self.name = "SolidQueue Failed Jobs"
+    end
+
+    # Public: The total number of failed jobs
+    def size
+      SolidQueue::FailedExecution.count
+    end
+  end
+end

data/lib/ok_computer/built_in_checks/solid_queue_failed_jobs_rate_check.rb

@@ -0,0 +1,29 @@
+module OkComputer
+  # Detects rapid increases in failed SolidQueue jobs by counting failures
+  # that occurred within a rolling time window, rather than the total
+  # accumulated failures. This is stateless across requests: it relies on the
+  # created_at timestamp of each failed execution.
+  class SolidQueueFailedJobsRateCheck < SizeThresholdCheck
+    attr_accessor :threshold
+    attr_accessor :window
+
+    # Public: Initialize a check for the rate of failing SolidQueue jobs
+    #
+    # threshold - An Integer number of failures within the window to tolerate
+    #   before the check is considered failed
+    # window - The size of the rolling window to count failures within. Accepts
+    #   either a number of seconds or an ActiveSupport::Duration (e.g.
+    #   5.minutes). Defaults to 300 seconds (5 minutes).
+    def initialize(threshold, window = 300)
+      self.threshold = Integer(threshold)
+      self.window = window
+      self.name = "SolidQueue Failed Jobs Rate"
+    end
+
+    # Public: The number of jobs that have failed within the window
+    def size
+      cutoff = window.respond_to?(:ago) ? window.ago : Time.now - window
+      SolidQueue::FailedExecution.where("created_at > ?", cutoff).count
+    end
+  end
+end

data/lib/ok_computer/built_in_checks/solid_queue_scheduled_backed_up_check.rb

@@ -0,0 +1,33 @@
+module OkComputer
+  # Detects a stalled SolidQueue dispatcher by counting scheduled jobs that are
+  # overdue — i.e. their scheduled_at is more than `grace` in the past, so a
+  # healthy dispatcher should already have promoted them to ready_executions.
+  #
+  # This is distinct from SolidQueueBackedUpCheck, which measures ready (already
+  # promoted) depth. A dead/behind dispatcher leaves jobs stuck in scheduled and
+  # invisible to that check; this check surfaces them.
+  class SolidQueueScheduledBackedUpCheck < SizeThresholdCheck
+    attr_accessor :threshold
+    attr_accessor :grace
+
+    # Public: Initialize a check for overdue scheduled SolidQueue jobs
+    #
+    # threshold - An Integer; the number of overdue scheduled jobs to tolerate
+    #   before considering the dispatcher backed up.
+    # grace - An ActiveSupport::Duration; how far past scheduled_at a job must be
+    #   before it counts as overdue. The dispatcher polls roughly every second
+    #   (config/queue.yml polling_interval), so sub-poll lateness is normal and a
+    #   grace window prevents flapping. Defaults to 1 minute.
+    def initialize(threshold, grace: 1.minute)
+      self.threshold = Integer(threshold)
+      self.grace = grace
+      self.name = "SolidQueue overdue scheduled jobs"
+    end
+
+    # Public: Count of scheduled jobs overdue by more than `grace`. A healthy
+    # dispatcher keeps this at 0.
+    def size
+      SolidQueue::ScheduledExecution.where("scheduled_at <= ?", grace.ago).count
+    end
+  end
+end

data/lib/ok_computer/check.rb

@@ -3,7 +3,7 @@ require "benchmark"
 module OkComputer
   class Check
     # to be set by Registry upon registration
-    attr_accessor :registrant_name
+    attr_accessor :registrant_name, :skip_all
     # nil by default, only set to true if the check deems itself failed
     attr_accessor :failure_occurred
     # nil by default, set by #check to control the output

data/lib/ok_computer/check_collection.rb

@@ -1,13 +1,16 @@
 module OkComputer
   class CheckCollection
-    attr_accessor :collection, :registrant_name, :display
+    attr_accessor :collection, :registrant_name, :display, :skip_all
 
     # Public: Initialize a new CheckCollection
     #
     # display - the display name for the Check Collection
-    def initialize(display)
+    # exclude_skipped_checks - whether checks marked skip_all should be omitted
+    def initialize(display, exclude_skipped_checks=false)
       self.display = display
       self.collection = {}
+      self.skip_all = false
+      @exclude_skipped_checks = exclude_skipped_checks
     end
 
     # Public: Run the collection's checks
@@ -37,7 +40,7 @@ module OkComputer
     #
     # Returns an Array of the collection's values
     def checks
-      collection.values
+      included_collection.values
     end
 
     def <=>(check)
@@ -51,13 +54,13 @@ module OkComputer
     alias_method :values, :checks
 
     def check_names
-      collection.keys
+      included_collection.keys
     end
 
     alias_method :keys, :check_names
 
     def sub_collections
-      checks.select{ |c| c.is_a?(CheckCollection)}
+      collection.values.select{ |c| c.is_a?(CheckCollection)}
     end
 
     def self_and_sub_collections
@@ -108,15 +111,17 @@ module OkComputer
 
     private
 
+    def included_collection
+      return collection unless @exclude_skipped_checks
+      collection.reject{ |_name, check| check.respond_to?(:skip_all) && check.skip_all }
+    end
+
     def check_in_sequence
       checks.each(&:run)
     end
 
     def check_in_parallel
-      threads = checks.map do |check|
-        Thread.new { check.run }
-      end
-      threads.each(&:join)
+      checks.map{ |check| Thread.new(check, &:run) }.each(&:join)
     end
   end
 end

data/lib/ok_computer/registry.rb

@@ -31,7 +31,7 @@ module OkComputer
     #
     # Returns @default_collection
     def self.default_collection
-      @default_collection ||= CheckCollection.new('Default Collection')
+      @default_collection ||= CheckCollection.new('Default Collection', true)
     end
 
     # Public: Register the given check with OkComputer
@@ -39,8 +39,27 @@ module OkComputer
     # check_name - The name of the check to retrieve
     # check_object - Instance of Checker to register
     # collection_name - The name of the check collection the check should be registered to
-    def self.register(check_name, check_object, collection_name=nil)
-      find_collection(collection_name).register(check_name, check_object)
+    # options - Set skip_all to true to omit the check from the default collection's results
+    def self.register(check_name, check_object, collection_name=nil, options={})
+      if collection_name.is_a?(Hash)
+        options = collection_name
+        collection_name = nil
+      end
+
+      if collection_name && options[:skip_all]
+        raise ArgumentError, "skip_all is only supported in the default collection"
+      end
+
+      if !collection_name && options.key?(:skip_all)
+        if check_object.respond_to?(:skip_all=)
+          check_object.skip_all = !!options[:skip_all]
+        elsif options[:skip_all]
+          raise ArgumentError, "skip_all requires a check that supports skip_all="
+        end
+      end
+
+      collection = find_collection(collection_name)
+      collection.register(check_name, check_object)
     end
 
     # Public: Remove the check of the given name being checked

data/lib/ok_computer/version.rb

@@ -1,3 +1,3 @@
 module OkComputer
-  VERSION = '1.19.2'
+  VERSION = '1.20.0'
 end

data/lib/okcomputer.rb

@@ -34,6 +34,11 @@ require "ok_computer/built_in_checks/resque_failure_threshold_check"
 require "ok_computer/built_in_checks/ruby_version_check"
 require "ok_computer/built_in_checks/sequel_check"
 require "ok_computer/built_in_checks/sidekiq_latency_check"
+require "ok_computer/built_in_checks/solid_queue_check"
+require "ok_computer/built_in_checks/solid_queue_backed_up_check"
+require "ok_computer/built_in_checks/solid_queue_scheduled_backed_up_check"
+require "ok_computer/built_in_checks/solid_queue_failed_jobs_check"
+require "ok_computer/built_in_checks/solid_queue_failed_jobs_rate_check"
 require "ok_computer/built_in_checks/solr_check"
 
 OkComputer::Registry.register "default", OkComputer::DefaultCheck.new

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: okcomputer
 version: !ruby/object:Gem::Version
-  version: 1.19.2
+  version: 1.20.0
 platform: ruby
 authors:
 - Patrick Byrne
@@ -12,7 +12,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-31 00:00:00.000000000 Z
+date: 2026-09-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: benchmark
@@ -75,6 +75,11 @@ files:
 - lib/ok_computer/built_in_checks/sequel_check.rb
 - lib/ok_computer/built_in_checks/sidekiq_latency_check.rb
 - lib/ok_computer/built_in_checks/size_threshold_check.rb
+- lib/ok_computer/built_in_checks/solid_queue_backed_up_check.rb
+- lib/ok_computer/built_in_checks/solid_queue_check.rb
+- lib/ok_computer/built_in_checks/solid_queue_failed_jobs_check.rb
+- lib/ok_computer/built_in_checks/solid_queue_failed_jobs_rate_check.rb
+- lib/ok_computer/built_in_checks/solid_queue_scheduled_backed_up_check.rb
 - lib/ok_computer/built_in_checks/solr_check.rb
 - lib/ok_computer/check.rb
 - lib/ok_computer/check_collection.rb