class Puppet::Transaction::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

Attributes

configuration_version[RW]

The version of the configuration @todo Uncertain what this is? @return [???] the configuration version

environment[RW]

The name of the environment the host is in @return [String] the environment name

host[RW]

The host name for which the report is generated @return [String] the host name

kind[R]

The ‘kind’ of report is the name of operation that triggered the report to be produced. Typically “apply”. @return [String] the kind of operation that triggered the generation of the report.

logs[R]

A list of log messages. @return [Array<Puppet::Util::Log>] logged messages

metrics[R]

A hash of metric name to metric value. @return [Hash<{String => Object}>] A map of metric name to value. @todo Uncertain if all values are numbers - now marked as Object.

puppet_version[R]

@return [String] The Puppet version in String form. @see Puppet.version

report_format[R]

@return [Integer] report format version number. This value is constant for

a given version of Puppet; it is incremented when a new release of Puppet
changes the API for the various objects that make up a report.

resource_statuses[R]

A hash with a map from resource to status @return [Hash{String => Puppet::Resource::Status}] Resource name to status.

status[R]

The status of the client run is an enumeration: ‘failed’, ‘changed’ or ‘unchanged’ @return [String] the status of the run - one of the values ‘failed’, ‘changed’, or ‘unchanged’

time[R]

The time when the report data was generated. @return [Time] A time object indicating when the report data was generated

transaction_uuid[RW]

An agent generated transaction uuid, useful for connecting catalog and report @return [String] uuid

Public Instance Methods

<<(msg) click to toggle source

@api private

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

add_metric(name, hash) click to toggle source

@api private

# File lib/puppet/transaction/report.rb, line 127
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 139
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 122
def add_times(name, value)
  @external_times[name] = value
end

as_logging_destination(&block) click to toggle source

# File lib/puppet/transaction/report.rb, line 111
def as_logging_destination(&block)
  Puppet::Util::Log.with_destination(self, &block)
end

compute_status(resource_metrics, change_metric) click to toggle source

@api private

# File lib/puppet/transaction/report.rb, line 144
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 resource failures or resources that failed to restart

@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 308
def exit_status
  status = 0
  status |= 2 if @metrics["changes"]["total"] > 0
  status |= 4 if @metrics["resources"]["failed"] > 0
  status |= 4 if @metrics["resources"]["failed_to_restart"] > 0
  status
end

finalize_report() click to toggle source

@api private

# File lib/puppet/transaction/report.rb, line 160
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

initialize_from_hash(data) click to toggle source

@api private

# File lib/puppet/transaction/report.rb, line 189
def initialize_from_hash(data)
  @puppet_version = data['puppet_version']
  @report_format = data['report_format']
  @configuration_version = data['configuration_version']
  @transaction_uuid = data['transaction_uuid']
  @environment = data['environment']
  @status = data['status']
  @host = data['host']
  @time = data['time']
  if @time.is_a? String
    @time = Time.parse(@time)
  end
  @kind = data['kind']

  @metrics = {}
  data['metrics'].each do |name, hash|
    @metrics[name] = Puppet::Util::Metric.from_data_hash(hash)
  end

  @logs = data['logs'].map do |record|
    Puppet::Util::Log.from_data_hash(record)
  end

  @resource_statuses = {}
  data['resource_statuses'].map do |record|
    if record[1] == {}
      status = nil
    else
      status = Puppet::Resource::Status.from_data_hash(record[1])
    end
    @resource_statuses[record[0]] = status
  end
end

name() click to toggle source

@return [String] the host name @api public

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

prune_internal_data() click to toggle source

@api private

# File lib/puppet/transaction/report.rb, line 155
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 283
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 253
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_data_hash() click to toggle source

# File lib/puppet/transaction/report.rb, line 223
def to_data_hash
  {
    'host' => @host,
    'time' => @time.iso8601(9),
    'configuration_version' => @configuration_version,
    'transaction_uuid' => @transaction_uuid,
    'report_format' => @report_format,
    'puppet_version' => @puppet_version,
    'kind' => @kind,
    'status' => @status,
    'environment' => @environment,

    'logs' => @logs,
    'metrics' => @metrics,
    'resource_statuses' => @resource_statuses,
  }
end

to_yaml_properties() click to toggle source

@api private

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

Public Class Methods

default_format() click to toggle source

# File lib/puppet/transaction/report.rb, line 326
def self.default_format
  Puppet[:report_serialization_format].intern
end

from_data_hash(data) click to toggle source

# File lib/puppet/transaction/report.rb, line 100
def self.from_data_hash(data)
  obj = self.allocate
  obj.initialize_from_hash(data)
  obj
end

from_pson(data) click to toggle source

# File lib/puppet/transaction/report.rb, line 106
def self.from_pson(data)
  Puppet.deprecation_warning("from_pson is being removed in favour of from_data_hash.")
  self.from_data_hash(data)
end

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

@api private

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

supported_formats() click to toggle source

# File lib/puppet/transaction/report.rb, line 322
def self.supported_formats
  [:pson, :yaml]
end