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