The anatomy of a report processor

Exclusive offer: get 50% off this eBook here
Puppet Reporting and Monitoring

Puppet Reporting and Monitoring — Save 50%

Create insightful reports for your server infrastructure using Puppet with this book and ebook

$17.99    $9.00
by Michael Duffy | June 2014 | Open Source

This article by Michael Duffy, the author of Puppet Reporting and Monitoring, describes the anatomy of a report processor and how to create a report processor.

(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 Reporting and Monitoring Create insightful reports for your server infrastructure using Puppet with this book and ebook
Published: June 2014
eBook Price: $17.99
Book Price: $29.99
See more
Select your format and quantity:

About the Author :


Michael Duffy

Michael Duffy has been working in systems administration and automation for more years than he cares to remember, and is the founder of Stunt Hamster Ltd.; a small but perfectly formed consultancy that helps companies, both small and large, deliver fully automated and scalable infrastructure. He has consulted for companies such as O2 and BSkyB, delivering design, automation, and monitoring of infrastructure for products that serve millions of users.

Michael is a keen advocate of DevOps methodologies and is especially interested in using automation to not only deliver scalable and reliable systems, but also to make sure that people can see what is actually going on under the hood when using reporting tools. If given the chance, he will happily spend hours telling you how fantastic it is that people from the development and operations fields can finally talk and go to the pub together.

Books From Packt


Chef Infrastructure Automation Cookbook
Chef Infrastructure Automation Cookbook

Puppet 3 Cookbook
Puppet 3 Cookbook

Puppet 2.7 Cookbook
Puppet 2.7 Cookbook

 Puppet 3 Beginner’s Guide
Puppet 3 Beginner’s Guide

Instant Puppet 3 Starter
Instant Puppet 3 Starter

 Learning Chef
Learning Chef

Instant Chef Starter
Instant Chef Starter

 Managing Windows Servers with Chef
Managing Windows Servers with Chef


Code Download and Errata
Packt Anytime, Anywhere
Register Books
Print Upgrades
eBook Downloads
Video Support
Contact Us
Awards Voting Nominations Previous Winners
Judges Open Source CMS Hall Of Fame CMS Most Promising Open Source Project Open Source E-Commerce Applications Open Source JavaScript Library Open Source Graphics Software
Resources
Open Source CMS Hall Of Fame CMS Most Promising Open Source Project Open Source E-Commerce Applications Open Source JavaScript Library Open Source Graphics Software