Tocsin

Tocsin is a library designed to simply the task of notifying interested parties about your site's operation. You may already be tracking errors through New Relic, but not all errors are created equal -- there are probably parts of your site where an exception occuring is significantly more of a problem than a bored URL surfer visiting random links and throwing 404s. Tocsin can help you be informed when these parts of your site break, or when important events happen.

Currently, Tocsin works only in Rails 3, and supports notification via email.

Installation

Add Tocsin to your Gemfile:

gem 'tocsin'

Update your bundle:

bundle install

Use the provided Rake task to generate the migration and model needed by Tocsin. (Angry at the lack of normalization? Install lookup_by and rewrite the migration and model to use it; Tocsin won't even notice.)

rake tocsin:install

Lastly, configure Tocsin to be useful. Create an initializer in config/initializers/tocsin.rb that looks something like this:

Tocsin.configure do |c|
  c.from_address = 'me@mysite.com'

  c.notify 'you@gmail.com', :of => { :category => /user_registrations/ }, :by => :email
  c.notify ['you@gmail.com', 'sales@mysite.com'], :of => { :category => /new_sales/ } # N.B. 'email' is the default nofifier.
  c.notify 'ops@mysite.com', :of => { :severity => /critical/ } # Values in the :of hash should be regexes.
end

Usage

In anywhere you want to send yourself a notification:

Tocsin.notify :category => :user_registrations,
              :message => "User #{user.name} registered at #{Time.now}!"

If you want to sound the alarm:

begin
  # ...
rescue => e
  Tocsin.raise_alert  e, :category => :user_registrations,
                         :severity => :critical,
                         :message => "An error occurred when a user tried to sign up!"
end

In any code you want to watch for explosions:

Tocsin.watch! :category => :important_stuff, :severity => :critical, :message => "Error doing important stuff!" do
  Important::Stuff.do!
end