chef_sous_vide 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4dbf479c7c26026bf1c478fed4b9268743c018cc
-  data.tar.gz: f903092d21a62916b09d1b03c5b0a6e2e00be2c5
+  metadata.gz: b7625a1692ecb152693bc6dc151c671801001d59
+  data.tar.gz: 38a2599b444790b518ccec7c70d668b4bcc7b859
 SHA512:
-  metadata.gz: 6cf82abbceeb1d85371f5cda965cf3c27dbbd61bdc220253c9e5ded22149ce6ab6f658f2473cd2a15a050c127d9c525536ee13d5ba62cd7e496e488211a8b1ab
-  data.tar.gz: c80e255d8f134869e2e72448c2b30ebdec32044568271175138933129dd5ab643eaa370b5a5af5729f06b33019b208c9afc652bf16622eb1446408af5fb16960
+  metadata.gz: 4a4a9001104866457fb7591800de2707122db72db4e5fa1f13c4444c8c6a13c82665823125afe5719b2b8486869d17e8111baace07afb6ea21bd9e7d578ac413
+  data.tar.gz: 19f0b7ad71404d464a687d4cbfabfc58f047734675b6f03038c8497d10c03d77a249594ece19a8806bd4f9f4be12e3d59f56ad799bb359ea154fde63acea3ce8

data/.gitignore

@@ -12,3 +12,4 @@ vendor
 .rspec_status
 .kitchen/
 .kitchen.local.yml
+*.gem

data/Gemfile

@@ -1,3 +1,5 @@
 source "https://rubygems.org"
 
 gemspec
+
+gem "yard"

data/Gemfile.lock

@@ -1,8 +1,8 @@
 PATH
   remote: .
   specs:
-    sous_vide (0.1.0)
-      chef (~> 12.17.44)
+    chef_sous_vide (0.2.0)
+      chef
 
 GEM
   remote: https://rubygems.org/
@@ -278,6 +278,7 @@ GEM
       rubyzip (~> 1.1)
       winrm (~> 2.0)
     wmi-lite (1.0.2)
+    yard (0.9.19)
 
 PLATFORMS
   ruby
@@ -285,13 +286,14 @@ PLATFORMS
 DEPENDENCIES
   berkshelf
   bundler (~> 1.17)
+  chef_sous_vide!
   cucumber (~> 3.1.2)
   kitchen-docker
   kitchen-transport-rsync
   pry
   rake (~> 10.0)
-  sous_vide!
   test-kitchen
+  yard
 
 BUNDLED WITH
    1.17.1

data/README.md

@@ -2,6 +2,9 @@
 
 **=======> SousVide is not ready to use. <=======**
 
+
+![SousVide example dashboard](media/kibana-dashboard.png?raw=true)
+
 SousVide is a Chef Handler you can use to collect & visualize `chef-client` converge process. It receives event data from `chef-client` and keeps track of the converge process. It's essentially a stream parser hooked into `Chef::EventDispatch`.
 
 At the end you will have an extensive report about events occured during the run.
@@ -24,7 +27,7 @@ Here's what SousVide will tell you:
   - simple counters for each type
   - notification type & notifying resource when available
 
-All this and more will be available in a simple JSON friendly data structure ready to serve anywhere you like.
+All this and more will be available in a flat JSON data structure.
 
 Feed it to Kibana, save to file or print at the end of chef-client run. `SousVide` comes with common outputs (see `SousVide::Outputs`) but you can write your own or even pass it a Proc.
 
@@ -33,12 +36,17 @@ Feed it to Kibana, save to file or print at the end of chef-client run. `SousVid
 Add to your recipe:
 
 ```ruby
-chef_gem "sous_vide" do
+chef_gem "chef_sous_vide" do
   action :install
 end
 
-require "sous_vide"
-SousVide::Handler.register(node.run_context)
+ruby_block "register sous handler" do
+  block do
+    require "sous_vide"
+    SousVide.register(node.run_context)
+  end
+  action :nothing
+end.run_action(:run)
 ```
 
 You should add these lines as early as possible. SousVide will not detect compile-time executions before it's registration, but otherwise it will work just fine (or just as one would expect).
@@ -81,19 +89,26 @@ Once SousVide is registered, it's for the most part up to you to consume the out
     "chef_run_started_at": "2019-04-01 11:46:18",
     "chef_run_completed_at": "2019-04-01 11:46:24",
     "chef_run_success": true
-  },
-
-  #...
+  }
 ]
 ```
 
-You can configure SousVide in the recipe:
+Example configuration for JsonHTTP:
 
 ```ruby
-require "sous_vide"
-json_http = SousVide::Outputs::JsonHTTP.new(url: "http://elasticsearch:3000")
-SousVide::Handler.instance.sous_output = json_http
-SousVide::Handler.register(node.run_context)
+chef_gem "chef_sous_vide" do
+  action :install
+end
+
+ruby_block "register sous handler" do
+  block do
+    require "sous_vide"
+    json_http = SousVide::Outputs::JsonHTTP.new(url: "http://elasticsearch:3000")
+    SousVide.sous_output = json_http
+    SousVide.register(node.run_context)
+  end
+  action :nothing
+end.run_action(:run)
 ```
 
 Open `cookbooks/sous_vide/recipes/install.rb` to see how to configure other outputs or use more than one.
@@ -116,6 +131,8 @@ Once `chef-client` finishes converging you can access a Kibana dashboard and see
 
 There are more example kitchen configurations you can converge and see the runs in Kibana. You can change the default recipe, converge again and see it in Kibana.
 
+[![asciicast](https://asciinema.org/a/RerbmOQ5FzZisOM312zarxcYX.svg)](https://asciinema.org/a/RerbmOQ5FzZisOM312zarxcYX)
+
 ## Contributing
 
 Bug reports, suggestions and pull requests are welcome on GitHub.

data/kitchen.yml

@@ -41,6 +41,8 @@ suites:
       forward:
         - "5601:5601" # kibana
         - "9200:9200" # es
+      cap_add:
+        - IPC_LOCK
     run_list:
       - sous_vide::install
       - sous_vide::default
@@ -70,6 +72,9 @@ suites:
       java:
         jdk_version: 8
   - name: nginx
+    driver:
+      links:
+        - elasticsearch
     includes:
       - ubuntu-16.04
     run_list:

data/lib/sous_vide.rb

@@ -1,10 +1,45 @@
-require "chef/handler"
-require "chef/http"
 require "sous_vide/version"
-
-require "sous_vide/tracked_resource"
 require "sous_vide/handler"
+require "chef"
 
+# Interface to use SousVide in Chef.
+#
+# Provides a shortcut methods to configure and enable SousVide.
+#
+# @example Enable SousVide with JSON HTTP output and custom run name
+#
+#   ruby_block "enable SousVide" do
+#     block do
+#       json_http_output = SousVide::Outputs::JsonHTTP.new(url: "http://localhost:3000")
+#       SousVide.run_name = "custom run name"
+#       SousVide.sous_output = json_http_output
+#       SousVide.register(node.run_context)
+#     end
+#     action :nothing
+#   end.run_action(:run)
 module SousVide
-  class Error < StandardError; end
+  # (see SousVide::Handler.register)
+  def self.register(chef_run_context)
+    SousVide::Handler.register(chef_run_context)
+  end
+
+  # (see SousVide::Handler#sous_output)
+  def self.sous_output=(output)
+    SousVide::Handler.instance.sous_output = output
+  end
+
+  # (see SousVide::Handler#run_name)
+  def self.run_name=(text)
+    SousVide::Handler.instance.run_name = text
+  end
+
+  # (see SousVide::Handler#run_id)
+  def self.run_id=(text)
+    SousVide::Handler.instance.run_id = text
+  end
+
+  # (see SousVide::Handler#logger)
+  def self.logger=(logger)
+    SousVide::Handler.instance.logger = logger
+  end
 end

data/lib/sous_vide/event_methods.rb

@@ -7,13 +7,15 @@ module SousVide
   # 2. resource_* events (possibly multiple)
   # 3. resource_action_complete
   #
-  # The code is intentionally procedural and explicit. If :resource_action_start assigned
-  # @processing_now only then other events will work. :resource_action_completed unassigns
-  # @processing_now so all events will be ignored until :resource_action_start is called
-  # again.
+  # If :resource_action_start assigned @processing_now only then other methods will perform any
+  # processing.
+  #
+  # :resource_action_completed unassigns @processing_now so all events will be ignored until
+  # :resource_action_start is called again.
+  #
+  # @see https://www.rubydoc.info/gems/chef/Chef/EventDispatch/Base
   module EventMethods
-    # This hook will always fire whenever chef is about to converge a resource, including why_run
-    # mode, notifications or skipped resources.
+    # Called before action is executed on a resource.
     def resource_action_start(new_resource, action, notification_type, notifying_resource)
       if nested?(new_resource) # ignore nested resources
         new_r_name = "#{new_resource.resource_name}[#{new_resource.name}]##{action}"
@@ -53,6 +55,7 @@ module SousVide
       true
     end
 
+    # Called after a resource has been completely converged, but only if modifications were made.
     def resource_updated(new_resource, _action)
       return false if @processing_now.nil? || nested?(new_resource) # ignore nested resources
 
@@ -61,8 +64,7 @@ module SousVide
       true
     end
 
-    # Resource is skipped when a guard instruction stops the converge process or when
-    # `action :nothing` is used (it's a guard too).
+    # Called when a resource action has been skipped b/c of a conditional.
     def resource_skipped(new_resource, _action, conditional)
       return false if @processing_now.nil? || nested?(new_resource) # ignore nested resources
 
@@ -72,6 +74,7 @@ module SousVide
       true
     end
 
+    # Called when a resource has no converge actions, e.g., it was already correct.
     def resource_up_to_date(new_resource, _action)
       return false if @processing_now.nil? || nested?(new_resource) # ignore nested resources
 
@@ -80,6 +83,7 @@ module SousVide
       true
     end
 
+    # Called when a resource action has been completed.
     def resource_completed(new_resource)
       return false if @processing_now.nil? || nested?(new_resource) # ignore nested resources
 
@@ -110,7 +114,7 @@ module SousVide
       # why-run mode and notifications are not in natural order and must not move the cursor.
       #
       # Having it pointing ahead is relevant because current resource has just been converged
-      # (technically 'failed') and it is not 'unprocessed'.
+      # (maybe 'failed') and it is not 'unprocessed'.
       if !@processing_now.notifying_resource && # not notified
          !::Chef::Config[:why_run] &&           # not why-run
          @run_phase == "converge"               # only converge phase
@@ -124,6 +128,7 @@ module SousVide
       true
     end
 
+    # Called when a resource fails and will not be retried.
     def resource_failed(new_resource, _action, exception)
       return false if @processing_now.nil? || nested?(new_resource) # ignore nested resources
 
@@ -134,6 +139,8 @@ module SousVide
       true
     end
 
+    # Called when a resource fails, but will retry.
+    #
     # Resources with retries can succeed on subsequent attempts or ignore_failure option may be
     # set and it's the only place we can capture intermittent errors.
     #
@@ -148,6 +155,7 @@ module SousVide
       true
     end
 
+    # Called before convergence starts
     def converge_start
       debug("Received :converge_start")
       debug("Changed run phase to 'converge'.")
@@ -155,6 +163,7 @@ module SousVide
       @run_name ||= [@run_started_at, @chef_node_role, @chef_node_ipv4, @run_id].join(" ")
     end
 
+    # Called when the converge phase is finished (success)
     def converge_complete
       debug("Received :converge_completed")
       @run_success = true
@@ -162,6 +171,8 @@ module SousVide
       send_to_output!
     end
 
+
+    # Called if the converge phase fails
     def converge_failed(_exception)
       debug("Received :converge_failed")
       @run_success = false

data/lib/sous_vide/handler.rb

@@ -1,55 +1,152 @@
+require "sous_vide/tracked_resource"
 require "sous_vide/event_methods"
-require "sous_vide/outputs/json_file"
-require "sous_vide/outputs/json_http"
-require "sous_vide/outputs/logger"
-require "sous_vide/outputs/multi"
+require "sous_vide/outputs"
 
 require "securerandom"
 require "singleton"
 
 module SousVide
-  # == SousVide::Handler
+  # SousVide exposes minimal API as it's driven by events passed from chef-client.
   #
-  # The Handler receives event data from chef-client and keeps track of the converge process. It's
-  # essentially a stream parser hooked into Chef::EventDispatch.
+  # It's sufficient to enable it and with default configuration it will print summary to
+  # chef-client logs.
   #
-  # Event methods are all in SousVide::EventMethods module. This file contains logic that does not
-  # deal with events directly.
+  # Collected data can be sent to different outputs, ie. HTTP endpoint.
+  #
+  # :run_name and :run_id can be customized, it will be passed to the configured output along
+  # all data.
+  #
+  # @note You should interact with SousVide via top level methods, i.e. SousVide.run_id = '1123'.
+  #
+  # @example Enable SousVide with JSON HTTP output and custom run name
+  #
+  #   ruby_block "enable SousVide" do
+  #     block do
+  #       json_http_output = SousVide::Outputs::JsonHTTP.new(url: "http://localhost:3000")
+  #       SousVide::Handler.instance.run_name = "custom run name"
+  #       SousVide::Handler.instance.sous_output = json_http_output
+  #       SousVide::Handler.register(node.run_context)
+  #     end
+  #     action :nothing
+  #   end.run_action(:run)
+  #
+  # @see SousVide::Handler.register
+  # @see SousVide::Handler#sous_output
+  # @see https://www.rubydoc.info/gems/chef/Chef/EventDispatch/Base
   class Handler
     include Singleton
     include EventMethods
 
-    attr_accessor :chef_run_context,
-                  :logger,
-                  :sous_output,
-                  :processing_now,
-                  :processed,
-                  :run_phase,
-                  :run_id,
-                  :run_name
+    # Chef-client run phase. One of:
+    #
+    # * compile
+    # * converge
+    # * delayed
+    # * post-converge
+    #
+    # Compile & converge phases reflect standard Chef two-pass model. Delayed & post-converge
+    # are custom phases added by SousVide.
+    #
+    # SousVide enters delayed phase when chef-client begins processing delayed notifications, that
+    # is after all resources in the run list have bggen converged.
+    #
+    # Post-converge phase happens when chef-client run fails and aborts the converge process. It
+    # will include resources that should, but were not converged.
+    #
+    # @api private
+    #
+    # @return [String]
+    attr_reader :run_phase
 
-    # Enables the handler. Call it anywhere in the recipe, ideally as early as possible.
+    # Chef::RunContext object from chef-client.
+    # @see https://www.rubydoc.info/gems/chef/Chef/RunContext
+    # @api private
+    attr_writer :chef_run_context
+
+    # Logger object SousVide will use (default Chef::Log)
     #
-    #   SousVide::Handler.register(node.run_context)
+    # Event methods emit debug level messages and it can be helpful to configure a dedicated logger
+    # for SousVide to avoid excessive messages from chef-client.
+    #
+    # @example Configure custom debug logger
+    #
+    #   logger = Logger.new(STDOUT)
+    #   logger.level = Logger::DEBUG
+    #   @sous_vide.logger = logger
+    #
+    # @see https://www.rubydoc.info/gems/chef/Chef/Log
+    attr_accessor :logger
+
+    # An object SousVide will pass all collected data to at the end of the chef-client run.
+    #
+    # The output must respond to #call (like Proc).
+    #
+    # Defaults to SousVide::Outputs::Logger.
+    #
+    # @example Configure JsonHTTP output
+    #
+    #   json_http_output = SousVide::Outputs::JsonHTTP.new(url: "http://localhost:3000")
+    #   @sous_vide.sous_output = json_http_output
+    #
+    # @example Configure multiple outputs
+    #
+    #   json_file_output = SousVide::Outputs::JsonFile.new
+    #   logger_output = SousVide::Outputs::Logger.new
+    #   multi_output = SousVide::Outputs::Multi.new(json_file_output, logger_output)
+    #   @sous_vide.sous_output = multi_output
+    #
+    #
+    # @see SousVide::Outputs::JsonFile
+    # @see SousVide::Outputs::JsonHTTP
+    # @see SousVide::Outputs::Logger
+    # @see SousVide::Outputs::Multi
+    attr_accessor :sous_output
+
+
+    # @return [SousVide::TrackedResource] a resource SousVide is currently processing.
+    # @api private
+    attr_reader :processing_now
+
+    # @return [Array<SousVide::TrackedResource>] a list of processed resources.
+    # @api private
+    attr_reader :processed
+
+    # SousVide custom run name. It will be included in the output, not used otherwise.
+    #
+    # @return [String]
+    attr_accessor :run_name
+
+    # SousVide custom run ID. It will be included in the output, not used otherwise.
+    #
+    # It is not chef client run id.
+    #
+    # @return [String]
+    attr_accessor :run_id
+
+    # Enables SousVide. It can be called anywhere in the recipe, ideally as early as possible.
     #
     # All converge-time resources will be included in the report regardless at what point
     # registration happens.
     #
     # Compile-time resources defined before registration will not be included.
-    # TODO: see client.rb start_handlers as an option.
     #
-    # `chef_handler` resource does not support subscribing to :events so we have give up DSL and
-    # use Chef API.
+    # @note chef_handler resource does not support subscribing to :events. Chef.event_handler DSL
+    #  could be used but dealing with returns and exceptions in blocks is tricky. Using Chef API
+    #  and Ruby feels the most reliable.
     #
-    # The `Chef.event_handler` DSL could be used but dealing with returns and exceptions in procs
-    # is a pain.
-    def self.register(run_context)
+    # @todo see client.rb start_handlers as an option.
+    #
+    # @example
+    #   SousVide::Handler.register(node.run_context)
+    #
+    # @return (void)
+    def self.register(chef_run_context)
       ::Chef::Log.info "Registering SousVide"
 
-      instance.chef_run_context = run_context
-      instance.post_initialize
+      instance.chef_run_context = chef_run_context
+      instance.populate_node_data
 
-      run_context.events.register(instance)
+      chef_run_context.events.register(instance)
     end
 
     def initialize
@@ -61,23 +158,17 @@ module SousVide
 
       @run_started_at = Time.now.strftime("%F %T")
 
-      # Not related to RunStatus#run_id, it's our internal run id.
+      # Not related to RunStatus#run_id, it's SousVide internal run ID.
       @run_id = SecureRandom.uuid.split("-").first # => 596e9d00
       @run_phase = "compile"
 
-      # Default to Chef logger, but can be changed to anything that responds to #call
       @logger = ::Chef::Log
       @sous_output = Outputs::Logger.new(logger: @logger)
     end
 
-    # This is called in #register, as soon as @chef_run_context is available.
-    def post_initialize
-      @chef_node_ipv4 = @chef_run_context.node["ipaddress"] || "<no ip>"
-      @chef_node_role = @chef_run_context.node["roles"].first || "<no role>"
-      @chef_node_instance_id = @chef_run_context.node.name
-    end
-
-
+    # Chef-client run related attributes.
+    #
+    # @return (Hash)
     def run_data
       {
         chef_run_id: @run_id,
@@ -88,6 +179,9 @@ module SousVide
       }
     end
 
+    # Node related attributes
+    #
+    # @return (Hash)
     def node_data
       {
         chef_node_ipv4: @chef_node_ipv4,
@@ -96,6 +190,31 @@ module SousVide
       }
     end
 
+    # Populates node attributes from Chef run context. These attributes will be passed to the
+    # configured output as :node_data.
+    #
+    # @api private
+    def populate_node_data
+      @chef_node_ipv4 = @chef_run_context.node["ipaddress"] || "<no ip>"
+      @chef_node_role = @chef_run_context.node["roles"].first || "<no role>"
+      @chef_node_instance_id = @chef_run_context.node.name
+    end
+
+    private
+
+    # Sends all collected data to configured output.
+    #
+    # It is called at the end of the converge process, both failure and success.
+    def send_to_output!
+      @sous_output.call(run_data: run_data, node_data: node_data, resources_data: @processed)
+    end
+
+    # Creates SousVide::TrackedResource from Chef resource and action.
+    #
+    # @param chef_resource [Chef::Resource]
+    # @param action [Symbol] an action chef-client executes on the resource
+    #
+    # @return (SousVide::TrackedResource)
     def create(chef_resource:, action:)
       tracked = TrackedResource.new(action: action,
                                     name: chef_resource.name,
@@ -108,30 +227,35 @@ module SousVide
       tracked
     end
 
-    # We will ignore nested resources. Once a top level resource triggered :resource_action
-    # started any events not related to it will be ignored.
+
+    # Tells if an event is related to the current SousVide resource. If not it's nested.
+    #
+    # Once a top level resource triggered :resource_action_start any events not related to it will
+    # be ignored by SousVide.
+    #
+    # @return (Boolean)
     def nested?(chef_resource)
       @processing_now &&
         @processing_now.chef_resource_handle != chef_resource
     end
 
-    # When chef-client fails we haven't seen all resources and need to backfill the handler.
+    # Backfills unprocessed resources. This is called only if chef-client failed (:converge_failed
+    # event). SousVide is now in "post-converge" run phase.
+    #
+    # Unprocessed resources as a result of notifications are not included.
     def consume_unprocessed_resources!
       all_known_resources = expand_chef_resources!
 
       # No unprocessed resources left. Failure likely occured on last resource or in a delayed
       # notification.
-      # TODO: check delayed notification failure
+      # TODO: check delayed notification failure. We may also want to backfeed unprocessed delayed
+      # notifications too? Maybe.
       return if @resource_collection_cursor >= all_known_resources.size
 
       unprocessed = all_known_resources[@resource_collection_cursor..-1]
 
-      # We will pass unprocessed resources via  :resource_action_start and :resource_completed so
-      # they will end up in @processed array, but with status set to 'unprocessed' and execution
-      # phase 'post-converge'.
-      #
-      # TODO: consider placing these resources before delayed notification, currently they are
-      # always at the very end. It _maybe_ makes sense.
+      # Pass unprocessed resources via  :resource_action_start and :resource_completed so
+      # they will end up in @processed collection, but with status set to "unprocessed".
       unprocessed.each do |tracked|
         resource_action_start(
           tracked.chef_resource_handle, # new_resource
@@ -146,34 +270,30 @@ module SousVide
       end
     end
 
-    # Resources with multiple actions must be expanded, ie. given resource:
+    # Expands chef-client run list. Resources with multiple actions must be expanded,
+    # ie. given resource:
     #
-    #   service 'nginx' do
+    #   service "nginx" do
     #     action [:enable, :start]
     #   end
     #
-    # After expansion we should have 2 resources:
+    # After expansion we will have 2 resources:
     #
     #   * service[nginx] with action :enable
     #   * service[nginx] with action :start
     #
-    # We keep track of the progress and on failure we will pick up unprocessed resources from here
-    # to feed the handler in post-converge stage.
+    # On failure SousVide will pick up unprocessed resources from here to feed the handler in
+    # post-converge stage.
     #
-    # On a successful chef-client run @processed will contain all resources and this method won't
-    # be called.
+    # On a successful chef-client run this method won't be called.
     def expand_chef_resources!
-      chef_run_context.resource_collection.flat_map do |chef_resource|
+      @chef_run_context.resource_collection.flat_map do |chef_resource|
         Array(chef_resource.action).map do |action|
           create(chef_resource: chef_resource, action: action)
         end
       end
     end
 
-    def send_to_output!
-      @sous_output.call(run_data: run_data, node_data: node_data, resources_data: @processed)
-    end
-
     def debug(*args)
       message = args.compact.join(" ")
       logger.debug(message)

data/lib/sous_vide/outputs.rb

@@ -0,0 +1,13 @@
+require "sous_vide/outputs/json_file"
+require "sous_vide/outputs/json_http"
+require "sous_vide/outputs/logger"
+require "sous_vide/outputs/multi"
+
+module SousVide
+  # @see SousVide::Outputs::JsonFile
+  # @see SousVide::Outputs::JsonHTTP
+  # @see SousVide::Outputs::Logger
+  # @see SousVide::Outputs::Multi
+  module Outputs
+  end
+end

data/lib/sous_vide/outputs/json_file.rb

@@ -1,19 +1,19 @@
-require "chef/config"
-require "chef/json_compat"
-require "chef/log"
-
 module SousVide
   module Outputs
-    # Saves the report to a JSON file on a node.  The file will be saved to chef cache directory.
+    # Saves the report to a JSON file.  The file will be saved to chef cache directory.
+    #
+    # Default file name is "sous-vide-report.json".
     #
-    #   Outputs::JsonFile.new
+    # @example
     #
-    # By the report will be saved to "<chef-cache-path>/sous-vide-report.json".
+    #   SousVide::Outputs::JsonFile.new
     class JsonFile
-      def initialize(logger: logger)
+      def initialize(logger: nil, file_name: "sous-vide-report.json")
         @logger = logger
+        @file_name = file_name
       end
 
+      # Saves report to file.
       def call(run_data:, node_data:, resources_data:)
         log "=============== #{self.class.name} ==============="
         log ""
@@ -23,13 +23,14 @@ module SousVide
           tracked.to_h.merge(node_data).merge(run_data)
         end
 
-        ::Chef::FileCache.store("sous-vide-report.json",
-                                ::Chef::JSONCompat.to_json_pretty(json_data))
+        ::Chef::FileCache.store(@file_name, ::Chef::JSONCompat.to_json_pretty(json_data))
 
-        log "The report is in #{Chef::Config[:file_cache_path]}/sous-vide-report.json file."
+        log "The report is in #{Chef::Config[:file_cache_path]}/#{@file_name} file."
         log ""
       end
 
+      private
+
       def log(*args)
         message = args.compact.join(" ")
         logger.info(message)

data/lib/sous_vide/outputs/json_http.rb

@@ -6,16 +6,27 @@ module SousVide
   module Outputs
     # Makes a POST request to a configured endpoint. Logstash & Elasticsearch friendly format.
     #
+    # It uses Net::HTTP to perform requests, it can be customized via :http_client accessor.
+    #
+    # @example
+    #
     #   JsonHTTP.new(url: "http://localhost:9200/endpoint", max_retries: 10)
     class JsonHTTP
-      def initialize(url:, max_retries: 0, logger: nil)
+      # Provides access to Net::HTTP client object. Use it to enable SSL or pass your own client.
+      # @return [Net::HTTP]
+      attr_accessor :http_client
+
+      # @param max_retries [Fixnum] number retries across all requests made.
+      def initialize(url:, max_retries: 2, logger: nil)
         @endpoint = URI(url)
         @logger = logger
-
-        @max_retries = max_retries || 2
+        @retry = 0
+        @max_retries = max_retries
         @http_client = Net::HTTP.new(@endpoint.host, @endpoint.port)
       end
 
+      # Sends a POST request with a JSON payload using @http_client object per resource.
+      # @return (void)
       def call(run_data:, node_data:, resources_data:)
         log "=============== #{self.class.name} ==============="
         log ""
@@ -38,24 +49,26 @@ module SousVide
         log ""
       end
 
+      private
+
       def call_with_retries(nethttp_request)
-        _retry = 0
         begin
           @http_client.request(nethttp_request)
         rescue
-          if _retry < @max_retries
-            _retry += 1
+          if @retry < @max_retries
+            logger.warn("Request failed, retry #{@retry} of #{@max_retries}.")
+            @retry += 1
             sleep 2
             retry
           else
+            logger.error("Request failed, retry #{@retry} of #{@max_retries}. Abort.")
             raise
           end
         end
       end
 
       def log(*args)
-        message = args.compact.join(" ")
-        logger.info(message)
+        logger.info(args.compact.join(" "))
       end
 
       def logger

data/lib/sous_vide/outputs/logger.rb

@@ -1,13 +1,15 @@
 module SousVide
   module Outputs
-    # Prints the report to the logger (usually Chef logger).
+    # Prints the report to logger.
     #
-    #   Outputs::Logger.new
+    # @example
+    #   SousVide::Outputs::Logger.new
     class Logger
       def initialize(logger: nil)
         @logger = logger
       end
 
+      # Prints the report to logger.
       def call(run_data:, node_data:, resources_data:)
         log "=============== #{self.class.name} ==============="
         log ""
@@ -35,6 +37,8 @@ module SousVide
         log ""
       end
 
+      private
+
       def log(*args)
         message = args.compact.join(' ')
         logger.info(message)

data/lib/sous_vide/outputs/multi.rb

@@ -2,14 +2,18 @@ module SousVide
   module Outputs
     # Combines multiple outputs
     #
-    #   es = Outputs::ES.new ...
-    #   log = Outputs::Logger.new ...
-    #   multi = Outputs::Multi.new(es, log)
+    # @example
+    #   http = JsonHTTP.new(url: "http://localhost:9200/endpoint")
+    #   logger = SousVide::Outputs::Logger.new
+    #   file = SousVide::Outputs::JsonFile.new
+    #
+    #   SousVide::Outputs::Multi.new(logger, file, http)
     class Multi
       def initialize(*outputs)
         @outputs = outputs
       end
 
+      # Calls all configured outputs in order.
       def call(run_data:, node_data:, resources_data:)
         @outputs.each do |output|
           output.call(run_data: run_data, node_data: node_data,

data/lib/sous_vide/tracked_resource.rb

@@ -1,31 +1,67 @@
 module SousVide
-  # == SousVide::TrackedResource
+  # It is a very simple data structure SousVide uses to capture information about resource
+  # execution.
   #
-  # This is a very simple data structure SousVide uses to capture interesting
-  # information.
+  # @see https://www.rubydoc.info/gems/chef/Chef/Resource
   class TrackedResource
-    attr_accessor :type,
-                  :name,
-                  :action,
-                  :status,
-                  :duration_ms,
-                  :guard_description,
-                  :execution_phase,
-                  :execution_order,
-                  :notifying_resource,
-                  :notification_type,
-                  :before_notifications,
-                  :immediate_notifications,
-                  :delayed_notifications,
-                  :retries,
-                  :error_output,
-                  :error_source,
-                  :cookbook_name,
-                  :cookbook_recipe,
-                  :source_line,
-                  :started_at,
-                  :completed_at
 
+    attr_accessor :type
+
+    attr_accessor :name
+
+    # Action executed on this resource.
+    attr_accessor :action
+
+    # Result of the action, ie. "updated", "skipped", ...
+    attr_accessor :status
+
+    attr_accessor :duration_ms
+
+    attr_accessor :guard_description
+
+    # SousVide run-phase when this resource was executed.
+    attr_accessor :execution_phase
+
+    # Resource execution order. Takes into account notifications and does not reflect resource.
+    # order on the run list.
+    attr_accessor :execution_order
+
+    # Resource that triggered this execution. Delayed notifications do not have this.
+    attr_accessor :notifying_resource
+
+    attr_accessor :notification_type
+
+    # Number of before notifications attached to this resource.
+    attr_accessor :before_notifications
+
+    # Number of immediate notifications attached to this resource.
+    attr_accessor :immediate_notifications
+
+    # Number of delayed notifications attached to this resource.
+    attr_accessor :delayed_notifications
+
+    # Number of retries.
+    attr_accessor :retries
+
+    # Last error output if available. This can be populated when resource failed and when resource
+    # succeed after a retry.
+    attr_accessor :error_output
+
+    # Resource definition that triggered the error.
+    attr_accessor :error_source
+
+    attr_accessor :cookbook_name
+
+    attr_accessor :cookbook_recipe
+
+    attr_accessor :source_line
+
+    attr_accessor :started_at
+
+    attr_accessor :completed_at
+
+    # Chef API resource. It is used for comparsion only.
+    # @api private
     attr_accessor :chef_resource_handle
 
     def initialize(name:, action:, type:)
@@ -42,10 +78,14 @@ module SousVide
       @error_source = nil
     end
 
+    # String and human friendly represtnation of the resource
+    # @return [String]
     def to_s
       "#{@type}[#{@name}]##{@action}"
     end
 
+    # Serializes the resource to hash
+    # @return [Hash]
     def to_h
       {
         chef_resource: "#{@type}[#{@name}]##{@action}",

data/lib/sous_vide/version.rb

@@ -1,3 +1,3 @@
 module SousVide
-  VERSION = "0.1.0".freeze
+  VERSION = "0.2.0".freeze
 end

data/sous_vide.gemspec

@@ -15,14 +15,14 @@ Gem::Specification.new do |spec|
 
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
   spec.files = Dir.chdir(File.expand_path(__dir__)) do
-    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(cookbooks|kitchen|features)/}) }
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(cookbooks|kitchen|features|media)/}) }
   end
 
   spec.bindir = "exe"
   spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_dependency "chef", "~> 12.17.44"
+  spec.add_dependency "chef"
 
   spec.add_development_dependency "bundler", "~> 1.17"
   spec.add_development_dependency "rake", "~> 10.0"

metadata

@@ -1,29 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: chef_sous_vide
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - robuye
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-04-01 00:00:00.000000000 Z
+date: 2019-04-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: chef
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 12.17.44
+        version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 12.17.44
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -159,6 +159,7 @@ files:
 - lib/sous_vide.rb
 - lib/sous_vide/event_methods.rb
 - lib/sous_vide/handler.rb
+- lib/sous_vide/outputs.rb
 - lib/sous_vide/outputs/json_file.rb
 - lib/sous_vide/outputs/json_http.rb
 - lib/sous_vide/outputs/logger.rb