README.md

Rails::Healthcheck

A simple way to configure a healthcheck route in Rails applications

Table of Contents

• Getting started
  • Installation
  • Settings
  • Custom Response
  • Verbose Errors
  • Ignoring logs
    • Lograge
    • Datadog
  • Requests Examples
• Contributing
• License

Getting started

Installation

Add this line to your application's Gemfile:

gem 'rails-healthcheck'

and run the command bellow to create the initializer:

rails generate healthcheck:install

Settings

You can set the settings in the initializer file (config/initializers/healthcheck.rb):

# frozen_string_literal: true

Healthcheck.configure do |config|
  config.success = 200
  config.error = 503
  config.verbose = false
  config.route = '/healthcheck'
  config.method = :get

  # -- Custom Response --
  # config.custom = lambda { |controller, checker|
  #   controller.render json: my_custom_response unless checker.errored?
  #   ...
  # }

  # -- Checks --
  # config.add_check :database,     -> { ActiveRecord::Base.connection.execute('select 1') }
  # config.add_check :migrations,   -> { ActiveRecord::Migration.check_pending! }
  # config.add_check :cache,        -> { Rails.cache.read('some_key') }
  # config.add_check :environments, -> { Dotenv.require_keys('ENV_NAME', 'ANOTHER_ENV') }
end

Custom Response

You can override the configs success, error and verbose and write your custom behaviour for the healthcheck api using the field custom in the initializer:

Healthcheck.configure do |config|
  # ...

  # -- Custom Response --
  config.custom = lambda { |controller, checker|
    controller.render json: { field_name: 'my custom field value' } unless checker.errored?
    ...
  }

  # ...
end

Pass a lambda or proc receiving the params controller and checker to use it correctly. To use checker, you can see the avialable methods here and how it is implemented on HealthcheckController.

Verbose Errors

When happen an error and verbose is enabled (config.verbose = true), the response will be like this:

{
    "code": 503,
    "errors": [
        {
            "name": "migrations",
            "exception": "ActiveRecord::PendingMigrationError",
            "message": "Migrations are pending. To resolve this issue, run: bin/rails db:migrate RAILS_ENV=production"
        },
        {
            "name": "environments",
            "exception": "Dotenv::MissingKeys",
            "message": "Missing required configuration key: [\"RAILS_ENV\"]"
        }
    ]
}

Ignoring logs

If you want to ignore Healthcheck request logs, you can use these options:

Lograge

# config/environments/production.rb

Rails.application.configure do
  config.lograge.enabled = true
  config.lograge.ignore_actions = [Healthcheck::CONTROLLER_ACTION]
end

Datadog

# config/environments/production.rb

filter = Datadog::Pipeline::SpanFilter.new do |span|
  span.name == 'rack.request' && span.get_tag('http.url') == Healthcheck.configuration.route
end

Datadog::Pipeline.before_flush(filter)

Requests Examples

• Success

curl -i localhost:3000/healthcheck

HTTP/1.1 200 OK

• Error

curl -i localhost:3000/healthcheck

HTTP/1.1 503 Service Unavailable

• Error (Verbose)

curl -i localhost:3000/healthcheck

HTTP/1.1 503 Service Unavailable
{"code":503,"errors":[{"name":"zero_division","exception":"ZeroDivisionError","message":"divided by 0"}]}

Contributing

1. Fork it
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 new Pull Request

License

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

Code of Conduct

Everyone interacting in the Rails::Healthcheck project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.