Docs: Reporting


Reporting

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.

Logs

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.

Metrics

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
    • File:
    • Exec:
    • User:
    • Group:
    • Config Retrieval: How long the configuration took to retrieve
    • Service:
    • Package:
  • 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 in the reportdir.

Make Agent Nodes Send Reports

Set the report setting in the puppet.conf file to true in order to turn on reporting on agent nodes.

#
#  /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 http or 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:

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.

Report Formats

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:

The report format applies to both the Ruby object handed to a report processor and the YAML object written to disk by the default store processor.

↑ Back to top