slack.md

Slack notifier

This notifier sends notifications to a slack channel using the slack-notifier gem.

Usage

Just add the slack-notifier gem to your Gemfile:

gem 'slack-notifier'

To configure it, you need to set at least the 'webhook_url' option, like this:

Rails.application.config.middleware.use ExceptionNotification::Rack,
                                        email: {
                                          email_prefix: '[PREFIX] ',
                                          sender_address: %{"notifier" <[email protected]>},
                                          exception_recipients: %w{[email protected]}
                                        },
                                        slack: {
                                          webhook_url: '[Your webhook url]',
                                          channel: '#exceptions',
                                          additional_parameters: {
                                            icon_url: 'http://image.jpg',
                                            mrkdwn: true
                                          }
                                        }

The slack notification will include any data saved under env['exception_notifier.exception_data'].

An example of how to send the server name to Slack in Rails (put this code in application_controller.rb):

before_action :set_notification

def set_notification
  request.env['exception_notifier.exception_data'] = { 'server' => request.env['SERVER_NAME'] }
  # can be any key-value pairs
end

If you find this too verbose, you can determine to exclude certain information by doing the following:

Rails.application.config.middleware.use ExceptionNotification::Rack,
                                        slack: {
                                          webhook_url: '[Your webhook url]',
                                          channel: '#exceptions',
                                          additional_parameters: {
                                            icon_url: 'http://image.jpg',
                                            mrkdwn: true
                                          },
                                          ignore_data_if: lambda {|key, value|
                                            "#{key}" == 'key_to_ignore' || value.is_a?(ClassToBeIgnored)
                                          }
                                        }

Any evaluation to true will cause the key / value pair not be be sent along to Slack.

the slack-notifier gem allows to override the channel default value, if you ever need to send a notification to a different slack channel. Simply add the channel option when calling .notify_exception

ExceptionNotifier.notify_exception(
  exception,
  env: request.env,
  channel: '#my-custom-channel', # Make sure the channel name starts with `#`
  data: {
    error: error_variable,
    server: server_name
  }
)

If you ever need to add more slack-notifier specific options, and particularly to the #ping method of the slack notifier, you can use the pre_callback option when defining the middleware.

 pre_callback: proc { |opts, _notifier, _backtrace, _message, message_opts|
   message_opts[:channel] = opts[:channel] if opts.key?(:channel)
 }

• message_opts is the hash you want to append to if you need to add an option.
• options is the hash containing the values when you call ExceptionNotification.notify_exception

An example implementation would be:

config.middleware.use ExceptionNotification::Rack,
  slack: {
    webhook_url: '[Your webhook url]',
    pre_callback: proc { |opts, _notifier, _backtrace, _message, message_opts|
      message_opts[:ping_option] = opts[:ping_option] if
      opts.key?(:ping_option)
    }
  },
  error_grouping: true

Then when calling from within your application code:

ExceptionNotifier.notify_exception(
  exception,
  env: request.env,
  ping_option: 'value',
  # this will be passed to the slack notifier's `#ping`
  # method, as a parameter. The `:pre_callback` hook will catch it
  # and do that for you.
  # Helpful, if the API evolves, you only need to update
  # the `slack-notifier` gem
  data: {
    error: error_variable,
    server: server_name
  }
)

Options

webhook_url

String, required

The Incoming WebHook URL on slack.

channel

String, optional

Message will appear in this channel. Defaults to the channel you set as such on slack.

username

String, optional

Username of the bot. Defaults to the name you set as such on slack

custom_hook

String, optional

Custom hook name. See slack-notifier for more information. Default: 'incoming-webhook'

additional_parameters

Hash of strings, optional

Contains additional payload for a message (e.g avatar, attachments, etc). See slack-notifier for more information.. Default: '{}'

additional_fields

Array of Hashes, optional

Contains additional fields that will be added to the attachement. See Slack documentation.