How to learn more about the activity of your nodes.
Reports and Reporting
Puppet clients can be configured to send reports at the end of every configuration run. These reports include all of the log messages generated during the configuration run and metrics related to what happened on that run.
The bulk of the report is every log message generated during the transaction. This is a simple way to send almost all client logs to the Puppet server; you can use the log report to send all of these client logs to syslog on the server.
The rest of the report contains some basic metrics describing what happened in the transaction. There are three types of metrics in each report, and each type of metric has one or more values:
- Time: Keeps track of how long things took.
- Total: Total time for the configuration run
- Config Retrieval: How long the configuration took to retrieve
- Resources: Keeps track of the following stats:
- Total: The total number of resources being managed
- Skipped: How many resources were skipped, because of either tagging or scheduling restrictions
- Scheduled: How many resources met any scheduling restrictions
- Out of Sync: How many resources were out of sync
- Applied: How many resources were attempted to be fixed
- Failed: How many resources were not successfully fixed
- Restarted: How many resources were restarted because their dependencies changed
- Failed Restarts: How many resources could not be restarted
- Changes: The total number of changes in the transaction.
Setting Up Reporting
By default, the agent does not send reports, and the master is only configured to store reports, which just dumps reports as YAML
Make Agent Nodes Send Reports
# # /etc/puppet/puppet.conf # [agent] report = true
With this setting enabled, the agent will then send the report to the puppet master server at the end of every transaction.
Agents default to sending reports to the same server they get
their configurations from, but you can change that by setting
reportserver, so if you have load-balanced Puppet
servers you can keep all of your reports consolidated on a single
machine. (This is unimportant if the puppet masters are using report processors like
puppetdb, which just hand off reports to an external system.)
Make Masters Process Reports
By default, the puppet master server stores incoming YAML reports to
disk in the
reportdir. There are other report types available that can process each report as it arrives; you can use Puppet’s built-in report processors, write custom report processor plugins, or write an out-of-band report analyzer task that consumes the stored YAML reports on your own schedule.
Using Built-In Reports
Select the report processors to use with the
reports setting in the puppet master’s
puppet.conf file. This setting should be a comma-separated list of report processors to use; if there is more than one, Puppet will run all of them.
The most useful one is usually the
http processor, which sends reports to an arbitrary URL. Puppet Dashboard uses this, and it’s easy enough to write a web service that consumes reports.
The PuppetDB terminus plugins also include a
puppetdb report processor.
Writing Custom Reports
You can easily write your own report processor in place of any of
the built-in reports. Put the report into the puppet master’s
lib/puppet/reports directory to make it available.
Documentation of the report plugin API is forthcoming; however, you can use the built-in reports as a guide, or use and/or hack one of these simple custom reports:
- Report failed runs to an IRC channel
- Report failed runs and logs to PagerDuty
- Report failed runs to Jabber/XMPP
- Report failed runs to Twitter
- Report failed runs and logs to Campfire
- Report failed runs to Twilio
- Report failed runs to Boxcar
- Report failed runs to HipChat
- Send metrics to a Ganglia server via gmetric
- Report failed runs to Growl
These example reports were posted to the Puppet users group by a Puppet Labs employee, and are linked here for educational purposes.
When writing a report processor, you will need to handle a Puppet::Transaction::Report object provided by Puppet. See Report Formats below.
Using External Report Processors
Alternately, you can use the default
store report and write an external
report processor that reads in and analyzes the saved YAML files. This is ideal for analyzing large amounts of reports on demand, and allows the report processor to be written in any common scripting language.
Puppet creates reports as Puppet::Transaction::Report objects, which have changed format several times over the course of Puppet’s history. We have report format references for the following Puppet versions:
- Puppet 3.x (report format 3)
- Puppet 2.7.x (report formats 3 and 2)
- Puppet 2.6.x (report formats 2 and 1)
- Puppet 0.25.5 (report format 0)
The report format applies to both the Ruby object handed to a report processor and the YAML object written to disk by the default