Learning the basics of Puppet reporting
Before we get into the nitty-gritty of configuring our Puppet installation, it's worth briefly going over the basics of how Puppet goes about its reporting. At its heart, a Puppet master is a web server and the reporting mechanism reflects this; a Puppet agent performs a simple HTTPS PUT operation to place the reporting information onto a Puppet master. When configured properly, the Puppet master will receive reports from Puppet agents, each and every time they perform a Puppet run, either in the noop or apply mode. Once the reports have been received, we can go ahead and do some fairly fantastic things with the data using a variety of methods to transform, transport, and integrate it with other systems.
The data that the Puppet agent reports back to the Puppet master is made up of two crucial elements: logs and metrics. The Puppet agent creates a full audit log of the events during each run, and when the reporting is enabled, this will be forwarded to the Puppet master. This allows you to see whether there were any issues during the run, and if so, what they were; or, it simply lets you examine what operations the Puppet agent performed if things went smoothly.
The metrics that the Puppet agent passes to the Puppet master are very granular and offer a fantastic insight into where Puppet is spending its time, be it fetching, processing, or applying changes. This can be very important if you are managing a large infrastructure with Puppet; a node that takes four minutes to complete isn't too bad when there are only a handful of them, but it can be downright painful when you are dealing with hundreds of them. It also allows you to start tracking the performance of your Puppet infrastructure over time. Puppet modules have a tendency to start as lean, but as they grow in complexity, they can become sluggish and bloated. Identifying speed issues early can help you refactor your modules into smaller and better performing pieces of code before they start to impact the overall stability and speed of your Puppet infrastructure.
The data derived from the logs and metrics build up a complete picture of your hosts and is enormously useful when it comes to diagnosing issues. For example, without reporting, you may have a hard time diagnosing why every single Puppet agent is suddenly throwing errors when applying the catalog; with reporting, it becomes a relatively easy matter to spot that someone has checked in a common module with a bug. Many sites use modules to manage DNS, NTP, and other common items, and a typo in one of these modules can very quickly ensure that every single host will report errors. Without reporting, you can make shrewd guesses as to the fault, but to actually prove it, you're going to have to log onto multiple nodes to examine the logs. You are going to end up spending a fair chunk of time going from node to node running the agent in the noop mode and comparing logs manually to ensure that it is indeed a common fault. This is based on the assumption that you notice the fault, of course; without the reporting in place, you may find that the nodes can be in poor shape for a substantial time before you realize that something is amiss or that you probably have not been running Puppet at all. Running Puppet on a host that has not been managed for some time may produce a list of changes that is uncomfortably long and could potentially introduce a breaking change somewhere along the line. There are many reasons why a Puppet agent may have stopped running, and you can be in for a shock if it's been a month or two since Puppet was last run on a host. A lot can change in that time, and it's entirely possible that one of the many non-applied changes might create problems in a running service.
Where the Parser is the brains of Puppet, the Facter is its eyes and ears. Before Puppet compiles a manifest, it first consults Facter to figure out a few key things. First and foremost, it needs to know where it is and what it is. These are facts that the Puppet agent can deduce by consulting Facter on elements such as the node's hostname, the number of CPUs, amount of RAM, and so on. Facter knows a surprising amount of information, out of the box, and its knowledge increases with each release. Before Facter 1.7, it was possible to use Ruby code, shipped as a Puppet plugin, to extend the facts you could gather. However, with Facter 1.7, you can also teach Facter some new tricks with external facts. External facts allow you to add to Facter's already prodigious knowledge by including anything from Ruby scripts to plain old YAML files to insert data. These additional points of data can be utilized within Puppet reports in the same way as any default Facter item, and they can also be used to add additional context around the existing data.
Now that we know the basics of how Puppet reporting works, it's time to go ahead and configure our Puppet master and agents to report. I'm going to make the assumption that you already have a working copy of either Puppet Open Source or Puppet Enterprise installed; if you haven't, there are some excellent guides available either online at http://Puppetlabs.com/learn or available for purchase elsewhere. If you're going to buy a book, I recommend Puppet 3 Beginner's Guide, John Arundel, Packt Publishing. It is an excellent and complete resource on how to install and use Puppet.
The example configurations I have used are from the latest version of Puppet Open Source (Version 3.2.2 and higher), packaged for Ubuntu. Your configuration may differ slightly if you're following this on another distribution, but it should broadly contain the same settings.
