RailsHealthChecks

A Rails engine providing structured, pluggable health check endpoints for monitoring application status. Goes beyond Rails' built-in /up endpoint with per-check diagnostics, latency tracking, and a configurable check registry.

Table of Contents

• Installation
• Endpoints
• Configuration
• Authentication
• Built-in Checks
• Contributing
• License

---

Installation

Add to your Gemfile:

gem "rails_health_checks"

Then run:

bundle install

Mount the engine in config/routes.rb:

mount RailsHealthChecks::Engine => "/health"

↑ Back to top

---

Endpoints

Endpoint	Format	Use case
GET /health	JSON	Monitoring dashboards, detailed diagnostics
GET /health/live	Plain text	Load balancer liveness probes

HTTP status is 200 OK when all checks pass, 503 Service Unavailable otherwise.

JSON response shape

{
  "status": "ok",
  "timestamp": "2026-06-08T20:00:00Z",
  "checks": {
    "database": { "status": "ok", "latency_ms": 4 }
  }
}

Status values: ok | degraded | critical. Overall status is critical if any check is critical, degraded if any is degraded.

↑ Back to top

---

Configuration

# config/initializers/rails_health_checks.rb
RailsHealthChecks.configure do |config|
  config.checks  = [:database, :cache]  # checks to run (default: [:database])
  config.timeout = 5            # global timeout per check in seconds (default: 5)
end

↑ Back to top

---

Authentication

By default health endpoints are public. Use one of the following strategies to restrict access. Unauthenticated requests receive 401 Unauthorized.

Bearer token

RailsHealthChecks.configure do |config|
  config.token = ENV["HEALTH_TOKEN"]
end

Requests must include Authorization: Bearer <token>.

IP allowlist

RailsHealthChecks.configure do |config|
  config.allowed_ips = ["127.0.0.1", "10.0.0.0/8"]  # exact IPs or CIDR ranges
end

Custom block

RailsHealthChecks.configure do |config|
  config.authenticate { |request| request.headers["X-Internal"] == "true" }
end

The block receives the ActionDispatch::Request object and must return a truthy value to allow access.

↑ Back to top

---

Built-in Checks

Check	Description
:database	ActiveRecord SELECT 1 against the primary connection, includes latency
:cache	Rails.cache read/write probe; works with Redis, Memcached, or in-process store
:sidekiq	Sidekiq Redis connectivity; optional config.sidekiq_queue_size threshold for queue depth
:solid_queue	Solid Queue DB connectivity; optional config.solid_queue_job_count threshold for pending jobs
:good_job	GoodJob queue latency; optional config.good_job_latency (seconds) threshold for oldest pending job
:resque	Resque Redis connectivity; optional config.resque_queue_size threshold for total queue depth

↑ Back to top

---

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

↑ Back to top

---

License

The gem is available as open source under the terms of the MIT License.