Switch branches/tags
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
80 lines (47 sloc) 2.47 KB


Stethoscope is Rack Middelware that provides heartbeats for your application. Heartbeats are used to check that your application is functioning correctly.

Typically, a tool like Nagios will monitor a heartbeat URL which will return a 200 OK status if everything is ok, or a 500 response for any issues.



use Stethoscope
run MyApp

Rails 2

# config/environment.rb
config.middleware.use Stethoscope

Rails 3

Just require Stethoscope in your application. Stethoscope has a Railtie that will configure Stethoscope to work

Customizing Stethoscope

Heartbeat URL

Default: /heartbeat

Stethoscope.url = "/some/custom/path"


Stethoscope uses checks to check some component of the application. A check is simply a block that is executed when the heartbeat url is hit.

You don't need any checks. If you don't include one, Stethoscope will respond if the application is running.

If you do want to check some other pieces of your stack, checks is where it's at.

A response hash is made available to store any information which is then made available to the heartbeat template.

Returning a response :status outside 200..299 will trigger Stethoscope to return a 500 status code to the client.


Stethoscope.check :database do |response|
  ActiveRecord::Base.connection.execute('select 1')

Stethoscope.check :some_service do |response|
  start   =
  response['result']    = SomeSerivce.check_availability!
  response['Ping Time'] = - start
  response[:status]     = 245 # Any status outside 200..299 will result in a 500 status being returned from the heartbeat

Any exceptions are caught and added to the response with the :error key. The template can then handle them appropriately


  • ActiveRecord
    • Check name - :database
    • require 'stethoscope/checks/active_record'
    • Included if the ActiveRecord constant is present in Rails 3
  • DataMapper
    • Check name - :database
    • require 'stethoscope/checks/data_mapper'
    • Included if the DataMapper constant is present in Rails 3


Stethoscope uses Tilt to render a template for the heartbeat response

By default, Stethoscope provides a simple template to render the responses of the checks in the lib/stethoscope/template.erb file.

You can overwrite the template used:

Stethoscope.template ="my_new_tempalte_file.haml")