exception_notification-rake 0.0.1 → 0.0.2

data/README.md

@@ -1,4 +1,120 @@
-exception_notification-rake
-===========================
+exception_notification-rake - ExceptionNotifier for Rake tasks
+==============================================================
 
-An extension of the exception_notification gem to support sending mail upon failures in Rake tasks. Currently in development.
+This Ruby gem is an extension of the [exception_notification gem](http://rubygems.org/gems/exception_notification) to support sending mail upon failures in Rake tasks. This is useful if you run Rake tasks as batch jobs on a schedule, particularly if you're using the [Heroku Scheduler add-on](http://addons.heroku.com/scheduler).
+
+
+## Usage
+
+### Basic Configuration
+
+Exception notification must be set up in your Rails config files. In general, you'll want to do this in environment-specific config files, such as `config/environments/production.rb`. Minimal configuration:
+
+    # config/environments/production.rb
+    require 'exception_notifier/rake'
+
+    YourApp::Application.configure do
+      # Other configuration here, including ActionMailer config ...
+
+      config.middleware.use ExceptionNotifier,
+        :sender_address       => %{"notifier" <sender.address@example.com>},
+        :exception_recipients => %w{your.email@example.com},
+        :ignore_if            => lambda { true }
+
+      ExceptionNotifier::Rake.configure
+    end
+
+**Note:** This uses `:ignore_if` to suppress all exception notifications triggered by the Rails server itself (as opposed to Rake). If you want those notifications as well, omit the `:ignore_if` option.
+
+If you are already using `ExceptionNotifier` anyway, you don't need to configure it again and all you need is:
+
+	# config/environments/production.rb
+	require 'exception_notifier/rake'
+
+	YourApp::Application.configure do
+	  # Other configuration here, including ExceptionNotifer and ActionMailer config ...
+
+	  ExceptionNotifier::Rake.configure
+	end
+
+**Note:** As a prerequisite for sending mail your Rails Action Mailer needs to be configured in the environment where you're using exception notification. See the [Rails guide on Action Mailer](http://guides.rubyonrails.org/action_mailer_basics.html#action-mailer-configuration).
+
+
+### Notification Example
+
+Email sent upon a failure will include the Rake tasks executed and a stacktrace. This is the result from calling an undefined method `khaaaaan!` in a task called `failing_task`:
+
+	Subject: [Rake Failure] (NoMethodError) "undefined method `khaaaaan!' for main:Object"
+	From: "notifier" <sender.address@example.com>
+	To: <your.email@example.com>
+
+	A NoMethodError occurred in background at 2013-02-07 18:31:57 UTC :
+
+	  undefined method `khaaaaan!&#x27; for main:Object
+	  lib/tasks/scheduler.rake:33:in `block in &lt;top (required)&gt;&#x27;
+
+	  -------------------------------
+	Rake:
+	-------------------------------
+
+	  rake failing_task
+
+	-------------------------------
+	Backtrace:
+	-------------------------------
+
+	  lib/tasks/scheduler.rake:33:in `block in <top (required)>'
+	  .rvm/gems/ruby-1.9.3-p327/gems/rake-10.0.3/lib/rake/task.rb:228:in `call'
+	  .rvm/gems/ruby-1.9.3-p327/gems/rake-10.0.3/lib/rake/task.rb:228:in `block in execute'
+	  .rvm/gems/ruby-1.9.3-p327/gems/rake-10.0.3/lib/rake/task.rb:223:in `each'
+	  .rvm/gems/ruby-1.9.3-p327/gems/rake-10.0.3/lib/rake/task.rb:223:in `execute'
+	  .rvm/gems/ruby-1.9.3-p327/gems/rake-10.0.3/lib/rake/task.rb:166:in `block in invoke_with_call_chain'
+	  .rvm/rubies/ruby-1.9.3-p327/lib/ruby/1.9.1/monitor.rb:211:in `mon_synchronize'
+	  .rvm/gems/ruby-1.9.3-p327/gems/rake-10.0.3/lib/rake/task.rb:159:in `invoke_with_call_chain'
+	  .rvm/gems/ruby-1.9.3-p327/gems/rake-10.0.3/lib/rake/task.rb:152:in `invoke'
+	  .rvm/gems/ruby-1.9.3-p327/gems/rake-10.0.3/lib/rake/application.rb:143:in `invoke_task'
+	  .rvm/gems/ruby-1.9.3-p327/gems/rake-10.0.3/lib/rake/application.rb:101:in `block (2 levels) in top_level'
+	  .rvm/gems/ruby-1.9.3-p327/gems/rake-10.0.3/lib/rake/application.rb:101:in `each'
+	  .rvm/gems/ruby-1.9.3-p327/gems/rake-10.0.3/lib/rake/application.rb:101:in `block in top_level'
+	  .rvm/gems/ruby-1.9.3-p327/gems/rake-10.0.3/lib/rake/application.rb:110:in `run_with_threads'
+	  .rvm/gems/ruby-1.9.3-p327/gems/rake-10.0.3/lib/rake/application.rb:95:in `top_level'
+	  .rvm/gems/ruby-1.9.3-p327/gems/rake-10.0.3/lib/rake/application.rb:73:in `block in run'
+	  .rvm/gems/ruby-1.9.3-p327/gems/rake-10.0.3/lib/rake/application.rb:160:in `standard_exception_handling'
+	  .rvm/gems/ruby-1.9.3-p327/gems/rake-10.0.3/lib/rake/application.rb:70:in `run'
+	  .rvm/gems/ruby-1.9.3-p327/gems/rake-10.0.3/bin/rake:33:in `<top (required)>'
+	  .rvm/gems/ruby-1.9.3-p327/bin/rake:23:in `load'
+	  .rvm/gems/ruby-1.9.3-p327/bin/rake:23:in `<main>'
+
+(If you're spotting encoding issues here, those appear to be a problem upstream in the exception_notification gem.)
+
+
+### Usage with Heroku Scheduler
+
+If you're using Heroku, the [Scheduler add-on](http://addons.heroku.com/scheduler) is a very convenient and cheap (i.e., free) way to run scheduled batch jobs. In a Rails environment it's easiest to define batch jobs as Rake tasks. However, the only way to find out whether a task run by the scheduler succeeded or failed is generally reading the logs.
+
+This gem fixes this issue. If you configure exception notification as described above it should work out of the box with the Heroku Scheduler. (Provided you have email delivery set up in your Heroku app - you could try the [SendGrid add-on](https://addons.heroku.com/sendgrid) which comes in a free version that should be good enough for notifications.)
+
+
+### Customization
+
+You can pass configuration options to `ExceptionNotifier::Rake.configure`. It accepts all the same options as standard `ExceptionNotifier` (see [its documentation](https://github.com/smartinez87/exception_notification)). These options will be applied only to notifications sent as a result of Rake failures.
+
+The most likely options you'll want to use are `:email_prefix` and `:exception_recpients`. Example:
+
+    ExceptionNotifier::Rake.configure(
+	  :email_prefix => "[Cron Failure] ",
+	  :exception_recipients => %w{user1@example.com user2@example.com})
+
+This will prefix the email subjects of Rake failure notifications with `[Cron Failure]` and will send them to the two given email addresses. Note that if you set the same options when you configure `ExceptionNotifier` itself, they will be overridden but for Rake failures only.
+
+If you want to configure sections, which is unlikely, note that by default the sections `['rake', 'backtrace']` are used (where `rake` is a custom section introduced by this gem).
+
+
+## Installation
+
+    gem install exception_notification-rake
+
+
+## License
+
+Distributed under an [MIT license](https://github.com/nikhaldi/exception_notification-rake/blob/master/LICENSE.md).

data/lib/exception_notifier/rake/rake.rb

@@ -9,10 +9,15 @@ class ExceptionNotifier
 
     @notifier_options = {}
 
+    # Whether Rake exception notifications have been configured.
     def self.configured?
       !@notifier_options.empty?
     end
 
+    # Configure Rake exception notifications. Should be called in a config file,
+    # usually in config/environments/production.rb for production use.
+    # An optional hash of options can be given, which will be passed through
+    # unchanged to the underlying ExceptionNotifier.
     def self.configure(options = {})
       @notifier_options.merge!(default_notifier_options)
       @notifier_options.merge!(options)
@@ -29,7 +34,13 @@ class ExceptionNotifier
       @notifier_options
     end
 
+    # Deliver a notification about the given exception by email, in case
+    # notifications have been configured. The additional data hash will
+    # be passed through to ExceptionNotifier's data hash and will be availble
+    # in templates.
     def self.maybe_deliver_notification(exception, data={})
+      # TODO must check whether config has fully loaded yet, to avoid masking
+      # configuration issues.
       if configured?
         options = notifier_options
         if !data.empty?

data/lib/exception_notifier/rake/version.rb

@@ -1,5 +1,5 @@
 class ExceptionNotifier
   class Rake
-    VERSION = '0.0.1'
+    VERSION = '0.0.2'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: exception_notification-rake
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-02-07 00:00:00.000000000 Z
+date: 2013-02-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: exception_notification
@@ -74,13 +74,11 @@ files:
 - Rakefile
 - exception_notification-rake.gemspec
 - lib/exception_notifier/rake.rb
-- lib/exception_notifier/rake/multi_delegator.rb
 - lib/exception_notifier/rake/rake.rb
 - lib/exception_notifier/rake/rake_patch.rb
 - lib/exception_notifier/rake/version.rb
 - lib/exception_notifier/rake/views/exception_notifier/_rake.html.erb
 - lib/exception_notifier/rake/views/exception_notifier/_rake.text.erb
-- test/multi_delegator_test.rb
 - test/rake_test.rb
 homepage: https://github.com/nikhaldi/exception_notification-rake
 licenses: []
@@ -107,6 +105,5 @@ signing_key:
 specification_version: 3
 summary: Sending exception notifications upon Rake task failures
 test_files:
-- test/multi_delegator_test.rb
 - test/rake_test.rb
 has_rdoc: 

data/lib/exception_notifier/rake/multi_delegator.rb

@@ -1,21 +0,0 @@
-require 'delegate'
-
-class ExceptionNotifier
-  class Rake
-    class MultiDelegator
-
-      def initialize(delegates)
-        @delegates = delegates.map do |del|
-          SimpleDelegator.new(del)
-        end
-      end
-
-      def method_missing(m, *args, &block)
-        return_values = @delegates.map do |del|
-          del.method_missing(m, *args, &block)
-        end
-        return_values.first
-      end
-    end
-  end
-end

data/test/multi_delegator_test.rb

@@ -1,34 +0,0 @@
-require 'test/unit'
-
-require 'exception_notifier/rake/multi_delegator'
-
-class MultiDelegatorTest < Test::Unit::TestCase
-
-  def setup
-    @delegate1 = []
-    @delegate2 = [42]
-  end
-
-  def test_one_delegate
-    delegator = ExceptionNotifier::Rake::MultiDelegator.new([@delegate1])
-    result = delegator.push(42)
-    assert_equal [42], @delegate1
-    assert_equal [42], result
-  end
-
-  def test_multiple_delegates
-    delegator = ExceptionNotifier::Rake::MultiDelegator.new([@delegate1, @delegate2])
-    result = delegator.push(43)
-    assert_equal [43], result
-    assert_equal [43], @delegate1
-    assert_equal [42, 43], @delegate2
-  end
-
-  def test_multiple_delegates_block_argument
-    delegator = ExceptionNotifier::Rake::MultiDelegator.new([@delegate1, @delegate2])
-    result = delegator.map! do |e| e + 1 end
-    assert_equal [], result
-    assert_equal [], @delegate1
-    assert_equal [43], @delegate2
-  end
-end