bugsnag 2.8.12 → 2.8.13

data/VERSION

@@ -1 +1 @@
-2.8.12
+2.8.13

data/docs/Configuration.md

@@ -0,0 +1,239 @@
+# `bugsnag-ruby` Configuration
+
+To configure additional Bugsnag settings, use the block syntax and set any
+settings you need on the `config` block variable. For example:
+
+```ruby
+Bugsnag.configure do |config|
+  config.api_key = "your-api-key-here"
+  config.notify_release_stages = ["production", "development"]
+end
+```
+
+## Available Options
+
+### `api_key`
+
+Your Bugsnag API key (required).
+
+```ruby
+config.api_key = "your-api-key-here"
+```
+
+### `app_type`
+
+You can set the type of application executing the current code by using
+`app_type`:
+
+```ruby
+config.app_type = "resque"
+```
+
+This is usually used to represent if you are running in a Rails server, Sidekiq
+job or Rake task for example. Bugsnag will automatically detect most application
+types for you.
+
+### `app_version`
+
+If you want to track in which versions of your application each exception
+happens, you can set `app_version`. This is set to `nil` by default.
+
+```ruby
+config.app_version = "2.5.1"
+```
+
+### `auto_notify`
+
+By default, we will automatically notify Bugsnag of any fatal exceptions
+in your application. If you want to stop this from happening, you can set
+`auto_notify`:
+
+```ruby
+config.auto_notify = false
+```
+
+### `endpoint`
+
+By default, we'll send crashes to *notify.bugsnag.com* to display them on
+your dashboard. If you are using *Bugsnag Enterprise* you'll need to set
+this to be your *Event Server* endpoint, for example:
+
+```ruby
+config.endpoint = "bugsnag.example.com:49000"
+```
+
+### `ignore_classes`
+
+Sets for which exception classes we should not send exceptions to bugsnag.com.
+
+```ruby
+config.ignore_classes << "ActiveRecord::StatementInvalid"
+```
+
+You can also provide a lambda function here to ignore by other exception
+attributes or by a regex:
+
+```ruby
+config.ignore_classes << lambda {|ex| ex.message =~ /timeout/}
+```
+
+By default, `ignore_classes` contains the following:
+
+```ruby
+[
+  "ActiveRecord::RecordNotFound",
+  "ActionController::RoutingError",
+  "ActionController::InvalidAuthenticityToken",
+  "CGI::Session::CookieStore::TamperedWithCookie",
+  "ActionController::UnknownAction",
+  "AbstractController::ActionNotFound"
+]
+```
+
+### `ignore_user_agents`
+
+Sets an array of Regexps that can be used to ignore exceptions from
+certain user agents.
+
+```ruby
+config.ignore_user_agents << %r{Chrome}
+```
+
+By default, `ignore_user_agents` is empty, so exceptions caused by all
+user agents are reported.
+
+### `logger`
+
+Sets which logger to use for Bugsnag log messages. In rails apps, this is
+automatically set to use `Rails.logger`, otherwise it will be set to
+`Logger.new(STDOUT)`.
+
+### `middleware`
+
+Provides access to the middleware stack, see the
+[Bugsnag Middleware](#bugsnag-middleware) section below for details.
+
+### `notify_release_stages`
+
+By default, we will notify Bugsnag of exceptions that happen in any
+`release_stage`. If you would like to change which release stages
+notify Bugsnag of exceptions you can set `notify_release_stages`:
+
+```ruby
+config.notify_release_stages = ["production", "development"]
+```
+
+### `params_filters`
+
+Sets which keys should be filtered out from `params` hashes before sending
+them to Bugsnag. Use this if you want to ensure you don't send sensitive data
+such as passwords, and credit card numbers to our servers. You can add both
+strings and regular expressions to this array. When adding strings, keys which
+*contain* the string will be filtered. When adding regular expressions, any
+keys which *match* the regular expression will be filtered.
+
+```ruby
+config.params_filters += ["credit_card_number", /^password$/]
+```
+
+By default, `params_filters` is set to `[/authorization/i, /cookie/i,
+/password/i, /secret/i]`, and for rails apps, imports all values from
+`Rails.configuration.filter_parameters`.
+
+<!-- Custom anchor for linking from alerts -->
+<div id="set-project-root"></div>
+### `project_root`
+
+We mark stacktrace lines as `inProject` if they come from files inside your
+`project_root`. In rails apps this value is automatically set to `RAILS_ROOT`,
+otherwise you should set it manually:
+
+```ruby
+config.project_root = "/var/www/myproject"
+```
+
+### `proxy_host`
+
+Sets the address of the HTTP proxy that should be used for requests to bugsnag.
+
+```ruby
+config.proxy_host = "10.10.10.10"
+```
+
+### `proxy_password`
+
+Sets the password for the user that should be used to send requests to the HTTP proxy for requests to bugsnag.
+
+```ruby
+config.proxy_password = "proxy_secret_password_here"
+```
+
+### `proxy_port`
+
+Sets the port of the HTTP proxy that should be used for requests to bugsnag.
+
+```ruby
+config.proxy_port = 1089
+```
+
+### `proxy_user`
+
+Sets the user that should be used to send requests to the HTTP proxy for requests to bugsnag.
+
+```ruby
+config.proxy_user = "proxy_user"
+```
+
+### `release_stage`
+
+If you would like to distinguish between errors that happen in different
+stages of the application release process (development, production, etc)
+you can set the `release_stage` that is reported to Bugsnag.
+
+```ruby
+config.release_stage = "development"
+```
+
+In rails apps this value is automatically set from `RAILS_ENV`, and in rack
+apps it is automatically set to `RACK_ENV`. Otherwise the default is
+"production".
+
+### `send_environment`
+
+Bugsnag can transmit your rack environment to help diagnose issues. This environment
+can sometimes contain private information so Bugsnag does not transmit by default. To
+send your rack environment, set the `send_environment` option to `true`.
+
+```ruby
+config.send_environment = true
+```
+
+### `send_code`
+
+Bugsnag automatically sends a small snippet of the code that crashed to help you diagnose
+even faster from within your dashboard. If you don't want to send this snippet you can
+set the `send_code` option to `false`.
+
+```ruby
+config.send_code = false
+```
+
+### `timeout`
+By default the timeout for posting errors to Bugsnag is 15 seconds, to change this
+you can set the `timeout`:
+
+```ruby
+config.timeout = 10
+```
+
+### `use_ssl`
+
+Enforces all communication with bugsnag.com be made via ssl. You can turn
+this off if necessary.
+
+```ruby
+config.use_ssl = false
+```
+
+By default, `use_ssl` is set to true.
+

data/docs/Notification Options.md

@@ -0,0 +1,269 @@
+# `bugsnag-ruby` Notification Options
+
+It is often useful to send additional meta-data about your app, such as
+information about the currently logged in user, along with any
+exceptions, to help debug problems.
+
+* [Notification Object](#notification-object)
+    - [Instance Methods](#instance-methods)
+    - [`Bugsnag::MetaData` Exception Mixin](#exception-mixin)
+* [Handled Notification Options](#handled-notification-options)
+* [Framework-specific Configuration](#framework-specific-configuration)
+    - [Rails Apps](#rails-apps)
+    - [Rails API Apps](#rails-api-apps)
+    - [Other Ruby Apps](#other-ruby-apps)
+
+## Notification Object
+
+The notification object is passed to all [before bugsnag notify](#sending-custom-data-with-exceptions)
+callbacks and is used to manipulate the error report before it is transmitted.
+
+### Instance Methods
+
+#### `add_tab`
+
+Call add_tab on a notification object to add a tab to the error report so that
+it would appear on your dashboard.
+
+```ruby
+notif.add_tab(:user_info, {
+      name: current_user.name
+})
+```
+
+The first parameter is the tab name that will appear in the error report and the
+second is the key, value list that will be displayed in the tab.
+
+#### `remove_tab`
+
+Removes a tab completely from the error report
+
+```ruby
+notif.remove_tab(:request)
+```
+
+#### `ignore!`
+
+Calling ignore! on a notification object will cause the notification to not be
+sent to bugsnag. This means that you can choose dynamically not to send an error
+depending on application state or the error itself.
+
+```ruby
+notif.ignore! if foo == 'bar'
+```
+
+#### `grouping_hash`
+
+Sets the grouping hash of the error report. All errors with the same grouping
+hash are grouped together. This is an advanced usage of the library and
+mis-using it will cause your errors not to group properly in your dashboard.
+
+```ruby
+notif.grouping_hash = "#{exception.message}#{exception.class}"
+```
+
+#### `severity`
+
+Set the severity of the error. Severity can be `error`, `warning` or `info`.
+
+```ruby
+notif.severity = "error"
+```
+
+#### `context`
+
+Set the context of the error report. This is notionally the location of the
+error and should be populated automatically. Context is displayed in the
+dashboard prominently.
+
+```ruby
+notif.context = "billing"
+```
+
+#### `user`
+
+You can set or read the user with the user property of the notification. The
+user will be a hash of `email`, `id` and `name`.
+
+```ruby
+notif.user = {
+      id: current_user.id,
+        email: current_user.email,
+          name: current_user.name
+}
+```
+
+#### `exceptions`
+
+Allows you to read the exceptions that will be combined into the report.
+
+```ruby
+puts "#{notif.exceptions.first.message} found!"
+```
+
+#### `meta_data`
+
+Provides access to the meta_data in the error report.
+
+```ruby
+notif.ignore! if notif.meta_data[:sidekiq][:retry_count] > 2
+```
+
+### Exception Mixin
+
+If you include the `Bugsnag::MetaData` module into your own exceptions, you can
+associate meta data with a particular exception.
+
+```ruby
+class MyCustomException < Exception
+  include Bugsnag::MetaData
+end
+
+exception = MyCustomException.new("It broke!")
+exception.bugsnag_meta_data = {
+  :user_info => {
+    name: current_user.name
+  }
+}
+
+raise exception
+```
+
+## Handled Notification Options
+
+Non-fatal exception notifications can send additional metadata in when being
+sent via `Bugsnag.notify` including setting the severity and custom data.
+
+#### Severity
+
+You can set the severity of an error in Bugsnag by including the severity option when
+notifying bugsnag of the error,
+
+```ruby
+Bugsnag.notify(RuntimeError.new("Something broke"), {
+  :severity => "error",
+})
+```
+
+Valid severities are `error`, `warning` and `info`.
+
+Severity is displayed in the dashboard and can be used to filter the error list.
+By default all crashes (or unhandled exceptions) are set to `error` and all
+`Bugsnag.notify` calls default to `warning`.
+
+#### Multiple projects
+
+If you want to divide errors into multiple Bugsnag projects, you can specify the API key as a parameter to `Bugsnag.notify`:
+
+```ruby
+rescue => e
+  Bugsnag.notify e, api_key: "your-api-key-here"
+end
+```
+
+#### Custom Metadata
+
+You can also send additional meta-data with your exception:
+
+```ruby
+Bugsnag.notify(RuntimeError.new("Something broke"), {
+  :user => {
+    :username => "bob-hoskins",
+    :registered_user => true
+  }
+})
+```
+
+#### Custom Grouping via `grouping_hash`
+
+If you want to override Bugsnag's grouping algorithm, you can specify a grouping hash key as a parameter to `Bugsnag.notify`:
+
+```ruby
+rescue => e
+  Bugsnag.notify e, grouping_hash: "this-is-my-grouping-hash"
+end
+```
+
+All errors with the same groupingHash will be grouped together within the bugsnag dashboard.
+
+## Framework-specific Configuration
+
+### Rails Apps
+
+By default Bugsnag includes some information automatically. For example, we
+send all the HTTP headers for requests. Additionally if you're using Warden or
+Devise, the id, name and email of the current user are sent.
+
+To send additional information, in any rails controller you can define a
+`before_bugsnag_notify` callback, which allows you to add this additional data
+by calling `add_tab` on the exception notification object. Please see the
+[Notification Object](#notification-object) for details on the notification
+parameter.
+
+```ruby
+class MyController < ApplicationController
+  # Define the filter
+  before_bugsnag_notify :add_user_info_to_bugsnag
+
+  # Your controller code here
+
+  private
+  def add_user_info_to_bugsnag(notif)
+    # Set the user that this bug affected
+    # Email, name and id are searchable on bugsnag.com
+    notif.user = {
+      email: current_user.email,
+      name: current_user.name,
+      id: current_user.id
+    }
+
+    # Add some app-specific data which will be displayed on a custom
+    # "Diagnostics" tab on each error page on bugsnag.com
+    notif.add_tab(:diagnostics, {
+      product: current_product.name
+    })
+  end
+end
+```
+
+### Rails API Apps
+
+If you are building an API using the
+[rails-api](https://github.com/rails-api/rails-api) gem, your controllers will
+inherit from `ActionController::API` instead of `ActionController::Base`.
+
+In this case, the `before_bugsnag_notify` filter will not be automatically
+available in your controllers.  In order to use it, you will need to include
+the module `Bugsnag::Rails::ControllerMethods`.
+
+```ruby
+class ApplicationController < ActionController::API
+
+  # Include module which defines the before_bugsnag_notify filter
+  include Bugsnag::Rails::ControllerMethods
+
+  # Other code here
+end
+```
+
+### Other Ruby Apps
+
+In other ruby apps, you can provide lambda functions to execute before any
+`Bugsnag.notify` calls as follows. Don't forget to clear the callbacks at the
+end of each request or session. In Rack applications like Sinatra, this is
+automatically done for you.
+
+```ruby
+# Set a before notify callback
+Bugsnag.before_notify_callbacks << lambda {|notif|
+  notif.add_tab(:user_info, {
+    name: current_user.name
+  })
+}
+
+# Your app code here
+
+# Clear the callbacks
+Bugsnag.before_notify_callbacks.clear
+```
+