# class Report

This class is used to report what happens on a client. There are two types of data in a report; Logs and Metrics.

- *Logs* - are the output that each change produces.

- *Metrics* - are all of the numerical data involved in the transaction.

Use {Puppet::Reports} class to create a new custom report type. This class is indirectly used as a source of data to report in such a registered report.

##Metrics 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.

@api public

### Public Class Methods

default_format() click to toggle source

This is necessary since Marshal doesn’t know how to dump hash with default proc (see below “@records”) ? @todo there is no “@records” to see below, uncertain what this is for. @api private

    # File lib/puppet/transaction/report.rb, line 101
    def self.default_format
      :yaml
    end

new(kind, configuration_version=nil, environment=nil) click to toggle source

@api private

    # File lib/puppet/transaction/report.rb, line 162
    def initialize(kind, configuration_version=nil, environment=nil)
      @metrics = {}
      @logs = []
      @resource_statuses = {}
      @external_times ||= {}
      @host = Puppet[:node_name_value]
      @time = Time.now
      @kind = kind
      @report_format = 3
      @puppet_version = Puppet.version
      @configuration_version = configuration_version
      @environment = environment
      @status = 'failed' # assume failed until the report is finalized
    end

### Public Instance Methods

<<(msg) click to toggle source

@api private

    # File lib/puppet/transaction/report.rb, line 106
    def <<(msg)
      @logs << msg
      self
    end

add_metric(name, hash) click to toggle source

@api private

    # File lib/puppet/transaction/report.rb, line 117
    def add_metric(name, hash)
      metric = Puppet::Util::Metric.new(name)

      hash.each do |name, value|
        metric.newvalue(name, value)
      end

      @metrics[metric.name] = metric
      metric
    end

add_resource_status(status) click to toggle source

@api private

    # File lib/puppet/transaction/report.rb, line 129
    def add_resource_status(status)
      @resource_statuses[status.resource] = status
    end

add_times(name, value) click to toggle source

@api private

    # File lib/puppet/transaction/report.rb, line 112
    def add_times(name, value)
      @external_times[name] = value
    end

compute_status(resource_metrics, change_metric) click to toggle source

@api private

    # File lib/puppet/transaction/report.rb, line 134
    def compute_status(resource_metrics, change_metric)
      if (resource_metrics["failed"] || 0) > 0
        'failed'
      elsif change_metric > 0
        'changed'
      else
        'unchanged'
      end
    end

exit_status() click to toggle source

Computes a single number that represents the report’s status. The computation is based on the contents of this report’s metrics. The resulting number is a bitmask where individual bits represent the presence of different metrics.

- 0x2 set if there are changes

- 0x4 set if there are failures

@return [Integer] A bitmask where 0x2 is set if there are changes, and 0x4 is set of there are failures. @api public

    # File lib/puppet/transaction/report.rb, line 244
    def exit_status
      status = 0
      status |= 2 if @metrics["changes"]["total"] > 0
      status |= 4 if @metrics["resources"]["failed"] > 0
      status
    end

finalize_report() click to toggle source

@api private

    # File lib/puppet/transaction/report.rb, line 150
    def finalize_report
      prune_internal_data

      resource_metrics = add_metric(:resources, calculate_resource_metrics)
      add_metric(:time, calculate_time_metrics)
      change_metric = calculate_change_metric
      add_metric(:changes, {"total" => change_metric})
      add_metric(:events, calculate_event_metrics)
      @status = compute_status(resource_metrics, change_metric)
    end

name() click to toggle source

@return [String] the host name @api public

    # File lib/puppet/transaction/report.rb, line 180
    def name
      host
    end

prune_internal_data() click to toggle source

@api private

    # File lib/puppet/transaction/report.rb, line 145
    def prune_internal_data
      resource_statuses.delete_if {|name,res| res.resource_type == 'Whit'}
    end

raw_summary() click to toggle source

Provides a raw hash summary of this report. @return [Hash<{String => Object}>] A hash with metrics key to value map @api public

    # File lib/puppet/transaction/report.rb, line 219
    def raw_summary
      report = { "version" => { "config" => configuration_version, "puppet" => Puppet.version  } }

      @metrics.each do |name, metric|
        key = metric.name.to_s
        report[key] = {}
        metric.values.each do |name, label, value|
          report[key][name.to_s] = value
        end
        report[key]["total"] = 0 unless key == "time" or report[key].include?("total")
      end
      (report["time"] ||= {})["last_run"] = Time.now.tv_sec
      report
    end

summary() click to toggle source

Provide a human readable textual summary of this report. @note This is intended for debugging purposes @return [String] A string with a textual summary of this report. @api public

    # File lib/puppet/transaction/report.rb, line 189
    def summary
      report = raw_summary

      ret = ""
      report.keys.sort { |a,b| a.to_s <=> b.to_s }.each do |key|
        ret += "#{Puppet::Util::Metric.labelize(key)}:\n"

        report[key].keys.sort { |a,b|
          # sort by label
          if a == :total
            1
          elsif b == :total
            -1
          else
            report[key][a].to_s <=> report[key][b].to_s
          end
        }.each do |label|
          value = report[key][label]
          next if value == 0
          value = "%0.2f" % value if value.is_a?(Float)
          ret += "   %15s %s\n" % [Puppet::Util::Metric.labelize(label) + ":", value]
        end
      end
      ret
    end

to_yaml_properties() click to toggle source

@api private

    # File lib/puppet/transaction/report.rb, line 253
    def to_yaml_properties
      instance_variables - [:@external_times]
    end

### Private Instance Methods

calculate_change_metric() click to toggle source

    # File lib/puppet/transaction/report.rb, line 259
    def calculate_change_metric
      resource_statuses.map { |name, status| status.change_count || 0 }.inject(0) { |a,b| a+b }
    end

calculate_event_metrics() click to toggle source

    # File lib/puppet/transaction/report.rb, line 263
    def calculate_event_metrics
      metrics = Hash.new(0)
      %w{total failure success}.each { |m| metrics[m] = 0 }
      resource_statuses.each do |name, status|
        metrics["total"] += status.events.length
        status.events.each do |event|
          metrics[event.status] += 1
        end
      end

      metrics
    end

calculate_resource_metrics() click to toggle source

    # File lib/puppet/transaction/report.rb, line 276
    def calculate_resource_metrics
      metrics = {}
      metrics["total"] = resource_statuses.length

      # force every resource key in the report to be present
      # even if no resources is in this given state
      Puppet::Resource::Status::STATES.each do |state|
        metrics[state.to_s] = 0
      end

      resource_statuses.each do |name, status|
        Puppet::Resource::Status::STATES.each do |state|
          metrics[state.to_s] += 1 if status.send(state)
        end
      end

      metrics
    end

calculate_time_metrics() click to toggle source

    # File lib/puppet/transaction/report.rb, line 295
    def calculate_time_metrics
      metrics = Hash.new(0)
      resource_statuses.each do |name, status|
        type = Puppet::Resource.new(name).type
        metrics[type.to_s.downcase] += status.evaluation_time if status.evaluation_time
      end

      @external_times.each do |name, value|
        metrics[name.to_s.downcase] = value
      end

      metrics["total"] = metrics.values.inject(0) { |a,b| a+b }

      metrics
    end