Exception and Report handlers are a feature of Chef that allow you to run code in response to a Chef run succeeding or failing.

The most obvious use is to dispatch notifications if a Chef run fails, though it is also possible to gather rich data about your chef usage for trending and analysis.

Anatomy of a handler

A handler is a class inheriting from Chef::Handler and implementing report() function. Before report() is actually run, run_status is initialized by chef. run_status is an instance of Chef::RunStatus, a class that keeps track of the chef run status (gee, there's a surprise...). run_status provides several useful properties for reporting, have a look at the table:

A handler may be assigned as a report or exception handler, there's no real difference in the code. Use success? or failed? if you need to know what situation caused it to run.

Writing a Handler

Let's start by writing a simple handler to send an email when a chef run fails. We'll keep things simple by using the pony library to send the email. For this example to work, you'll need to be able to send mail via /usr/sbin/sendmail or SMTP to localhost, but it should be pretty easy to extend the example if you need to.

Installing and Configuring a Handler

You can install and configure handlers either through use of the chef-handler LWRP, or manually.

In a recipe with the chef_handler LWRP

The chef_handler LWRP that ships as part of the chef_handler cookbook provides an easy to use idempotent resource that can be included in your recipe code.

To manually install and configure a handler, you'll need to use edit the Chef config file.

In the Chef config (client.rb) file

There is currently no default install location for handlers. The simplest way to distribute and install them is via rubygems, though any method of distributing the code (i.e., github, HTTP, etc.) will work. Once the handler is installed on the system, enable it in your client.rb file by requiring it. If you're using rubygems, you can require the handler by name:

If you installed the handler by some other method, you will probably need to require it using the full path to the file:

Once the handler is enabled, you may need to configure it. The way this is done will vary for each handler. If you have a simple handler that requires no additional configuration, you will most likely just need to create a new instance of the handler.

For example, if you have a handler MyOrganization::EmailMe in which you hardcoded all the values it needs to send email, you would simply create a new instance of it:

Finally, configure the handler to notify you for either failed chef runs or successful ones.

Putting it all together, your client.rb file would have a section like this:

Distributing Chef Handlers

See Distributing Chef Handlers for use of the Opscode provided cookbook to accomplish this task.

Existing Handlers

Chef ships with a handler that will serialize the run status data to a JSON file. To use it, put the following in /etc/chef/client.rb or /etc/chef/solo.rb.

The data can be loaded and inspected via irb:

• Airbrake exceptions
  Chef handler for sending exceptions to Airbrake (exceptions only)

• Asynchronous Resources Handler
  Chef report handler that pushes changes to a stomp queue, see blog post

• Campfire handler
  Chef handler for sending exceptions and reports to campfire

• chef-handler-graphite
  Chef report handler to push metrics to graphite. YEAH!

• chef-irc-snitch
  An exception handler for Opscode Chef runs (github gists & IRC)

• Cloudkick handler
  Chef handler for sending exceptions and reports to cloudkick

• Datadog handler
  Chef handler for getting Chef stats directly into the Datadog newsfeed each time the client runs, extended into a Rubygem from chef-datadog. See blog post

• GELF/Graylog2 handler
  Chef handler which can report run status, including any changes that were made, to a Graylog2 server.

• Growl handler
  Chef report handler to send Growl notification

• HipChat room message
  HipChat HTTP API Wrapper in Ruby with Capistrano hooks (exceptions only)

• Mail report handler
  Simple Chef report handler that sends Erubis template based reports via the Pony gem

• nsca based chef report handler
  Chef report/exception handler plugin that submits passive checks to nagios via nsca

• Simple Updated Resources Handler
  Chef report handler to display resources updated in the Chef Run, see blog post

There are Community Plugins for Chef, Ohai, and Knife as well.

Environments

Distributing Chef Handlers