Class: Puppet::Transaction::Report

Inherits:
Object
  • Object
show all
Defined in:
lib/puppet/transaction/report.rb

Overview

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

Class Method Summary (collapse)

Instance Method Summary (collapse)

Constructor Details

- (Report) initialize(kind, configuration_version = nil, environment = nil)  private

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

A new instance of Report



162
163
164
165
166
167
168
169
170
171
172
173
174
175
 
# 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

Class Method Details

+ (Object) default_format  private

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

TODO:

there is no “@records” to see below, uncertain what this is for.

This is necessary since Marshal doesn’t know how to dump hash with default proc (see below “@records”) ?



101
102
103
 
# File 'lib/puppet/transaction/report.rb', line 101

def self.default_format
  :yaml
end

Instance Method Details

- (Object) <<(msg)  private

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



106
107
108
109
 
# File 'lib/puppet/transaction/report.rb', line 106

def <<(msg)
  @logs << msg
  self
end

- (Object) add_metric(name, hash)  private

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



117
118
119
120
121
122
123
124
125
126
 
# 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

- (Object) add_resource_status(status)  private

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



129
130
131
 
# File 'lib/puppet/transaction/report.rb', line 129

def add_resource_status(status)
  @resource_statuses[status.resource] = status
end

- (Object) add_times(name, value)  private

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



112
113
114
 
# File 'lib/puppet/transaction/report.rb', line 112

def add_times(name, value)
  @external_times[name] = value
end

- (Object) compute_status(resource_metrics, change_metric)  private

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



134
135
136
137
138
139
140
141
142
 
# 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

- (Integer) exit_status

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

Returns:

  • (Integer) —

    A bitmask where 0x2 is set if there are changes, and 0x4 is set of there are failures.



244
245
246
247
248
249
 
# 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

- (Object) finalize_report  private

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



150
151
152
153
154
155
156
157
158
159
 
# 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

- (String) name

The host name

Returns:

  • (String) —

    the host name



180
181
182
 
# File 'lib/puppet/transaction/report.rb', line 180

def name
  host
end

- (Object) prune_internal_data  private

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



145
146
147
 
# File 'lib/puppet/transaction/report.rb', line 145

def prune_internal_data
  resource_statuses.delete_if {|name,res| res.resource_type == 'Whit'}
end

- (Hash<{String => Object}>) raw_summary

Provides a raw hash summary of this report.

Returns:

  • (Hash<{String => Object}>) —

    A hash with metrics key to value map



219
220
221
222
223
224
225
226
227
228
229
230
231
232
 
# 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

- (String) summary

Note:

This is intended for debugging purposes

Provide a human readable textual summary of this report.

Returns:

  • (String) —

    A string with a textual summary of this report.



189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
 
# 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

- (Object) to_yaml_properties  private

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



253
254
255
 
# File 'lib/puppet/transaction/report.rb', line 253

def to_yaml_properties
  instance_variables - [:@external_times]
end