rails_health_checks 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4e3f62376ecb6e658daaf39738dbb50a5eb6885b765af8766a74f748dafe9ac5
-  data.tar.gz: da0bcf07fdb7636c810e6656b99084d1554fbd3d4012d69560a8bd8474a05232
+  metadata.gz: 010ea2d8734800da5baaaa805b0671ac685f3c5a26a11967ca64f00cfd03500c
+  data.tar.gz: 7f81bbd9940d17d7b67f779da47b6fe42796ab6542080fcf2a790976c9e83be5
 SHA512:
-  metadata.gz: eccd94c21587daabf39b10f6d98b5be36a632353b698538db2fb8e14be6e0dab9b0f4d175d9f8e896a4cde1faca45824036b4f4618e7bb8303e5e435064584a3
-  data.tar.gz: 92ac0ad412e0cc473cccaa16240bcf78b3a2c4cac017f15651386990009cd32b2bf82866d39d58ccd7fa287de88745f6fb84ee99df472c385a2525277dfefa93
+  metadata.gz: f6da67674aa9871b760450a01834a09b1bdebcbacbd21c330c60d2a6c98725b331321c3e187e7741269f414b11562b1dcb48ea99ec8d8face847677c678bbdd0
+  data.tar.gz: f5cf9df5e54de04defd67440c8d838f7c7a085f2712351b1e79920975d64d5c957c43d02cf5de3497ef25ae4ee77ac8a6d8e52d32c682fb0158e753d958a683b

data/README.md

@@ -15,6 +15,8 @@ A Rails engine providing structured, pluggable health check endpoints for monito
 - [Configuration](#configuration)
 - [Authentication](#authentication)
 - [Built-in Checks](#built-in-checks)
+- [Notifications](#notifications)
+- [Prometheus Metrics](#prometheus-metrics)
 - [Per-Environment Toggling](#per-environment-toggling)
 - [Check Groups](#check-groups)
 - [Custom Checks](#custom-checks)
@@ -53,8 +55,9 @@ mount RailsHealthChecks::Engine => "/health"
 |----------|--------|----------|
 | `GET /health` | JSON | Monitoring dashboards, detailed diagnostics |
 | `GET /health/live` | Plain text | Load balancer liveness probes |
+| `GET /health/metrics` | Prometheus text | Prometheus / OpenMetrics scraping |
 
-HTTP status is `200 OK` when all checks pass, `503 Service Unavailable` otherwise.
+HTTP status is `200 OK` when all checks pass, `503 Service Unavailable` otherwise (except `/metrics` which always returns `200`).
 
 ### JSON response shape
 
@@ -142,6 +145,44 @@ The block receives the `ActionDispatch::Request` object and must return a truthy
 
 ---
 
+## Notifications
+
+Every health check run publishes an `ActiveSupport::Notifications` event:
+
+```ruby
+ActiveSupport::Notifications.subscribe("health_check.rails_health_checks") do |*args|
+  event = ActiveSupport::Notifications::Event.new(*args)
+  Rails.logger.info "Health check: #{event.payload[:status]} (#{event.duration.round}ms)"
+  # event.payload[:checks] => { database: { status: "ok", latency_ms: 3 }, ... }
+end
+```
+
+The payload includes `status` (overall: `ok`/`degraded`/`critical`) and `checks` (per-check hash with `status`, `latency_ms`, and `message` when present). Duration is measured over the entire parallel check run.
+
+[↑ Back to top](#table-of-contents)
+
+---
+
+## Prometheus Metrics
+
+`GET /health/metrics` returns Prometheus text exposition format (`text/plain; version=0.0.4`). This endpoint always returns HTTP 200 — Prometheus convention is that scrape targets should always respond successfully, with check state encoded in metric values.
+
+```
+# HELP rails_health_check_status Health check status (0=ok, 1=degraded, 2=critical)
+# TYPE rails_health_check_status gauge
+rails_health_check_status{check="database"} 0
+rails_health_check_status{check="cache"} 0
+
+# HELP rails_health_check_latency_ms Health check latency in milliseconds
+# TYPE rails_health_check_latency_ms gauge
+rails_health_check_latency_ms{check="database"} 4
+rails_health_check_latency_ms{check="cache"} 2
+```
+
+[↑ Back to top](#table-of-contents)
+
+---
+
 ## Per-Environment Toggling
 
 Disable specific checks in specific environments:
@@ -199,7 +240,11 @@ RailsHealthChecks.configure do |config|
 end
 ```
 
-`config.register` automatically adds the check to the active checks list. Use `pass`, `warn_with`, and `fail_with` (inherited from `Check`) to set status, and `measure { }` to record latency.
+`config.register` automatically adds the check to the active checks list. Pass `timeout:` to override the global timeout for this check only:
+
+```ruby
+config.register :slow_api, MyApiCheck.new, timeout: 10
+``` Use `pass`, `warn_with`, and `fail_with` (inherited from `Check`) to set status, and `measure { }` to record latency.
 
 [↑ Back to top](#table-of-contents)
 

data/app/controllers/rails_health_checks/application_controller.rb

@@ -4,5 +4,13 @@ module RailsHealthChecks
   class ApplicationController < ActionController::API
     include Authentication
     before_action :authenticate!
+
+    private
+
+    def run_checks(check_names)
+      config = RailsHealthChecks.configuration
+      checks = CheckRegistry.build(check_names)
+      CheckRegistry.run(checks, timeout: config.timeout)
+    end
   end
 end

data/app/controllers/rails_health_checks/groups_controller.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module RailsHealthChecks
+  class GroupsController < ApplicationController
+    def show
+      group_name = params[:id].to_sym
+      check_names = RailsHealthChecks.configuration.groups[group_name]
+      return render json: { error: "Group '#{group_name}' not found" }, status: :not_found unless check_names
+
+      builder = ResponseBuilder.new(run_checks(check_names))
+      render json: builder.to_json, status: builder.http_status
+    end
+  end
+end

data/app/controllers/rails_health_checks/health_controller.rb

@@ -6,31 +6,5 @@ module RailsHealthChecks
       builder = ResponseBuilder.new(run_checks(RailsHealthChecks.configuration.checks))
       render json: builder.to_json, status: builder.http_status
     end
-
-    def live
-      builder = ResponseBuilder.new(run_checks(RailsHealthChecks.configuration.checks))
-      if builder.overall_status == "ok"
-        render plain: "OK", status: :ok
-      else
-        render plain: "Service Unavailable", status: :service_unavailable
-      end
-    end
-
-    def group
-      group_name = params[:group].to_sym
-      check_names = RailsHealthChecks.configuration.groups[group_name]
-      return render json: { error: "Group '#{group_name}' not found" }, status: :not_found unless check_names
-
-      builder = ResponseBuilder.new(run_checks(check_names))
-      render json: builder.to_json, status: builder.http_status
-    end
-
-    private
-
-    def run_checks(check_names)
-      config = RailsHealthChecks.configuration
-      checks = CheckRegistry.build(check_names)
-      CheckRegistry.run(checks, timeout: config.timeout)
-    end
   end
 end

data/app/controllers/rails_health_checks/live_controller.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module RailsHealthChecks
+  class LiveController < ApplicationController
+    def show
+      builder = ResponseBuilder.new(run_checks(RailsHealthChecks.configuration.checks))
+      if builder.overall_status == "ok"
+        render plain: "OK", status: :ok
+      else
+        render plain: "Service Unavailable", status: :service_unavailable
+      end
+    end
+  end
+end

data/app/controllers/rails_health_checks/metrics_controller.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module RailsHealthChecks
+  class MetricsController < ApplicationController
+    def show
+      results = run_checks(RailsHealthChecks.configuration.checks)
+      render plain: PrometheusFormatter.new(results).to_text,
+             content_type: "text/plain; version=0.0.4",
+             status: :ok
+    end
+  end
+end

data/config/routes.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
 RailsHealthChecks::Engine.routes.draw do
-  get "/",       to: "health#show",  as: :health
-  get "/live",   to: "health#live",  as: :health_live
-  get "/:group", to: "health#group", as: :health_group
+  get "/",        to: "health#show",   as: :health
+  get "/live",    to: "live#show",     as: :health_live
+  get "/metrics", to: "metrics#show",  as: :health_metrics
+  get "/:id",     to: "groups#show",   as: :health_group
 end

data/lib/rails_health_checks/check.rb

@@ -2,6 +2,7 @@
 
 module RailsHealthChecks
   class Check
+    attr_accessor :timeout
     attr_reader :status, :message, :latency_ms
 
     def call

data/lib/rails_health_checks/check_registry.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "timeout"
+require "concurrent"
 
 module RailsHealthChecks
   class CheckRegistry
@@ -38,7 +39,22 @@ module RailsHealthChecks
     end
 
     def self.run(checks, timeout:)
-      checks.transform_values { |check| run_check(check, timeout: timeout) }
+      results = {}
+      ActiveSupport::Notifications.instrument("health_check.rails_health_checks") do |payload|
+        futures = checks.transform_values do |check|
+          t = check.timeout || timeout
+          Concurrent::Future.execute { run_check(check, timeout: t) }
+        end
+        checks.each do |name, check|
+          t = check.timeout || timeout
+          results[name] = futures[name].value(t + 1) || mark_critical(check, "timed out")
+        end
+        payload[:status] = overall_status(results)
+        payload[:checks] = results.transform_values do |c|
+          { status: c.status, message: c.message, latency_ms: c.latency_ms }.compact
+        end
+      end
+      results
     end
 
     def self.run_check(check, timeout:)
@@ -56,6 +72,14 @@ module RailsHealthChecks
       check
     end
 
-    private_class_method :run_check, :mark_critical
+    def self.overall_status(results)
+      statuses = results.values.map(&:status)
+      if statuses.include?("critical") then "critical"
+      elsif statuses.include?("degraded") then "degraded"
+      else "ok"
+      end
+    end
+
+    private_class_method :run_check, :mark_critical, :overall_status
   end
 end

data/lib/rails_health_checks/configuration.rb

@@ -48,7 +48,8 @@ module RailsHealthChecks
       @groups[name] = check_names
     end
 
-    def register(name, check)
+    def register(name, check, timeout: nil)
+      check.timeout = timeout
       @custom_checks[name] = check
       @checks << name unless @checks.include?(name)
     end

data/lib/rails_health_checks/prometheus_formatter.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module RailsHealthChecks
+  class PrometheusFormatter
+    STATUS_CODES = { "ok" => 0, "degraded" => 1, "critical" => 2 }.freeze
+
+    def initialize(results)
+      @results = results
+    end
+
+    def to_text
+      lines = []
+
+      lines << "# HELP rails_health_check_status Health check status (0=ok, 1=degraded, 2=critical)"
+      lines << "# TYPE rails_health_check_status gauge"
+      @results.each { |name, check| lines << "rails_health_check_status{check=\"#{name}\"} #{STATUS_CODES[check.status]}" }
+
+      lines << ""
+      lines << "# HELP rails_health_check_latency_ms Health check latency in milliseconds"
+      lines << "# TYPE rails_health_check_latency_ms gauge"
+      @results.each do |name, check|
+        lines << "rails_health_check_latency_ms{check=\"#{name}\"} #{check.latency_ms}" if check.latency_ms
+      end
+
+      lines.join("\n") + "\n"
+    end
+  end
+end

data/lib/rails_health_checks/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RailsHealthChecks
-  VERSION = "0.5.0"
+  VERSION = "0.6.0"
 end

data/lib/rails_health_checks.rb

@@ -16,6 +16,7 @@ require "rails_health_checks/checks/memory_check"
 require "rails_health_checks/checks/http_check"
 require "rails_health_checks/check_registry"
 require "rails_health_checks/response_builder"
+require "rails_health_checks/prometheus_formatter"
 
 module RailsHealthChecks
   class << self

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails_health_checks
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Chuck Smith
@@ -35,7 +35,10 @@ files:
 - README.md
 - Rakefile
 - app/controllers/rails_health_checks/application_controller.rb
+- app/controllers/rails_health_checks/groups_controller.rb
 - app/controllers/rails_health_checks/health_controller.rb
+- app/controllers/rails_health_checks/live_controller.rb
+- app/controllers/rails_health_checks/metrics_controller.rb
 - app/jobs/rails_health_checks/application_job.rb
 - app/mailers/rails_health_checks/application_mailer.rb
 - app/models/rails_health_checks/application_record.rb
@@ -55,6 +58,7 @@ files:
 - lib/rails_health_checks/checks/solid_queue_check.rb
 - lib/rails_health_checks/configuration.rb
 - lib/rails_health_checks/engine.rb
+- lib/rails_health_checks/prometheus_formatter.rb
 - lib/rails_health_checks/response_builder.rb
 - lib/rails_health_checks/version.rb
 - lib/tasks/rails_health_checks_tasks.rake