Class: Chef::Formatters::Doc

Inherits:
Base show all
Defined in:
lib/chef/formatters/doc.rb

Overview

Formatter similar to RSpec’s documentation formatter. Uses indentation to show context.

Instance Attribute Summary collapse

Attributes inherited from Base

#err, #out, #output

Instance Method Summary collapse

Methods inherited from Base

#attribute_file_load_failed, #attribute_file_loaded, cli_name, #cookbook_sync_failed, #definition_file_load_failed, #definition_file_loaded, #display_error, #file_load_failed, #indent_by, #is_formatter?, #library_file_load_failed, #library_file_loaded, #lwrp_file_load_failed, #lwrp_file_loaded, #print, #puts, #puts_line, #recipe_file_load_failed, #recipe_file_loaded, #recipe_not_found, #registration_failed, #run_list_expand_failed, #start_line

Methods included from ErrorMapper

cookbook_resolution_failed, cookbook_sync_failed, file_load_failed, node_load_failed, registration_failed, resource_failed, run_list_expand_failed

Methods inherited from EventDispatch::Base

#attribute_file_load_failed, #attribute_file_loaded, #attribute_load_complete, #attribute_load_start, #control_group_started, #cookbook_sync_failed, #definition_file_load_failed, #definition_file_loaded, #definition_load_complete, #definition_load_start, #library_file_load_failed, #library_file_loaded, #library_load_complete, #lwrp_file_load_failed, #lwrp_file_loaded, #lwrp_load_complete, #lwrp_load_start, #msg, #recipe_file_load_failed, #recipe_file_loaded, #recipe_load_start, #recipe_not_found, #registration_failed, #resource_completed, #run_list_expand_failed, #run_list_expanded, #run_started, #stream_closed, #stream_opened

Constructor Details

#initialize(out, err) ⇒ Doc

Returns a new instance of Doc.



16
17
18
19
20
21
22
23
24
25
26
 
# File 'lib/chef/formatters/doc.rb', line 16

def initialize(out, err)
  super

  @updated_resources = 0
  @up_to_date_resources = 0
  @successful_audits = 0
  @failed_audits = 0
  @start_time = Time.now
  @end_time = @start_time
  @skipped_resources = 0
end

Instance Attribute Details

#end_time ⇒ Object (readonly)

Returns the value of attribute end_time.



11
12
13
 
# File 'lib/chef/formatters/doc.rb', line 11

def end_time
  @end_time
end

#start_time ⇒ Object (readonly)

Returns the value of attribute start_time.



11
12
13
 
# File 'lib/chef/formatters/doc.rb', line 11

def start_time
  @start_time
end

Instance Method Details

#audit_phase_complete(audit_output) ⇒ Object 



216
217
218
219
 
# File 'lib/chef/formatters/doc.rb', line 216

def audit_phase_complete(audit_output)
  puts_line audit_output
  puts_line "Auditing complete"
end

#audit_phase_failed(error, audit_output) ⇒ Object 



221
222
223
224
225
226
227
228
229
230
231
232
 
# File 'lib/chef/formatters/doc.rb', line 221

def audit_phase_failed(error, audit_output)
  puts_line audit_output
  puts_line ""
  puts_line "Audit phase exception:"
  indent
  puts_line "#{error.message}"
  if error.backtrace
    error.backtrace.each do |l|
      puts_line l
    end
  end
end

#audit_phase_start(run_status) ⇒ Object

Called before audit phase starts



212
213
214
 
# File 'lib/chef/formatters/doc.rb', line 212

def audit_phase_start(run_status)
  puts_line "Starting audit phase"
end

#control_example_failure(control_group_name, example_data, error) ⇒ Object 



238
239
240
 
# File 'lib/chef/formatters/doc.rb', line 238

def control_example_failure(control_group_name, example_data, error)
  @failed_audits += 1
end

#control_example_success(control_group_name, example_data) ⇒ Object 



234
235
236
 
# File 'lib/chef/formatters/doc.rb', line 234

def control_example_success(control_group_name, example_data)
  @successful_audits += 1
end

#converge_complete ⇒ Object

Called when the converge phase is finished.



202
203
204
 
# File 'lib/chef/formatters/doc.rb', line 202

def converge_complete
  unindent if @current_recipe
end

#converge_failed(e) ⇒ Object 



206
207
208
209
 
# File 'lib/chef/formatters/doc.rb', line 206

def converge_failed(e)
  # Currently a failed converge is handled the same way as a successful converge
  converge_complete
end

#converge_start(run_context) ⇒ Object

Called before convergence starts



197
198
199
 
# File 'lib/chef/formatters/doc.rb', line 197

def converge_start(run_context)
  puts_line "Converging #{run_context.resource_collection.all_resources.size} resources"
end

#cookbook_clean_complete ⇒ Object

Called when cookbook cleaning is finished.



160
161
 
# File 'lib/chef/formatters/doc.rb', line 160

def cookbook_clean_complete
end

#cookbook_clean_start ⇒ Object

Called before unneeded cookbooks are removed



150
151
 
# File 'lib/chef/formatters/doc.rb', line 150

def cookbook_clean_start
end

#cookbook_resolution_complete(cookbook_collection) ⇒ Object

Called when the cookbook collection is returned from the server.



146
147
 
# File 'lib/chef/formatters/doc.rb', line 146

def cookbook_resolution_complete(cookbook_collection)
end

#cookbook_resolution_failed(expanded_run_list, exception) ⇒ Object

Called when there is an error getting the cookbook collection from the server.



141
142
143
 
# File 'lib/chef/formatters/doc.rb', line 141

def cookbook_resolution_failed(expanded_run_list, exception)
  super
end

#cookbook_resolution_start(expanded_run_list) ⇒ Object

Called before the cookbook collection is fetched from the server.



135
136
137
 
# File 'lib/chef/formatters/doc.rb', line 135

def cookbook_resolution_start(expanded_run_list)
  puts_line "resolving cookbooks for run list: #{expanded_run_list.inspect}"
end

#cookbook_sync_complete ⇒ Object

Called after all cookbooks have been sync’d.



179
180
181
 
# File 'lib/chef/formatters/doc.rb', line 179

def cookbook_sync_complete
  unindent
end

#cookbook_sync_start(cookbook_count) ⇒ Object

Called before cookbook sync starts



164
165
166
167
 
# File 'lib/chef/formatters/doc.rb', line 164

def cookbook_sync_start(cookbook_count)
  puts_line "Synchronizing Cookbooks:"
  indent
end

#deprecation(message, location = ) ⇒ Object 



371
372
373
374
375
376
377
378
379
 
# File 'lib/chef/formatters/doc.rb', line 371

def deprecation(message, location = caller(2..2)[0])
  if Chef::Config[:treat_deprecation_warnings_as_errors]
    super
  end

  # Save deprecations to the screen until the end
  deprecations[message] ||= Set.new
  deprecations[message] << location
end

#elapsed_time ⇒ Object 



28
29
30
 
# File 'lib/chef/formatters/doc.rb', line 28

def elapsed_time
  end_time - start_time
end

#file_loaded(path) ⇒ Object

Called after a file in a cookbook is loaded.



189
190
 
# File 'lib/chef/formatters/doc.rb', line 189

def file_loaded(path)
end

#handler_executed(handler) ⇒ Object

Called after an individual handler has run



343
344
345
 
# File 'lib/chef/formatters/doc.rb', line 343

def handler_executed(handler)
  puts_line "- #{handler.class.name}"
end

#handlers_completed ⇒ Object

Called after all handlers have executed



348
349
350
351
 
# File 'lib/chef/formatters/doc.rb', line 348

def handlers_completed
  unindent
  puts_line "Running handlers complete\n"
end

#handlers_start(handler_count) ⇒ Object

Called before handlers run



336
337
338
339
340
 
# File 'lib/chef/formatters/doc.rb', line 336

def handlers_start(handler_count)
  puts ""
  puts "Running handlers:"
  indent
end

#indent ⇒ Object 



381
382
383
 
# File 'lib/chef/formatters/doc.rb', line 381

def indent
  indent_by(2)
end

#library_load_start(file_count) ⇒ Object

Called when cookbook loading starts.



184
185
186
 
# File 'lib/chef/formatters/doc.rb', line 184

def library_load_start(file_count)
  puts_line "Compiling Cookbooks..."
end

#node_load_completed(node, expanded_run_list, config) ⇒ Object

Default and override attrs from roles have been computed, but not yet applied. Normal attrs from JSON have been added to the node.



127
128
 
# File 'lib/chef/formatters/doc.rb', line 127

def node_load_completed(node, expanded_run_list, config)
end

#node_load_failed(node_name, exception, config) ⇒ Object

Failed to load node data from the server



121
122
123
 
# File 'lib/chef/formatters/doc.rb', line 121

def node_load_failed(node_name, exception, config)
  super
end

#node_load_start(node_name, config) ⇒ Object 



117
118
 
# File 'lib/chef/formatters/doc.rb', line 117

def node_load_start(node_name, config)
end

#ohai_completed(node) ⇒ Object

Called right after ohai runs.



102
103
 
# File 'lib/chef/formatters/doc.rb', line 102

def ohai_completed(node)
end

#output_record(line) ⇒ Object 



295
296
 
# File 'lib/chef/formatters/doc.rb', line 295

def output_record(line)
end

#policyfile_loaded(policy) ⇒ Object 



130
131
132
 
# File 'lib/chef/formatters/doc.rb', line 130

def policyfile_loaded(policy)
  puts_line "Using policy '#{policy["name"]}' at revision '#{policy["revision_id"]}'"
end

#pretty_elapsed_time ⇒ Object 



32
33
34
35
36
37
38
39
40
41
42
 
# File 'lib/chef/formatters/doc.rb', line 32

def pretty_elapsed_time
  time = elapsed_time
  if time < 60 then
    message = Time.at(time).utc.strftime("%S seconds")
  elsif time < 3600 then
    message = Time.at(time).utc.strftime("%M minutes %S seconds")
  else
    message = Time.at(time).utc.strftime("%H hours %M minutes %S seconds")
  end
  message
end

#provider_requirement_failed(action, resource, exception, message) ⇒ Object

Called when an assertion declared by a provider fails



363
364
365
366
367
368
369
 
# File 'lib/chef/formatters/doc.rb', line 363

def provider_requirement_failed(action, resource, exception, message)
  return unless message
  color = Chef::Config[:why_run] ? :yellow : :red
  [ message ].flatten.each do |line|
    start_line("* #{line}", color)
  end
end

#recipe_load_complete ⇒ Object

Called when recipes have been loaded.



193
194
 
# File 'lib/chef/formatters/doc.rb', line 193

def recipe_load_complete
end

#registration_completed ⇒ Object 



114
115
 
# File 'lib/chef/formatters/doc.rb', line 114

def registration_completed
end

#registration_start(node_name, config) ⇒ Object

About to attempt to register as node_name



110
111
112
 
# File 'lib/chef/formatters/doc.rb', line 110

def registration_start(node_name, config)
  puts_line "Creating a new client identity for #{node_name} using the validator key."
end

#removed_cookbook_file(path) ⇒ Object

Called after the file at path is removed. It may be removed if the cookbook containing it was removed from the run list, or if the file was removed from the cookbook.



156
157
 
# File 'lib/chef/formatters/doc.rb', line 156

def removed_cookbook_file(path)
end

#resource_action_start(resource, action, notification_type = nil, notifier = nil) ⇒ Object

Called before action is executed on a resource.



243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
 
# File 'lib/chef/formatters/doc.rb', line 243

def resource_action_start(resource, action, notification_type = nil, notifier = nil)
  if resource.cookbook_name && resource.recipe_name
    resource_recipe = "#{resource.cookbook_name}::#{resource.recipe_name}"
  else
    resource_recipe = "<Dynamically Defined Resource>"
  end

  if resource_recipe != @current_recipe && !resource.enclosing_provider
    unindent if @current_recipe
    puts_line "Recipe: #{resource_recipe}"
    @current_recipe = resource_recipe
    indent
  end
  # TODO: info about notifies
  start_line "* #{resource} action #{action}", :stream => resource
  indent
end

#resource_bypassed(resource, action, provider) ⇒ Object 



290
291
292
293
 
# File 'lib/chef/formatters/doc.rb', line 290

def resource_bypassed(resource, action, provider)
  puts " (Skipped: whyrun not supported by provider #{provider.class.name})", :stream => resource
  unindent
end

#resource_current_state_load_bypassed(resource, action, current_resource) ⇒ Object

Called when resource current state load is skipped due to the provider not supporting whyrun mode.



327
328
329
 
# File 'lib/chef/formatters/doc.rb', line 327

def resource_current_state_load_bypassed(resource, action, current_resource)
  puts_line("* Whyrun not supported for #{resource}, bypassing load.", :yellow)
end

#resource_current_state_loaded(resource, action, current_resource) ⇒ Object

Called after #load_current_resource has run.



280
281
 
# File 'lib/chef/formatters/doc.rb', line 280

def resource_current_state_loaded(resource, action, current_resource)
end

#resource_failed(resource, action, exception) ⇒ Object

Called when a resource fails and will not be retried.



266
267
268
269
 
# File 'lib/chef/formatters/doc.rb', line 266

def resource_failed(resource, action, exception)
  super
  unindent
end

#resource_failed_retriable(resource, action, retry_count, exception) ⇒ Object

Called when a resource fails, but will retry.



262
263
 
# File 'lib/chef/formatters/doc.rb', line 262

def resource_failed_retriable(resource, action, retry_count, exception)
end

#resource_skipped(resource, action, conditional) ⇒ Object

Called when a resource action has been skipped b/c of a conditional



272
273
274
275
276
277
 
# File 'lib/chef/formatters/doc.rb', line 272

def resource_skipped(resource, action, conditional)
  @skipped_resources += 1
  # TODO: more info about conditional
  puts " (skipped due to #{conditional.short_description})", :stream => resource
  unindent
end

#resource_up_to_date(resource, action) ⇒ Object

Called when a resource has no converge actions, e.g., it was already correct.



284
285
286
287
288
 
# File 'lib/chef/formatters/doc.rb', line 284

def resource_up_to_date(resource, action)
  @up_to_date_resources += 1
  puts " (up to date)", :stream => resource
  unindent
end

#resource_update_applied(resource, action, update) ⇒ Object

Called when a change has been made to a resource. May be called multiple times per resource, e.g., a file may have its content updated, and then its permissions updated.



301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
 
# File 'lib/chef/formatters/doc.rb', line 301

def resource_update_applied(resource, action, update)
  prefix = Chef::Config[:why_run] ? "Would " : ""
  Array(update).each do |line|
    next if line.nil?
    output_record line
    if line.kind_of? String
      start_line "- #{prefix}#{line}", :green
    elsif line.kind_of? Array
      # Expanded output - delta
      # @todo should we have a resource_update_delta callback?
      line.each do |detail|
        start_line detail, :white
      end
    end
  end
end

#resource_updated(resource, action) ⇒ Object

Called after a resource has been completely converged.



319
320
321
322
323
 
# File 'lib/chef/formatters/doc.rb', line 319

def resource_updated(resource, action)
  @updated_resources += 1
  unindent
  puts "\n"
end

#run_completed(node) ⇒ Object 



57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
 
# File 'lib/chef/formatters/doc.rb', line 57

def run_completed(node)
  @end_time = Time.now
  # Print out deprecations.
  if !deprecations.empty?
    puts_line ""
    puts_line "Deprecated features used!"
    deprecations.each do |message, locations|
      if locations.size == 1
        puts_line "  #{message} at #{locations.size} location:"
      else
        puts_line "  #{message} at #{locations.size} locations:"
      end
      locations.each do |location|
        prefix = "    - "
        Array(location).each do |line|
          puts_line "#{prefix}#{line}"
          prefix = "      "
        end
      end
    end
    puts_line ""
  end
  if Chef::Config[:why_run]
    puts_line "Chef Client finished, #{@updated_resources}/#{total_resources} resources would have been updated"
  else
    puts_line "Chef Client finished, #{@updated_resources}/#{total_resources} resources updated in #{pretty_elapsed_time}"
    if total_audits > 0
      puts_line "  #{successful_audits}/#{total_audits} controls succeeded"
    end
  end
end

#run_failed(exception) ⇒ Object 



89
90
91
92
93
94
95
96
97
98
99
 
# File 'lib/chef/formatters/doc.rb', line 89

def run_failed(exception)
  @end_time = Time.now
  if Chef::Config[:why_run]
    puts_line "Chef Client failed. #{@updated_resources} resources would have been updated"
  else
    puts_line "Chef Client failed. #{@updated_resources} resources updated in #{pretty_elapsed_time}"
    if total_audits > 0
      puts_line "  #{successful_audits} controls succeeded"
    end
  end
end

#run_start(version) ⇒ Object 



44
45
46
47
 
# File 'lib/chef/formatters/doc.rb', line 44

def run_start(version)
  puts_line "Starting Chef Client, version #{version}"
  puts_line "OpenSSL FIPS 140 mode enabled" if Chef::Config[:fips]
end

#skipping_registration(node_name, config) ⇒ Object

Already have a client key, assuming this node has registered.



106
107
 
# File 'lib/chef/formatters/doc.rb', line 106

def skipping_registration(node_name, config)
end

#stream_output(stream, output, options = {}) ⇒ Object 



331
332
333
 
# File 'lib/chef/formatters/doc.rb', line 331

def stream_output(stream, output, options = {})
  print(output, { :stream => stream }.merge(options))
end

#synchronized_cookbook(cookbook_name, cookbook) ⇒ Object

Called when cookbook cookbook has been sync’d



170
171
172
 
# File 'lib/chef/formatters/doc.rb', line 170

def synchronized_cookbook(cookbook_name, cookbook)
  puts_line "- #{cookbook.name} (#{cookbook.version})"
end

#total_audits ⇒ Object 



53
54
55
 
# File 'lib/chef/formatters/doc.rb', line 53

def total_audits
  successful_audits + failed_audits
end

#total_resources ⇒ Object 



49
50
51
 
# File 'lib/chef/formatters/doc.rb', line 49

def total_resources
  @up_to_date_resources + @updated_resources + @skipped_resources
end

#unindent ⇒ Object 



385
386
387
 
# File 'lib/chef/formatters/doc.rb', line 385

def unindent
  indent_by(-2)
end

#updated_cookbook_file(cookbook_name, path) ⇒ Object

Called when an individual file in a cookbook has been updated



175
176
 
# File 'lib/chef/formatters/doc.rb', line 175

def updated_cookbook_file(cookbook_name, path)
end

#whyrun_assumption(action, resource, message) ⇒ Object

Called when a provider makes an assumption after a failed assertion in whyrun mode, in order to allow execution to continue



355
356
357
358
359
360
 
# File 'lib/chef/formatters/doc.rb', line 355

def whyrun_assumption(action, resource, message)
  return unless message
  [ message ].flatten.each do |line|
    start_line("* #{line}", :yellow)
  end
end