Class: Puppet::Transaction::Report

Inherits:
Object
  • Object
show all
Extended by:
Indirector
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.

Defined Under Namespace

Classes: Msgpack, Processor, Rest, Yaml

Constant Summary

Constants included from Indirector

Indirector::BadNameRegexp

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Indirector

configure_routes, indirects

Constructor Details

#initialize(kind, configuration_version = nil, environment = nil, transaction_uuid = nil) ⇒ Report

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.

Returns a new instance of Report.



172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
 
# 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

Instance Attribute Details

#configuration_version ⇒ ???

TODO:

Uncertain what this is?

The version of the configuration

Returns:

  • (???) —

    the configuration version



45
46
47
 
# File 'lib/puppet/transaction/report.rb', line 45

def configuration_version
  @configuration_version
end

#environment ⇒ String

The name of the environment the host is in

Returns:

  • (String) —

    the environment name



57
58
59
 
# File 'lib/puppet/transaction/report.rb', line 57

def environment
  @environment
end

#host ⇒ String

The host name for which the report is generated

Returns:



53
54
55
 
# File 'lib/puppet/transaction/report.rb', line 53

def host
  @host
end

#kind ⇒ String (readonly)

The ‘kind’ of report is the name of operation that triggered the report to be produced. Typically “apply”.

Returns:

  • (String) —

    the kind of operation that triggered the generation of the report.



82
83
84
 
# File 'lib/puppet/transaction/report.rb', line 82

def kind
  @kind
end

#logs ⇒ Array<Puppet::Util::Log> (readonly)

A list of log messages.

Returns:



65
66
67
 
# File 'lib/puppet/transaction/report.rb', line 65

def logs
  @logs
end

#metrics ⇒ Hash<{String => Object}> (readonly)

TODO:

Uncertain if all values are numbers - now marked as Object.

A hash of metric name to metric value.

Returns:



71
72
73
 
# File 'lib/puppet/transaction/report.rb', line 71

def metrics
  @metrics
end

#puppet_version ⇒ String (readonly)

Returns The Puppet version in String form.

Returns:

  • (String) —

    The Puppet version in String form.

See Also:

  • version()


92
93
94
 
# File 'lib/puppet/transaction/report.rb', line 92

def puppet_version
  @puppet_version
end

#report_format ⇒ Integer (readonly)

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

Returns:

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



98
99
100
 
# File 'lib/puppet/transaction/report.rb', line 98

def report_format
  @report_format
end

#resource_statuses ⇒ Hash{String => Puppet::Resource::Status} (readonly)

A hash with a map from resource to status

Returns:



61
62
63
 
# File 'lib/puppet/transaction/report.rb', line 61

def resource_statuses
  @resource_statuses
end

#status ⇒ String (readonly)

The status of the client run is an enumeration: ‘failed’, ‘changed’ or ‘unchanged’

Returns:

  • (String) —

    the status of the run - one of the values ‘failed’, ‘changed’, or ‘unchanged’



87
88
89
 
# File 'lib/puppet/transaction/report.rb', line 87

def status
  @status
end

#time ⇒ Time (readonly)

The time when the report data was generated.

Returns:

  • (Time) —

    A time object indicating when the report data was generated



76
77
78
 
# File 'lib/puppet/transaction/report.rb', line 76

def time
  @time
end

#transaction_uuid ⇒ String

An agent generated transaction uuid, useful for connecting catalog and report

Returns:



49
50
51
 
# File 'lib/puppet/transaction/report.rb', line 49

def transaction_uuid
  @transaction_uuid
end

Class Method Details

.default_format ⇒ Object 



326
327
328
 
# File 'lib/puppet/transaction/report.rb', line 326

def self.default_format
  Puppet[:report_serialization_format].intern
end

.from_data_hash(data) ⇒ Object 



100
101
102
103
104
 
# 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) ⇒ Object 



106
107
108
109
 
# 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

.supported_formats ⇒ Object 



322
323
324
 
# File 'lib/puppet/transaction/report.rb', line 322

def self.supported_formats
  [:pson, :yaml]
end

Instance Method Details

#<<(msg) ⇒ Object

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. 



116
117
118
119
 
# File 'lib/puppet/transaction/report.rb', line 116

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

#add_metric(name, hash) ⇒ Object

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. 



127
128
129
130
131
132
133
134
135
136
 
# 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) ⇒ Object

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. 



139
140
141
 
# File 'lib/puppet/transaction/report.rb', line 139

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

#add_times(name, value) ⇒ Object

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. 



122
123
124
 
# File 'lib/puppet/transaction/report.rb', line 122

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

#as_logging_destination(&block) ⇒ Object 



111
112
113
 
# 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) ⇒ Object

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. 



144
145
146
147
148
149
150
151
152
 
# 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 ⇒ Integer

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

Returns:

  • (Integer) —

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



308
309
310
311
312
313
314
 
# 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 ⇒ Object

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. 



160
161
162
163
164
165
166
167
168
169
 
# 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) ⇒ Object

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. 



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
214
215
216
217
218
219
220
221
 
# 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 ⇒ String

Returns the host name.

Returns:



244
245
246
 
# File 'lib/puppet/transaction/report.rb', line 244

def name
  host
end

#prune_internal_data ⇒ Object

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. 



155
156
157
 
# 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 ⇒ Hash<{String => Object}>

Provides a raw hash summary of this report.

Returns:



283
284
285
286
287
288
289
290
291
292
293
294
295
296
 
# 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 ⇒ String

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.



253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
 
# 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 ⇒ Object 



223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
 
# 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 ⇒ Object

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. 



318
319
320
 
# File 'lib/puppet/transaction/report.rb', line 318

def to_yaml_properties
  super - [:@external_times]
end