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.



178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
 
# File 'lib/puppet/transaction/report.rb', line 178

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 = 5
  @puppet_version = Puppet.version
  @configuration_version = configuration_version
  @transaction_uuid = transaction_uuid
  @code_id = nil
  @catalog_uuid = nil
  @cached_catalog_status = nil
  @environment = environment
  @status = 'failed' # assume failed until the report is finalized
end

Instance Attribute Details

#cached_catalog_status ⇒ String

Whether a cached catalog was used in the run, and if so, the reason that it was used. or ‘on_failure’

Returns:

  • (String) —

    One of the values: ‘not_used’, ‘explicitly_requested’,



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

def cached_catalog_status
  @cached_catalog_status
end

#catalog_uuid ⇒ Object

A master generated catalog uuid, useful for connecting a single catalog to multiple reports.



55
56
57
 
# File 'lib/puppet/transaction/report.rb', line 55

def catalog_uuid
  @catalog_uuid
end

#code_id ⇒ Object

The id of the code input to the compiler.



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

def code_id
  @code_id
end

#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



68
69
70
 
# File 'lib/puppet/transaction/report.rb', line 68

def environment
  @environment
end

#host ⇒ String

The host name for which the report is generated

Returns:

  • (String) —

    the host name



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

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.



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

def kind
  @kind
end

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

A list of log messages.

Returns:



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

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:

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

    A map of metric name to value.



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

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()


103
104
105
 
# File 'lib/puppet/transaction/report.rb', line 103

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.



109
110
111
 
# File 'lib/puppet/transaction/report.rb', line 109

def report_format
  @report_format
end

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

A hash with a map from resource to status

Returns:



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

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’



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

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



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

def time
  @time
end

#transaction_uuid ⇒ String

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

Returns:

  • (String) —

    uuid



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

def transaction_uuid
  @transaction_uuid
end

Class Method Details

.default_format ⇒ Object 



351
352
353
 
# File 'lib/puppet/transaction/report.rb', line 351

def self.default_format
  :pson
end

.from_data_hash(data) ⇒ Object 



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

def self.from_data_hash(data)
  obj = self.allocate
  obj.initialize_from_hash(data)
  obj
end

.supported_formats ⇒ Object 



347
348
349
 
# File 'lib/puppet/transaction/report.rb', line 347

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. 



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

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. 



133
134
135
136
137
138
139
140
141
142
 
# File 'lib/puppet/transaction/report.rb', line 133

def add_metric(name, hash)
  metric = Puppet::Util::Metric.new(name)

  hash.each do |metric_name, value|
    metric.newvalue(metric_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. 



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

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. 



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

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

#as_logging_destination(&block) ⇒ Object 



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

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. 



150
151
152
153
154
155
156
157
158
 
# File 'lib/puppet/transaction/report.rb', line 150

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.



333
334
335
336
337
338
339
 
# File 'lib/puppet/transaction/report.rb', line 333

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. 



166
167
168
169
170
171
172
173
174
175
 
# File 'lib/puppet/transaction/report.rb', line 166

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. 



198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
 
# File 'lib/puppet/transaction/report.rb', line 198

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 catalog_uuid = data['catalog_uuid']
    @catalog_uuid = catalog_uuid
  end

  if code_id = data['code_id']
    @code_id = code_id
  end

  if cached_catalog_status = data['cached_catalog_status']
    @cached_catalog_status = cached_catalog_status
  end

  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:

  • (String) —

    the host name



269
270
271
 
# File 'lib/puppet/transaction/report.rb', line 269

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. 



161
162
163
 
# File 'lib/puppet/transaction/report.rb', line 161

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:

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

    A hash with metrics key to value map



308
309
310
311
312
313
314
315
316
317
318
319
320
321
 
# File 'lib/puppet/transaction/report.rb', line 308

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 |metric_name, label, value|
      report[key][metric_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.



278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
 
# File 'lib/puppet/transaction/report.rb', line 278

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 



245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
 
# File 'lib/puppet/transaction/report.rb', line 245

def to_data_hash
  {
    'host' => @host,
    'time' => @time.iso8601(9),
    'configuration_version' => @configuration_version,
    'transaction_uuid' => @transaction_uuid,
    'catalog_uuid' => @catalog_uuid,
    'code_id' => @code_id,
    'cached_catalog_status' => @cached_catalog_status,
    '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. 



343
344
345
 
# File 'lib/puppet/transaction/report.rb', line 343

def to_yaml_properties
  super - [:@external_times]
end