Puppet can generate data about what happens during a run and we can gather this data in reports. They contain the output of what is executed on the client and details on any action taken during the execution and performance metrics.

Needless to say that we can also extend Puppet reports and deliver them to a variety of destinations: logging systems, database backends, e-mail, chat roots, notification and alerting systems, trouble ticketing software, and web frontends.

Reports may contain the whole output of a Puppet run, a part of them (for example, just the resources that failed) or just the metrics (as it happens with the rrd report that graphs key metrics such as Puppet compilation and run times).

We can distribute our custom report handlers via the pluginsync functionality too: we just need to place them in the lib/puppet/reports/<report_name>.rb path, so that the file name matches the handler name.

James Turnbull, the author of the most popular Puppet books, has written many custom reports for Puppet; here, we analyze the structure of one of his report handlers that sends notifications of failed reports to the PagerDuty service (https://github.com/jamtur01/puppet-pagerduty); it should be placed in a module with this path: lib/puppet/reports/pagerduty.rb.

First, we need to include some required classes. The Puppet class is always required, others may be required depending on the kind of report:

require 'puppet'
require 'json'
require 'yaml'

begin
  require 'redphone/pagerduty'
rescue LoadError => e
  Puppet.info "You need the `redphone` gem to use the PagerDuty report"
end

Next, we call the register_report method or the Puppet::Reports class, passing to it the handler name, as symbol, and its code in a block:

Puppet::Reports.register_report(:pagerduty) do

Here, the report handler uses an external configuration file (/etc/puppet/pagerduty.yaml (note how we can access Puppet configuration entries with Puppet.settings[]), where users can place specific settings (in this case, the PagerDuty API key):

  config_file = File.join(File.dirname(Puppet.settings[:config]), "pagerduty.yaml")
  raise(Puppet::ParseError, "PagerDuty report config file #{config_file} not readable") unless File.exist?(config_file)
  config = YAML.load_file(config_file)
  PAGERDUTY_API = config[:pagerduty_api]

We can use the familiar desc method to place a description of the report:

  desc <<-DESC

Send notification of failed reports to a PagerDuty service. You will need to create a receiving service in PagerDuty that uses the Generic API, and add the API key to configuration file:

  DESC

All the reporting logic is defined in the process method. Here, we can access a lot of information about the report, available as variables of the self object; for example, self.status contains the status of the Puppet run, self.logs all the output text, self.host the host where Puppet has been executed. In this case, the trigger_incident method of the Redphone::Pagerduty class is called and information about a Puppet run is sent if the report status is failed:

  def process
    if self.status == "failed"
      Puppet.debug "Sending status for #{self.host} to PagerDuty."
      details = Array.new
      self.logs.each do |log|
        details << log
      end
      response = Redphone::Pagerduty.trigger_incident(
        :service_key => PAGERDUTY_API,
        :incident_key => "puppet/#{self.host}",
        :description => "Puppet run for #{self.host} #{self.status} at #{Time.now.asctime}",
        :details => details
      )
      case response['status']
      when "success"
        Puppet.debug "Created PagerDuty incident: puppet/#{self.host}"
      else
        Puppet.debug "Failed to create PagerDuty incident: puppet/#{self.host}"
      end
    end
  end
end