Writing custom report processors

Create and use report processors to generate insightful information or alerts from Puppet reports. You can write your own report processor in Ruby and include it in a Puppet module. Puppet uses the processor to send report data to the service in the format you defined.

A report processor must follow these rules:

• The processor name must be a valid Ruby symbol that starts with a letter and contains only alphanumeric characters.
• The processor must be in its own Ruby file, <PROCESSOR_NAME>.rb, and stored inside the Puppet module directory lib/puppet/reports/
• The processor code must start with require 'puppet'
• The processor code must call the method Puppet::Reports.register_report(:NAME) This method takes the name of the report as a symbol, and a mandatory block of code with no arguments that contains:
  • A Markdown-formatted string describing the processor, passed to the desc(<DESCRIPTION>) method.
  • An implementation of a method named process that contains the report processor's main functionality.

Puppet lets the process method access a self object, which will be a Puppet::Transaction::Report object describing a Puppet run.

The processor can access report data by calling accessor methods on self, and it can forward that data to any service you configure in the report processor. It can also call self.to_yaml to dump the entire report to YAML. Note that the YAML output isn't a safe, well-defined data format — it's a serialized object.

# Located in /etc/puppetlabs/puppet/modules/myreport/lib/puppet/reports/myreport.rb.
require 'puppet'
# If necessary, require any other Ruby libraries for this report here.

Puppet::Reports.register_report(:myreport) do
  desc "Process reports via the fictional my_cool_cmdb API."

  # Declare and configure any settings here. We'll pretend this connects to our API.
  my_api = MY_COOL_CMD

  # Define and configure the report processor.
  def process
    # Do something that sets up the API we're sending the report to here.
    # For instance, let's check on the node's status using the report object (self):
    if self.status != nil then
      status = self.status
    else
      status = 'undefined'
    end

    # Next, let's do something if the status equals 'failed'.
    if status == 'failed' then
      # Finally, dump the report object to YAML and post it using the API object:
      my_api.post(self.to_yaml)
    end
  end
end

reports = store,myreport