(For more resources related to this topic, see here.)

At its most basic, a Puppet report processor is a piece of Ruby code that is triggered every time a Puppet agent passes a report to the Puppet master. This piece of code is passed as a Ruby object that contains both the client report and metrics. Although the data is sent in a wire format, such as YAML or PSON, by the time a report processor is triggered, this data is turned into an object by Puppet. This code can simply provide reports, but we’re not limited to that.

With a little imagination, we can use Puppet report processors for everything from alerts through to the orchestration of events. For instance, using a report processor and a suitable SMS provider would make it easy for Puppet to send you an SMS alert every time a run fails, or alternatively, using a report processor, you could analyze the data to reveal trends in your changes and update a change management console. The best way to think of a report processor is that it is a means to trigger actions on the event of a change, rather than strictly a reporting tool.

Puppet reports are written in plain old Ruby, and so you have access to the multitude of libraries available via the RubyGems repositories. This can make developing your plugins relatively simple, as half the time you will find that the heavy lifting has been done for you by some enterprising fellow who has already solved your problem and published his code in a gem. Good examples of this can be found if you need to interoperate with another product such as MySQL, Oracle, Salesforce, and so on. A brief search on the Internet will bring up three or four examples of libraries that will offer this functionality within a few lines of code. Not having to produce the plumbing of a solution will both save time and generally produce fewer bugs.

Creating a basic report processor

Let’s take a look at an incredibly simple report processor example. In the event that a Puppet agent fails to run, the following code will take the incoming data and create a little text file with a short message detailing which host had the problem:

include puppet
   Puppet::Reports::register_report(:myfirstreport) do
	desc "My very first report!"
			def process
			if self.status == 'failed'
			msg = "failed puppet run for #{self.host} #
{self.status}
    File.open('./tmp/puppetpanic.txt', 'w') { | f |
		    f.write(msg)}
    end
		    end
		    end

Although this code is basic, it contains all of the components required for a report processor. The first line includes the only mandatory library required: the Puppet library. This gives us access to several important methods that allow us to register and describe our report processor, and finally, a method to allow us to process our data.

Registering your report processor

The first method that every report processor must call is the Puppet::Reports::register_report method. This method can only take one argument, which is the name of the report processor. This name should be passed as a symbol and an alphanumeric title that starts with a letter (:report3 would be fine, but :3reports would not be). Try to avoid using any other characters—although you can potentially use underscores, the documentation is rather discouragingly vague on how valid this is and could well cause issues.

Describing your report processor

After we’ve called the Puppet::Reports::register_report method, we then need to call the desc method. The desc method is used to provide some brief documentation for what the report processor does and allows the use of Markdown formatting in the string.

Processing your report

The last method that every report processor must include is the process method. The process method is where we actually take our Puppet data and process it, and to make working with the report data easier, you have access to the .self object within the process method. The .self object is a Puppet::Transaction::Report object and gives you access to the Puppet report data. For example, to extract the hostname of the reporting host, we can use the self.host object.

You can find the full details of what is contained in the Puppet::Transaction::Report object by visiting http://docs.puppetlabs.com/puppet/latest/reference/format_report.html.

Let’s go through our small example in detail and look at what it’s doing. First of all, we include the Puppet library to ensure that we have access to the required methods. We then register our report by calling the Puppet::Reports::register_report(:myfirstreport) method and pass it the name of myfirstreport. Next, we add our desc method to tell users what this report is for. Finally, we have the process method, which is where we are going to place our code to process the report. For this example, we’re going to keep it simple and simply check if the Puppet agent reported a successful run or not, and we do this by checking the Puppet status. This is described in the following code snippet:

if self.status == 'failed'
		    msg = "failed puppet run for #{self.host}#{self.status}"

The transaction can produce one of three states: failed, changed, or unchanged. This is straightforward; a failed client run is any run that contains a resource that has a status of failed, a changed state is triggered when the client run contains a resource that has been given a status of changed, and the unchanged state occurs when a resource contains a value of out_of_sync; this generally happens if you run the Puppet client in noop (simulation) mode.

Finally, we actually do something with the data. In the case of this very simple application, we’re going to place the warning into a plain text file in the /tmp directory. This is described in the following code snippet:

msg = "failed puppet run for #{self.host}"
	      File.open('/tmp/puppetpanic.txt', 'w') { | f | f.write(msg)}

As you can see, we’re using basic string interpolation to take some of our report data and place it into the message. This is then written into a simple plain text file in the /tmp directory.

Summary

In this article, we have seen the anatomy of a report processor. We have also seen a basic Ruby code that sets up a simple report processor.

Resources for Article:

Further resources on this subject:

• Puppet: Integrating External Tools [Article]
• Quick start – Using the core Puppet resource types [Article]
• External Tools and the Puppet Ecosystem [Article]