exception_notification 4.3.0 → 4.4.0

data/docs/notifiers/irc.md

@@ -0,0 +1,97 @@
+### IRC notifier
+
+This notifier sends notifications to an IRC channel using the carrier-pigeon gem.
+
+#### Usage
+
+Just add the [carrier-pigeon](https://github.com/portertech/carrier-pigeon) gem to your `Gemfile`:
+
+```ruby
+gem 'carrier-pigeon'
+```
+
+To configure it, you need to set at least the 'domain' option, like this:
+
+```ruby
+Rails.application.config.middleware.use ExceptionNotification::Rack,
+                                        email: {
+                                          email_prefix: '[PREFIX] ',
+                                          sender_address: %{"notifier" <notifier@example.com>},
+                                          exception_recipients: %w{exceptions@example.com}
+                                        },
+                                        irc: {
+                                          domain: 'irc.example.com'
+                                        }
+```
+
+There are several other options, which are described below. For example, to use ssl and a password, add a prefix, post to the '#log' channel, and include recipients in the message (so that they will be notified), your configuration might look like this:
+
+```ruby
+Rails.application.config.middleware.use ExceptionNotification::Rack,
+                                        irc: {
+                                          domain: 'irc.example.com',
+                                          nick: 'BadNewsBot',
+                                          password: 'secret',
+                                          port: 6697,
+                                          channel: '#log',
+                                          ssl: true,
+                                          prefix: '[Exception Notification]',
+                                          recipients: ['peter', 'michael', 'samir']
+                                        }
+```
+
+#### Options
+
+##### domain
+
+*String, required*
+
+The domain name of your IRC server.
+
+##### nick
+
+*String, optional*
+
+The message will appear from this nick. Default : 'ExceptionNotifierBot'.
+
+##### password
+
+*String, optional*
+
+Password for your IRC server.
+
+##### port
+
+*String, optional*
+
+Port your IRC server is listening on. Default : 6667.
+
+##### channel
+
+*String, optional*
+
+Message will appear in this channel. Default : '#log'.
+
+##### notice
+
+*Boolean, optional*
+
+Send a notice. Default : false.
+
+##### ssl
+
+*Boolean, optional*
+
+Whether to use SSL. Default : false.
+
+##### join
+
+*Boolean, optional*
+
+Join a channel. Default : false.
+
+##### recipients
+
+*Array of strings, optional*
+
+Nicks to include in the message. Default: []

data/docs/notifiers/mattermost.md

@@ -0,0 +1,115 @@
+### Mattermost notifier
+
+Post notification in a mattermost channel via [incoming webhook](http://docs.mattermost.com/developer/webhooks-incoming.html)
+
+Just add the [HTTParty](https://github.com/jnunemaker/httparty) gem to your `Gemfile`:
+
+```ruby
+gem 'httparty'
+```
+
+To configure it, you **need** to set the `webhook_url` option.
+You can also specify an other channel with `channel` option.
+
+```ruby
+Rails.application.config.middleware.use ExceptionNotification::Rack,
+                                        email: {
+                                          email_prefix: '[PREFIX] ',
+                                          sender_address: %{"notifier" <notifier@example.com>},
+                                          exception_recipients: %w{exceptions@example.com}
+                                        },
+                                        mattermost: {
+                                          webhook_url: 'http://your-mattermost.com/hooks/blablabla',
+                                          channel: 'my-channel'
+                                        }
+```
+
+If you are using Github or Gitlab for issues tracking, you can specify `git_url` as follow to add a *Create issue* link in you notification.
+By default this will use your Rails application name to match the git repository. If yours differ you can specify `app_name`.
+
+
+```ruby
+Rails.application.config.middleware.use ExceptionNotification::Rack,
+                                        email: {
+                                          email_prefix: '[PREFIX] ',
+                                          sender_address: %{"notifier" <notifier@example.com>},
+                                          exception_recipients: %w{exceptions@example.com}
+                                        },
+                                        mattermost: {
+                                          webhook_url: 'http://your-mattermost.com/hooks/blablabla',
+                                          git_url: 'github.com/aschen'
+                                        }
+```
+
+You can also specify the bot name and avatar with `username` and `avatar` options.
+
+```ruby
+Rails.application.config.middleware.use ExceptionNotification::Rack,
+                                        email: {
+                                          email_prefix: 'PREFIX] ',
+                                          sender_address: %{"notifier" <notifier@example.com>},
+                                          exception_recipients: %w{exceptions@example.com}
+                                        },
+                                        mattermost: {
+                                          webhook_url: 'http://your-mattermost.com/hooks/blablabla',
+                                          avatar: 'http://example.com/your-image.png',
+                                          username: 'Fail bot'
+                                        }
+```
+
+Finally since the notifier use HTTParty, you can include all HTTParty options, like basic_auth for example.
+
+```ruby
+Rails.application.config.middleware.use ExceptionNotification::Rack,
+                                        email: {
+                                          email_prefix: '[PREFIX] ',
+                                          sender_address: %{"notifier" <notifier@example.com>},
+                                          exception_recipients: %w{exceptions@example.com}
+                                        },
+                                        mattermost: {
+                                          webhook_url: 'http://your-mattermost.com/hooks/blablabla',
+                                          basic_auth: {
+                                            username: 'clara',
+                                            password: 'password'
+                                          }
+                                        }
+```
+
+#### Options
+
+##### webhook_url
+
+*String, required*
+
+The Incoming WebHook URL on mattermost.
+
+##### channel
+
+*String, optional*
+
+Message will appear in this channel. Defaults to the channel you set as such on mattermost.
+
+##### username
+
+*String, optional*
+
+Username of the bot. Defaults to "Incoming Webhook"
+
+##### avatar
+
+*String, optional*
+
+Avatar of the bot. Defaults to incoming webhook icon.
+
+##### git_url
+
+*String, optional*
+
+Url of your gitlab or github with your organisation name for issue creation link (Eg: `github.com/aschen`). Defaults to nil and don't add link to the notification.
+
+##### app_name
+
+*String, optional*
+
+Your application name used for issue creation link. Defaults to `Rails.application.class.module_parent_name.underscore` for Rails versions >= 6;
+`Rails.application.class.parent_name.underscore` otherwise.

data/docs/notifiers/slack.md

@@ -0,0 +1,161 @@
+### Slack notifier
+
+This notifier sends notifications to a slack channel using the slack-notifier gem.
+
+#### Usage
+
+Just add the [slack-notifier](https://github.com/stevenosloan/slack-notifier) gem to your `Gemfile`:
+
+```ruby
+gem 'slack-notifier'
+```
+
+To configure it, you need to set at least the 'webhook_url' option, like this:
+
+```ruby
+Rails.application.config.middleware.use ExceptionNotification::Rack,
+                                        email: {
+                                          email_prefix: '[PREFIX] ',
+                                          sender_address: %{"notifier" <notifier@example.com>},
+                                          exception_recipients: %w{exceptions@example.com}
+                                        },
+                                        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):
+
+```ruby
+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:
+
+```ruby
+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`
+
+```ruby
+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.
+```ruby
+ 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:
+```ruby
+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:
+```ruby
+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](https://github.com/stevenosloan/slack-notifier#custom-hook-name) 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](https://github.com/stevenosloan/slack-notifier#additional-parameters) for more information.. Default: '{}'
+
+##### additional_fields
+
+*Array of Hashes, optional*
+
+Contains additional fields that will be added to the attachement. See [Slack documentation](https://api.slack.com/docs/message-attachments).

data/docs/notifiers/sns.md

@@ -0,0 +1,37 @@
+### Amazon SNS Notifier
+
+Notify all exceptions Amazon - Simple Notification Service: [SNS](https://aws.amazon.com/sns/).
+
+#### Usage
+
+Add the [aws-sdk-sns](https://github.com/aws/aws-sdk-ruby/tree/master/gems/aws-sdk-sns) gem to your `Gemfile`:
+
+```ruby
+  gem 'aws-sdk-sns', '~> 1.5'
+```
+
+To configure it, you **need** to set 3 required options for aws: `region`, `access_key_id` and `secret_access_key`, and one more option for sns: `topic_arn`.
+
+```ruby
+Rails.application.config.middleware.use ExceptionNotification::Rack,
+                                        sns: {
+                                          region: 'us-east-x',
+                                          access_key_id: 'access_key_id',
+                                          secret_access_key: 'secret_access_key',
+                                          topic_arn: 'arn:aws:sns:us-east-x:XXXX:my-topic'
+                                        }
+```
+
+##### sns_prefix
+*String, optional *
+
+Prefix in the notification subject, by default: "[Error]"
+
+##### backtrace_lines
+*Integer, optional *
+
+Number of backtrace lines to be displayed in the notification message. By default: 10
+
+#### Note:
+* You may need to update your previous `aws-sdk-*` gems in order to setup `aws-sdk-sns` correctly.
+* If you need any further information about the available regions or any other SNS related topic consider: [SNS faqs](https://aws.amazon.com/sns/faqs/)

data/docs/notifiers/teams.md

@@ -0,0 +1,54 @@
+### Teams notifier
+
+Post notification in a Microsoft Teams channel via [Incoming Webhook Connector](https://docs.microsoft.com/en-us/outlook/actionable-messages/actionable-messages-via-connectors)
+Just add the [HTTParty](https://github.com/jnunemaker/httparty) gem to your `Gemfile`:
+
+```ruby
+gem 'httparty'
+```
+
+To configure it, you **need** to set the `webhook_url` option.
+If you are using GitLab for issue tracking, you can specify `git_url` as follows to add a *Create issue* button in your notification.
+By default this will use your Rails application name to match the git repository. If yours differs, you can specify `app_name`.
+By that same notion, you may also set a `jira_url` to get a button that will send you to the New Issue screen in Jira.
+
+```ruby
+Rails.application.config.middleware.use ExceptionNotification::Rack,
+  email: {
+    email_prefix: "[PREFIX] ",
+    sender_address: %{"notifier" <notifier@example.com>},
+    exception_recipients: %w{exceptions@example.com}
+  },
+  teams: {
+    webhook_url: 'https://outlook.office.com/webhook/your-guid/IncomingWebhook/team-guid',
+    git_url: 'https://your-gitlab.com/Group/Project',
+    jira_url: 'https://your-jira.com'
+  }
+```
+
+#### Options
+
+##### webhook_url
+
+*String, required*
+
+The Incoming WebHook URL on Teams.
+
+##### git_url
+
+*String, optional*
+
+Url of your gitlab or github with your organisation name for issue creation link (Eg: `github.com/aschen`). Defaults to nil and doesn't add link to the notification.
+
+##### jira_url
+
+*String, optional*
+
+Url of your Jira instance, adds button for Create Issue screen. Defaults to nil and doesn't add a button to the card.
+
+##### app_name
+
+*String, optional*
+
+Your application name used for git issue creation link. Defaults to `Rails.application.class.module_parent_name.underscore` for Rails versions >= 6;
+`Rails.application.class.parent_name.underscore` otherwise.