rusen

The Ruby Simple Exception Notification (a.k.a Rusen) gem provides a simple way for logging and sending errors in any Ruby application.

Notifications include information about the current request, session, environment. They also provide a backtrace of the exception.

Installation

Just add the following line in your Gemfile

gem 'rusen'

Usage

With global configuration

The easiest way to use it is with global configuration.

First you configure Rusen

require 'rusen'

Rusen.settings.sender_address = '[e-mail]'
Rusen.settings.exception_recipients = %w([e-mail])
Rusen.settings.smtp_settings = {
  :address              => 'smtp.gmail.com',
  :port                 => 587,
  :domain               => 'example.org',
  :authentication       => :plain,
  :user_name            => '[e-mail]',
  :password             => 'xxxxxxx',
  :enable_starttls_auto => true
}

And then you can start sending notifications:

begin
  method.call
rescue Exception => exception
  Rusen.notify(exception)
end

This way, if you modify the notifications settings at runtime, every notification sent afterwards will use the new settings.

With local configuration

This method lets you have more control when notifying. You may want for example to send an email when a particular exception occurs and just print to stdout otherwise. To achieve this you can do the following:

@email_notifier = Rusen::Notifier.new(@email_settings)

@stdout_settings = Rusen::Settings.new
@stdout_settings.outputs = [:backtrace]

@stdout_notifier = Rusen::Notifier.new(@stdout_settings)

and then:

begin
  method.call
rescue SmallException => exception
  @stdout_notifier.notify(exception)
end

Middleware

Rusen comes with a Rack and rails special (soon to come) middleware for easy usage.

Rack

To use Rusen in any Rack application you just have to add the following code somewhere in your app (ex: config/initializers/rusen.rb):

require 'rusen/middleware/rusen_rack'

use Rusen::Middleware::RusenRack,
    :outputs => [:io, :email],
    :sections => [:backtrace, :request, :session, :environment],
    :email_prefix => '[ERROR] ',
    :sender_address => '[e-mail]',
    :exception_recipients => %w([e-mail]),
    :smtp_settings => {
      :address              => 'smtp.gmail.com',
      :port                 => 587,
      :domain               => 'example.org',
      :authentication       => :plain,
      :user_name            => '[e-mail]',
      :password             => 'xxxxxxx',
      :enable_starttls_auto => true
    }

This will capture any unhandled exception, send an email and write a trace in stdout.

Settings

Outputs

Currently supported outputs are :io, :lo4r, :pony and :mail. More outputs are easy to add so you can customize Rusen to your needs.

Note: :io will only print to stdout for the time being, but there are plans to extend it to anything that Ruby::IO supports.

Pony, lo4r and Mail outputs require additional gems to work.

To use Pony add this to your Gemfile:

  gem 'pony'

To use mail, add this to your Gemfile:

  gem 'mail'

To use log4r, add this to your Gemfile:

  gem 'log4r'

Sections

You can choose the output sections simply by setting the appropriate values in the configuration.

Exclude if

Here you can pass a block that will receive the error. If the block returns false, then the error will be notified.

Email settings

All the email settings are self explanatory, but you can contact [e-mail] if any of them needs clarification.

If you are running Rusen inside Rails and you have configured smtp_settings for your app Rusen will use that settings by default.

Log4r settings

• logger_name (required): Logger used for logging errors.
• log4r_config_file (optional): YAML file that contains Log4r configuration.

Sample of Log4r configuration file contents:

log4r_config:
  loggers:
    - name: error_notifications
      level: ERROR
      trace: false
      outputters:
        - logfile
        - stdoout

  outputters:
    - type: FileOutputter
      name: logfile
      filename: 'log/service.log'

    - type: StdoutOutputter
      name: stdout

Sidekiq

Rusen comes with sidekiq integration builtin to use just add this to your sidekiq initializer:

require 'rusen/sidekiq'

You can configure it with the global Rusen configuration, ex:

require 'rusen/sidekiq'

Rusen.settings.sender_address = '[e-mail]'
Rusen.settings.exception_recipients = %w([e-mail])
Rusen.settings.smtp_settings = {
  :address              => 'smtp.gmail.com',
  :port                 => 587,
  :domain               => 'example.org',
  :authentication       => :plain,
  :user_name            => '[e-mail]',
  :password             => 'xxxxxxx',
  :enable_starttls_auto => true
}

Rusen supports versions ~> 2 and ~> 3 of sidekiq.

Contributors

See the Network View and the CHANGELOG

Contributing

• Fork it
• Create your feature branch (git checkout -b my-new-feature)
• Commit your changes (git commit -am 'Added some feature')
• Push to the branch (git push origin my-new-feature)
• Make sure to add tests for it. This is important so we don't break it in a future version unintentionally.
• Create a new Pull Request

Legal

Rusen is released under the MIT License.