# class Chef::Handler

## Chef::Handler¶ ↑

The base class for an Exception or Notification Handler. Create your own handler by subclassing Chef::Handler. When a Chef run fails with an uncaught Exception, Chef will set the `run_status` on your handler and call `report`

### Example:¶ ↑

    require 'net/smtp'

    module MyOrg
      class OhNoes < Chef::Handler

        def report
          # Create the email message
          message  = "From: Your Name <your@mail.address>\n"
          message << "To: Destination Address <someone@example.com>\n"
          message << "Subject: Chef Run Failure\n"
          message << "Date: #{Time.now.rfc2822}\n\n"

          # The Node is available as +node+
          message << "Chef run failed on #{node.name}\n"
          # +run_status+ is a value object with all of the run status data
          message << "#{run_status.formatted_exception}\n"
          # Join the backtrace lines. Coerce to an array just in case.
          message << Array(backtrace).join("\n")

          # Send the email
          Net::SMTP.start('your.smtp.server', 25) do |smtp|
            smtp.send_message message, 'from@address', 'to@address'
          end
        end

      end
    end

### Attributes

run_status[R]

The Chef::RunStatus object containing data about the Chef run.

### Public Class Methods

exception_handlers() click to toggle source

The list of currently configured exception handlers

    # File lib/chef/handler.rb, line 107
    def self.exception_handlers
      Array(Chef::Config[:exception_handlers])
    end

report_handlers() click to toggle source

The list of currently configured report handlers

    # File lib/chef/handler.rb, line 82
    def self.report_handlers
      Array(Chef::Config[:report_handlers])
    end

run_exception_handlers(run_status) click to toggle source

Run the exception handlers. Usually will be called by a notification from Chef::Client when the run fails.

    # File lib/chef/handler.rb, line 113
    def self.run_exception_handlers(run_status)
      events = run_status.events
      events.handlers_start(exception_handlers.size)
      Chef::Log.error("Running exception handlers")
      exception_handlers.each do |handler|
        handler.run_report_safely(run_status)
        events.handler_executed(handler)
      end
      events.handlers_completed
      Chef::Log.error("Exception handlers complete")
    end

run_report_handlers(run_status) click to toggle source

Run the report handlers. This will usually be called by a notification from Chef::Client

    # File lib/chef/handler.rb, line 88
    def self.run_report_handlers(run_status)
      events = run_status.events
      events.handlers_start(report_handlers.size)
      Chef::Log.info("Running report handlers")
      report_handlers.each do |handler|
        handler.run_report_safely(run_status)
        events.handler_executed(handler)
      end
      events.handlers_completed
      Chef::Log.info("Report handlers complete")
    end

run_start_handlers(run_status) click to toggle source

Run the start handlers. This will usually be called by a notification from Chef::Client

    # File lib/chef/handler.rb, line 67
    def self.run_start_handlers(run_status)
      Chef::Log.info("Running start handlers")
      start_handlers.each do |handler|
        handler.run_report_safely(run_status)
      end
      Chef::Log.info("Start handlers complete.")
    end

start_handlers() click to toggle source

The list of currently configured start handlers

    # File lib/chef/handler.rb, line 61
    def self.start_handlers
      Array(Chef::Config[:start_handlers])
    end

### Public Instance Methods

all_resources() click to toggle source

An Array containing all resources in the chef run’s resource_collection

    # File lib/chef/handler.rb, line 183
    def_delegator :@run_status, :all_resources

backtrace() click to toggle source

The backtrace captured by the uncaught exception that terminated the chef run, or nil if the run completed successfully

    # File lib/chef/handler.rb, line 171
    def_delegator :@run_status, :backtrace

data() click to toggle source

Return the Hash representation of the #run_status

    # File lib/chef/handler.rb, line 230
    def data
      @run_status.to_hash
    end

elapsed_time() click to toggle source

The time elapsed between the start and finish of the chef run

    # File lib/chef/handler.rb, line 151
    def_delegator :@run_status, :elapsed_time

end_time() click to toggle source

The time the chef run ended

    # File lib/chef/handler.rb, line 145
    def_delegator :@run_status, :end_time

exception() click to toggle source

The uncaught Exception that terminated the chef run, or nil if the run completed successfully

    # File lib/chef/handler.rb, line 164
    def_delegator :@run_status, :exception

failed?() click to toggle source

Did the chef run fail? True if the chef run raised an uncaught exception

    # File lib/chef/handler.rb, line 202
    def_delegator :@run_status, :failed?

node() click to toggle source

The Chef::Node for this client run

    # File lib/chef/handler.rb, line 177
    def_delegator :@run_status, :node

report() click to toggle source

The main entry point for report handling. Subclasses should override this method with their own report handling logic.

    # File lib/chef/handler.rb, line 206
    def report
    end

run_context() click to toggle source

The Chef::RunContext object used by the chef run

    # File lib/chef/handler.rb, line 157
    def_delegator :@run_status, :run_context

run_report_safely(run_status) click to toggle source

Runs the report handler, rescuing and logging any errors it may cause. This ensures that all handlers get a chance to run even if one fails. This method should not be overridden by subclasses unless you know what you’re doing.

    # File lib/chef/handler.rb, line 213
    def run_report_safely(run_status)
      run_report_unsafe(run_status)
    rescue Exception => e
      Chef::Log.error("Report handler #{self.class.name} raised #{e.inspect}")
      Array(e.backtrace).each { |line| Chef::Log.error(line) }
    ensure
      @run_status = nil
    end

run_report_unsafe(run_status) click to toggle source

Runs the report handler without any error handling. This method should not be used directly except in testing.

    # File lib/chef/handler.rb, line 224
    def run_report_unsafe(run_status)
      @run_status = run_status
      report
    end

start_time() click to toggle source

The time the chef run started

    # File lib/chef/handler.rb, line 139
    def_delegator :@run_status, :start_time

success?() click to toggle source

Was the chef run successful? True if the chef run did not raise an uncaught exception

    # File lib/chef/handler.rb, line 196
    def_delegator :@run_status, :success?

updated_resources() click to toggle source

An Array containing all resources that were updated during the chef run

    # File lib/chef/handler.rb, line 189
    def_delegator :@run_status, :updated_resources