README.rdoc

Is It Working

This gem provides a mechanism for setting up a Rack handler that tests the
status of various components of an application and reports the output. It
is designed to be modular and give a comprehensive view of the application
status with a consistent URL (/is_it_working by default).

This handler can be used by monitoring to determine if an application is
working or not, but it does not replace system level monitoring of low
level resources. Rather it adds another level which tells if the
application can actually use those resources.

Use It As Documentation

A feature of this gem is that it gives you a consistent place to document
the external dependencies of you application as code. The handler checking
the status of you application should have a check for every line drawn from
it to another box on a system architecture diagram.

Example

Suppose you have a Rails application that uses the following services:

ActiveRecord uses PostgreSQL database

Caching is done using Rails.cache with a cluster of memcached instances

Output

The response from the handler will be a plain text description of the
checks that were run and the results of those checks. If all the checks
passed, the response code will be 200. If any checks fail, the response
code will be 500. The response will look something like this:

Security

Keep in mind that the output from the status check will be available on a
publicly accessible URL. This can pose a security risk if some servers are
not on a private network behind a firewall. If necessary, you can obscure
the host names in the predefined checks by providing an :alias
option that will be output instead of the actual host name or IP address.
Also, you can manually specify the hostname that the handler reports for
the application with the Handler#hostname= method.

Thread Safety

By default status checks each happen in their own thread. If you write your
own status check, you must make sure it is thread safe. If you need to
synchronize the check logic, you can use the synchronize method on
the handler object to do so. Alternatively, you can pass :async =>
false to any check specification. This will cause the check
to be executed in the main request thread.