health_check gem¶ ↑

Simple health check of Rails app for use with Pingdom, NewRelic, EngineYard or uptime.openacs.org etc.

The basic goal is to quickly check that rails is up and running and that it has access to correctly configured resources (database, email gateway)

health_check provides various monitoring URIs, for example:

curl localhost:3000/health_check
success

curl localhost:3000/health_check/all.json
{"healthy":true,"message":"success"}

curl localhost:3000/health_check/database_cache_migration.xml
<?xml version="1.0" encoding="UTF-8"?>
<hash>
  <healthy type="boolean">true</healthy>
  <message>success</message>
</hash>

On failure a 500 http status is returned with a simple explanation of the failure

curl localhost:3000/health_check/fail
health_check failed: invalid argument to health_test.

The health_check controller disables sessions and logging for its actions to minimise the impact of frequent uptime checks on the session store and the log file.

Checks¶ ↑

standard (default) - site, database and migrations checks are run plus email if settings have been changed
all / full - all checks are run
database - checks that the current migration level can be read from the database
email - basic check of email - :test returns true, :sendmail checks file is present and executable, :smtp sends HELO command to server and checks response
migration - checks that the database migration level matches that in db/migrations
cache - checks that a value can be written to the cache
site - checks rails is running sufficiently to render text
custom - runs checks added via config.add_custom_check

The email gateway is not checked unless the smtp settings have been changed. Specify full or include email in the list of checks to verify the smtp settings (eg use 127.0.0.1 instead of localhost).

Note: rails 4.0 also checks migrations and throws an ActiveRecord::PendingMigrationError exception (http error 500) if there is an error

Installation¶ ↑

As a Gem from rubygems (Rails 3.0 and above)¶ ↑

Add the following line to Gemfile

gem "health_check"

And then execute

bundle

Or install it yourself as:

gem install health_check

As a Gem from rubygems (Rails 2.3)¶ ↑

Install the gem using the following command

gem install health_check

Then add the following line to config/environment.rb within the config block

config.gem "health_check"

As a Plugin (Rails 2.3.x)¶ ↑

Run the following commands from the root of your rails application

cd vendor/plugins
git clone git://github.com/ianheggie/health_check.git

Configuration¶ ↑

To change the configuration of health_check, create a file ‘config/initializers/health_check.rb` and add a configuration block like:

HealthCheck.setup do |config|

  # Text output upon success
  config.success = 'success'

  # Timeout in seconds used when checking smtp server
  config.smtp_timeout = 30.0

  # http status code used when plain text error message is output
  # Set to 200 if you want your want to distinguish between partial (text does not include success) and
  # total failure of rails application (http status of 500 etc)

  config.http_status_for_error_text = 500

  # http status code used when an error object is output (json or xml)
  # Set to 200 if you want your want to distinguish between partial (healthy property == false) and
  # total failure of rails application (http status of 500 etc)

  config.http_status_for_error_object = 500

  # Add one or more custom checks that return a blank string if ok, or an error message if there is an error
  config.add_custom_check do
    CustomHealthCheck.perform_check # any code that returns blank on success and non blank string upon failure
  end

end

You may call add_custom_check multiple times with different tests. These tests will be included in the default list (“standard”).

Uptime Monitoring¶ ↑

Use a website monitoring service to check the url regularly for the word “success” (without the quotes) rather than just a 200 http status so that any substitution of a different server or generic information page should also be reported as an error.

If an error is encounted, the text “health_check failed: some error message/s” will be returned and the http status will be 500.

See

Pingdom Website Monitoring - www.pingdom.com
NewRelic Availability Monitoring - newrelic.com/docs/features/availability-monitoring-faq
Uptime by OpenACS - uptime.openacs.org/uptime/
Engine Yard’s guide - support.cloud.engineyard.com/entries/20996821-monitor-application-uptime (although the guide is based on fitter_happier plugin it will also work with this gem)
Any other montoring service that can be set to check for the word success in the test returned from a url

Requesting Json and XML responses¶ ↑

Health_check will respond with an encoded hash object if json or xml is requested. Either set the HTTP Accept header or append .json or .xml to the url.

The hash contains two keys:

healthy - true if requested checks pass (boolean)
message - text message (“success” or error message)

The following commands

curl -v localhost:3000/health_check.json
curl -v localhost:3000/health_check/email.json
curl -v -H "Accept: application/json" localhost:3000/health_check

Will return a result with Content-Type: application/json and body like:

{"healthy":true,"message":"success"}

These following commands

curl -v localhost:3000/health_check.xml
curl -v localhost:3000/health_check/migration_cache.xml
curl -v -H "Accept: text/xml" localhost:3000/health_check/cache

Will return a result with Content-Type: application/xml and body like:

<?xml version="1.0" encoding="UTF-8"?>
<hash>
  <healthy type="boolean">true</healthy>
  <message>success</message>
</hash>

See github.com/ianheggie/health_check/wiki/Ajax-Example for an Ajax example

Note on Patches/Pull Requests¶ ↑

Feedback welcome! Especially with suggested replacement code and corresponding tests

Fork it
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request.

Known Issues¶ ↑

No inline documentation for methods
rvm gemsets breaks the test - specifically rvm use 1.9.3 works but rvm gemset use ruby-1.9.3-p385@health_check --create triggers a “Could not find gem ‘coffee-rails (~> 3.2.1) ruby’ in the gems available on this machine.” error in the last call to bundle (installing health_check as a gem via a path into the temp railsapp)

Similar projects¶ ↑

fitter_happier plugin by atmos - plugin with similar goals, but not compatible with uptime, and does not check email gateway

Testing¶ ↑

Automated testing and other checks¶ ↑

Travis CI runs the tests: <img src=“https://travis-ci.org/ianheggie/health_check.png”>

Code Climate monitors code quality: <img src=“https://codeclimate.com/github/ianheggie/health_check.png” />

Gemnasium monitors gem dependencies <img src=“https://gemnasium.com/ianheggie/health_check.png”>

Manual testing¶ ↑

The test will package up and install the gem under a temporary path, create a dummy rails app configured for sqlite, install the gem, and then run up tests against the server. This will require TCP port 3456 to be free.

Using rbenv or rvm, install and set the version of ruby you wish to test against. You will need to install the bundler gem if using rbenv. See the .travis.yml file for the list of ruby versions that we test against.

rbenv command: rbenv shell 1.8.7-p371
rvm command: rvm use 1.9.3

Create a temp directory for throw away testing, and clone the health_check gem into it

mkdir -p ~/tmp
cd ~/tmp
git clone https://github.com/ianheggie/health_check.git

Cd to the checked out health_check directory and then run the test as follows:

cd ~/tmp/health_check

test/test_with_railsapp

The script will first call ‘test/setup_railsapp` to setup a rails app with health_check installed and then run up the rails server and perform veraious tests.

The script ‘test/setup_railsapp` will prompt you for which gemfile under test you wish to use to install the appropriate rails version, and then setup tmp/railsapp accordingly.

The command ‘rake test` will also launch these tests, except it cannot install the bundler and rake gems if they are missing first (unlike test/test_with_railsapp)

redmar/health_check