This post is for people who want to use or write their first Chef report handler, but aren’t sure where to begin. I first attempted to write a handler just after I learned how to write basic Chef recipes. It was hard, because I only had a rudimentary understanding of Chef mechanics, and I was learning Ruby as I went. This article would have got me started faster. However, in the end you are going to be writing Ruby, and probably you’ll need to get deeper into Chef too.
The three types of handler
There are three types of handler:
- Start handler – Runs at the beginning of a chef-client run
- Report handler – Runs at the end of a chef-client run, after all of the recipes have successfully completed
- Exception handler – Runs at the end of a chef-client run if it exits with an error code
I am going to gloss over start handlers: they are less common and somewhat more complex because you have to get the handler in place before the chef-client run happens (so you can’t distribute them in a recipe).
Report handlers are useful for gathering information about a chef-client run (e.g. what cookbook versions were run, what resources were updated). Exception handlers are useful to capture information about failed runs, or to perform cleanup on exception (e.g. cleaning up frozen filesystem resources).
Using the built-in handlers
The most basic place to start is being able to run one of the built-in handlers. At current time of writing, there are two handlers built in to the chef-client: the json_file handler, and the error_report handler. The benefit of starting here is you don’t have to worry about how to get the handler code onto the nodes that you want to run them on – they’re distributed with the chef-client.
Running the error_report handler
Let’s start with the error_report handler. To run this, all you need to do is use the ‘chef_handler’ cookbook and add the following into a recipe in your runlist:
include_recipe "chef_handler"
chef_handler "Chef::Handler::ErrorReport" do
source "chef/handler/error_report"
action :enable
end
After a chef-client run, this will create a file called ‘failed_run_data.json’ in the chef-client cache (typically ‘/var/chef/cache’) on the node it is running on.
Despite its name, this handler can be useful whether or not the run fails. Assuming your run succeeded, here’s what you’ll find in the ‘failed_run_data.json’ file.
{
"node": {
"name": "m2",
"chef_environment": "_default",
"json_class": "Chef::Node",
"automatic": {
"kernel": {
"name": "Linux",
...
The JSON data starts off with details about the node attributes, similar to what you get with ‘knife node show m2 -l -Fjson'.
"success": true,
"start_time": "2014-08-31 20:43:53 +0000",
"end_time": "2014-08-31 20:44:28 +0000",
"elapsed_time": 34.995100522,
It then lists some basic details about the chef-client run.
"all_resources": [
{
"json_class": "Chef::Resource::ChefHandler",
...
}
],
"updated_resources": [
{
"json_class": "Chef::Resource::ChefHandler",
...
}
],
The next JSON elements describe all of the resources that were part of the chef-client run, and which were updated.
"exception": null,
"backtrace": null,
"run_id": "53e02623-1bc9-4b33-a08d-eeb89936feca"
And then finally there is information about the exception that occurred (which is null in this case, a successful run).
Running error_report handler when an exception occurs
Let’s create an exception by adding an invalid resource to the recipe:
include_recipe "chef_handler"
execute "brokenthing"
chef_handler "Chef::Handler::ErrorReport" do
source "chef/handler/error_report"
action :enable
end
The chef-client run will fail with an error:
Errno::ENOENT: No such file or directory - brokenthing
But if you copied my recipe, the error report won’t have been updated! Why?
The problem is that the failing ‘execute’ resource happened before the error report handler was enabled. If you move the ‘execute’ resource after the chef_handler resource, the error report will be created. So one takeaway is that it is good practice to define handlers in a recipe that you put at the start of the runlist. But that’s not all that you want to do.
If the handler is the first resource encountered in the run, then it will report any errors happening when subsequent resources are executed. But sometimes exceptions happen before this, in what’s called the ‘compile’ phase (see About the chef-client Run). This is the phase where the chef-client constructs a list of all of the resources and actions that it is meant to perform, which it then executes in the ‘converge’ phase. For a much deeper explanation of this, see The chef resource run queue.
What we want to do is to enable the error report handler as early as possible in the compile phase, so it can catch errors occurring during this phase too. Here’s how to do that:
include_recipe "chef_handler"
execute "brokenthing"
chef_handler "Chef::Handler::ErrorReport" do
source "chef/handler/error_report"
action :nothing
end.run_action(:enable)
The end.run_action(:enable) tells Chef to do the “enable” action immediately on encountering the resource (i.e. during ‘compile’). The action :nothing tells Chef that it does not need to do anything during the ‘converge’ phase (as its already been enabled).
With this change, now you will find that the end of the error report has exception and backtrace information:
"exception": "Errno::ENOENT: execute[brokenthing] (testapp::handlers line 11) had an error: Errno::ENOENT: No such file or directory - brokenthing",
"backtrace": [
"/opt/chef/embedded/lib/ruby/gems/1.9.1/gems/mixlib-shellout-1.4.0/lib/mixlib/shellout/unix.rb:320:in `exec'",
"/opt/chef/embedded/lib/ruby/gems/1.9.1/gems/mixlib-shellout-1.4.0/lib/mixlib/shellout/unix.rb:320:in `block in fork_subprocess'",
...
Only running error_report on exception
Perhaps you do not want to run the error_report handler on every run, just when an exception occurs. To do this, we override the default supports attribute on the resource to specify it should be used with exceptions only:
chef_handler "Chef::Handler::ErrorReport" do
source "chef/handler/error_report"
action :nothing
supports :exception=>true
end.run_action(:enable)
Replace :exception with :report if you only want the handler to run when the run is successful.
Running the json_file handler
The json_file handler is like the error_report handler, but puts the results into a timestamped file. The following chef_handler resource will result in data being written to /var/chef/reports/chef-run-report-20140831204047.json, for a run that started at 20:40:47 on 31st August 2014.
chef_handler 'Chef::Handler::JsonFile' do
source 'chef/handler/json_file';
arguments :path => '/var/chef/reports'
action :nothing
end.run_action(:enable)
This example illustrates how to pass parameters into a handler.
You can also choose to use the ‘json_file’ recipe in the chef_handler cookbook to achieve the same result.
An alternative – using the client.rb file
An alternative (as described in the Chef docs) to enabling the handler using the chef_handler resource is to add the following to the client.rb file (or solo.rb file):
require 'chef/handler/json_file'
report_handlers << Chef::Handler::JsonFile.new(:path => "/var/chef/reports")
exception_handlers << Chef::Handler::JsonFile.new(:path => "/var/chef/reports")
Using a custom handler
The next step is to use a custom handler, i.e. one that is not built into the chef-client. The extra dimension here is that you need to get the handler code onto the node before it is run. You can do this by putting your handler source in the ‘files’ directory of your cookbook and using a cookbook_file resource to transfer it to the node, e.g.:
cookbook_file "#{node["chef_handler"]["handler_path"]}/your_handler.rb" do
source "your_handler.rb"
owner "root"
group "root"
mode 00755
action :nothing
end.run_action(:create)
The expression #{node["chef_handler"]["handler_path"]} gives you the directory in which the chef_handler resource expects to find your handler. As previously, we run the cookbook_file resource immediately to ensure the handler file is created during the compile phase, before the handler itself is run. If the handler doesn’t run until the converge phase, you can replace the last two lines with:
action :create
end
The chef_handler::default recipe can also be used to transfer handlers to the target node. You will need to make a copy of the chef_handlers cookbook and place your handlers in the ‘files/default/handlers’ directory of that cookbook (or copy the code from the default recipe into your handler cookbook).
To enable this handler, you would then define a chef_handler resource that refers to the transferred handler file:
chef_handler 'YourHandlerModule::YourHandler' do
source "#{node["chef_handler"]["handler_path"]}/your_handler.rb";
action :nothing
end.run_action(:enable)
For a real example you can try using, see Julian Dunn’s cookbook version handler.
Writing your own handler
To write a handler, you need to create a Ruby class that inherits from Chef::Handler and has a report method:
module YourHandlerModule
class YourHandler < Chef::Handler
def report
# Handler code goes here
end
end
end
Put this code in the ‘your_handler.rb’ file in the ‘files’ directory of your handler cookbook.
Within the handler you can write arbitrary Ruby code, and you can use ‘run_status’ information available from the chef-client run. ‘run_status’ is basically the same information that is output by the ‘error_report’ handler. The information can be accessed through the following methods in the Ruby code:
data – a hash containing the run statusstart_time, end_time, elapsed_time – times for the chef-client runupdated_resources, all_resources – the resources in the chef-client runsuccess?, failed? – methods that indicate if the chef-client run succeeded or failed
In the handler, you can access these directly or via the run_status object, e.g. ‘run_status.success?’ is equivalent to ‘success?’.
So for example, I can write the following handler:
require 'chef/log'
module TestApp
module Handlers
class UpdatedResources < Chef::Handler
def report
if success?
Chef::Log.info('Running Updated Resources handler after successful chef-client run')
else
Chef::Log.info('Running Updated Resources handler after failed chef-client run')
end
Chef::Log.info('Updated resources are:')
updated_resources.each do |resource|
Chef::Log.info(resource.to_s)
end
end
end
end
end
In the above, I use the success? method to test whether the run succeeded or not, and the updated_resources to loop through each resource updated during the run, and print it out as a string.
If you run ‘chef-client -linfo’ on the target node, you will see output similar to:
[2014-09-01T14:48:02+00:00] INFO: Running Updated Resources handler after successful chef-client run
[2014-09-01T14:48:02+00:00] INFO: Updated resources are:
[2014-09-01T14:48:02+00:00] INFO: chef_handler[Chef::Handler::JsonFile]
[2014-09-01T14:48:02+00:00] INFO: chef_handler[Chef::Handler::ErrorReport]
[2014-09-01T14:48:02+00:00] INFO: chef_handler[TestApp::Handlers::UpdatedResources]
- TestApp::Handlers::UpdatedResources
Running handlers complete
In this case, the only updated resources in the chef-client run are the three chef_handlers in my handlers recipe. ‘chef_handler[TestApp::Handlers::UpdatedResources]’ is how the UpdatedResources handler is represented as a string.
You can also use the ‘to_hash’ method in place to ‘to_s’ in the above, to see what information is available about the resource. If you did this, you would see something like the following:
2014-09-01T14:54:25+00:00] INFO: {:name=>"TestApp::Handlers::UpdatedResources", :noop=>nil,
:before=>nil, :params=>{}, :provider=>nil, :allowed_actions=>[:nothing, :enable, :disable],
:action=>[:nothing], :updated=>true, :updated_by_last_action=>false,
:supports=>{:report=>true, :exception=>true}, :ignore_failure=>false, :retries=>0, :retry_delay=>2,
:source_line=>"/var/chef/cache/cookbooks/testapp/recipes/handlers.rb:41:in `from_file'",
:guard_interpreter=>:default, :elapsed_time=>0.000480376, :resource_name=>:chef_handler,
:cookbook_name=>"testapp", :recipe_name=>"handlers",
:source=>"/var/chef/handlers/testapp_handlers.rb", :arguments=>[],
:class_name=>"TestApp::Handlers::UpdatedResources"}
From this, you might decide just to print out the name of the resource, e.g.:
updated_resources.each do |resource|
Chef::Log.info("Updated resource with name: " + resource.to_hash[:name])
end
Don’t expect ‘to_hash’ to work in all cases – it depends on whether it has been implemented in the relevant Ruby class. And be aware it may not be the best way to access the data. For example, the above can better be achieved using the name method on the resource, i.e. ‘resource.name’ in place of ‘resource.to_hash[:name]’. Over time, you’ll want to get comfortable with using debuggers to look at the data and reading the chef source code to understand how best to access it.
As well as ‘run_status’, you also have access to the run_context. I’ve included links to a couple of examples using the run context below.
Chef Handler with a parameter
If you want to pass a parameter into your handler, you need to add an initialize method to the handler, as below. This allows you to set the arguments attribute in chef_handler, which is passed to the initialize method as a parameter called ‘config’.
class UpdatedResourcesToFile < Chef::Handler
def initialize(config={})
@config = config
@config[:path] ||= "/var/chef/reports"
@config
end
def report
File.open(File.join(@config[:path], "lastrun-updated-resources.json"), "w") do |file|
updated_resources.each do |resource|
file.puts(resource.to_s)
end
end
end
end
What the above initialize method does is store the parameters in an attribute of the handler class called ‘@config’, and also sets a default value for the ‘path’ parameter. The ‘@’ indicates an attribute and means that the value is available to other methods in the class. The ‘report’ method can then access the path parameter using ‘@config[:path]’.
To enable the above handler, put something like the following in your handler recipe. You will also need to add a resource to create the path, if it doesn’t already exist.
chef_handler "TestApp::Handlers::UpdatedResourcesToFile" do
source "#{node["chef_handler"]["handler_path"]}/testapp_handlers.rb"
arguments :path => '/tmp'
action :nothing
supports :report=>true, :exception=>true
end.run_action(:enable)
In the above, I am overriding the default path value so that the file is written out to ‘/tmp’ instead.
Examples of handlers
Here are some examples of handlers that you may find useful:
Graphs and Chef and Javascript - oh my! 