Configuration options

Customize the content of error reports and how reports are delivered to BugSnag.

BugSnag can be configured using the configure block:

Bugsnag.configure do |config|
  config.api_key = 'your-api-key-here'
end

The configuration for BugSnag can also be changed by accessing the configuration directly:

Bugsnag.configuration.api_key = 'your-api-key-here'

Configuration options

add_metadata

Set diagnostic metadata that you want to send with all captured events — see Customizing Error Reports for more information.

config.add_metadata(:company, {
  name: 'Acme Co.',
  country: 'uk'
})

add_on_breadcrumb

Add callbacks to modify or discard breadcrumbs before they are attached to error reports — see customizing breadcrumbs for more information.

callback = proc do |breadcrumb|
  if breadcrumb.message == 'should ignore'
    # ignore the breadcrumb if the message is 'should ignore'
    false
  else
    # amend the breadcrumb metadata if not ignored
    breadcrumb.metadata[:captured] = true
  end
end

config.add_on_breadcrumb(callback)

add_on_error

Add callbacks to modify or discard error events before they are sent to BugSnag — see Customizing Error Reports for more information.

callback = proc |event| do
  event.set_user("9000", "bugs.nag@bugsnag.com", "Bugs Nag")
end

config.add_on_error(callback)

To use a block as a callback, use the on_error option.

api_key

Your Integration API Key (required).

config.api_key = 'your-api-key-here'

You can find your API key in Project Settings from your BugSnag dashboard.

app_type

You can set the type of application executing the current code by using app_type:

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.

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:

config.auto_notify = false

auto_capture_sessions

By default, BugSnag will automatically capture and report session information from your application. Use this flag to disable all automatic reporting.

config.auto_capture_sessions = false

auto_track_sessions

By default, BugSnag will automatically capture and report session information from your application. Use this flag to disable all automatic reporting.

config.auto_track_sessions = false

before_breadcrumb_callbacks

An array of callbacks to be run when a breadcrumb is left. Each callback will be passed a breadcrumb.

config.before_breadcrumb_callbacks << Proc.new do |breadcrumb|
  breadcrumb.metadata[:paying_customer] = true
end

clear_metadata

Clear diagnostic metadata that was previously added with add_metadata — see Customizing Error Reports for more information.

config.clear_metadata(:company)

context

Set the context for all future error reports, which is displayed in the dashboard prominently. This will prevent BugSnag from setting the context automatically.

config.context = "Example"

You can set this to nil to prevent automatic context setting without having to supply your own value. In this case, the BugSnag app will set the context instead.

config.context = nil

discard_classes

Sets exception classes that will be discarded and not sent to BugSnag.

config.discard_classes << "ActiveRecord::StatementInvalid"

You can also provide a regular expression to match multiple errors at once.

config.discard_classes << /^ActiveRecord::.*/

By default, the following classes will be discarded:

[
  "SystemExit",
  "SignalException"
]

delivery_method

Determines how events and sessions are sent to BugSnag. By default, Resque and Shoryuken applications will use the :synchronous method and other applications use :thread_queue.

config.delivery_method = :thread_queue

The delivery methods available by default are:

• :synchronous — sends data immediately, blocking the current thread.
• :thread_queue — adds data to a queue, which will be sent when the current thread exits.

Custom delivery methods can be implemented by creating a class that has a static deliver method, with this signature:

##
# @param url [String] The URL to send the data to.
# @param body [String] The serialised request data to send.
# @param configuration [Bugsnag::Configuration] A BugSnag Configuration object.
# @param options [Hash] Holds the HTTP headers for the request under the ':headers' key.
def self.deliver(url, body, configuration, options={})

The new delivery method must be registered before it can be used:

Bugsnag::Delivery.register(:my_delivery_method, MyDeliveryMethodClass)

enabled_automatic_breadcrumb_types

An array of types that can be automatically captured. Defaults to all breadcrumb types.

Setting this to an empty array will prevent automatic breadcrumb capture.

config.enabled_automatic_breadcrumb_types = [] # No breadcrumbs will automatically be captured

enabled_breadcrumb_types

An array of types that can be automatically captured. Defaults to all breadcrumb types.

Setting this to an empty array will prevent automatic breadcrumb capture.

config.enabled_breadcrumb_types = [] # No breadcrumbs will automatically be captured

There is a list of possible types within the Bugsnag::BreadcrumbType module.

enabled_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 enabled_release_stages:

config.enabled_release_stages = ['production', 'development']

endpoints

By default we will send error reports to notify.bugsnag.com and sessions to sessions.bugsnag.com.

If you are using BugSnag On-premise you’ll need to set these to your Event Server and Session Server endpoints. If the notify endpoint is set but the sessions endpoint is not, session tracking will be disabled automatically to avoid leaking session information outside of your server configuration, and a warning will be logged.

config.endpoints = Bugsnag::EndpointConfiguration.new(
  "https://bugsnag-notify.example.com", # Your notify, "Event Server", endpoint
  "https://bugsnag-session.example.com", # Your session, "Session Server", endpoint
)

hostname

The name or descriptor of the Ruby server host. Defaults to the server’s hostname.

config.hostname = "NameOfServer-1B"

ignore_classes

Sets for which exception classes we should not send exceptions to BugSnag.

config.ignore_classes << ActiveRecord::StatementInvalid

You can also provide a lambda function here to ignore by other exception attributes or by a regex:

config.ignore_classes << lambda {|ex| ex.message =~ /timeout/}

By default, ignore_classes contains the following:

[
  SystemExit,
  SignalException
]

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).

To hide lower-level messages from the BugSnag library, the logger can be reconfigured as follows:

config.logger = Logger.new(STDOUT) # In Rails apps, create a new logger to avoid
                                   # changing the Rails log level
config.logger.level = Logger::ERROR

max_breadcrumbs

The number of breadcrumbs that can be captured before the oldest start to be dropped. Defaults to 25.

config.max_breadcrumbs = 10 # A maximum of 10 breadcrumbs will be kept at any one time

meta_data_filters

Sets which keys should be filtered out from the event and breadcrumb metadata 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.

config.meta_data_filters += ['credit_card_number', /^password$/]

By default, meta_data_filters is set to

[
  /authorization/i,
  /cookie/i,
  /password/i,
  /secret/i,
  /warden\.user\.([^.]+)\.key/,
  "rack.request.form_vars"
]

and for Rails apps, all values from Rails.configuration.filter_parameters are added as well. String values within Rails.configuration.filter_parameters are matched as case-sensitive substrings and regular expression values are imported as-is.

Note: Assigning (=) instead of appending (+=) to the default value will remove the default protections.

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:

config.notify_release_stages = ['production', 'development']

on_error

Add blocks to modify or discard error events before they are sent to BugSnag — see Customizing Error Reports for more information.

config.on_error do |event|
  event.set_user("9000", "bugs.nag@bugsnag.com", "Bugs Nag")
end

To add an object that responds to #call, such as a Proc or Method, use the add_on_error option.

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:

config.project_root = '/var/www/myproject'

proxy_host

Sets the address of the HTTP proxy that should be used for requests to BugSnag.

config.proxy_host = '10.10.10.10'

All proxy options can also be configured using the http_proxy or https_proxy environment variables as described in the Net::HTTP documentation:

http_proxy='http://username:password@hostname:port'

Alternatively the proxy options can be parsed from a url by calling the parse_proxy method:

config.parse_proxy('http://username:password@hostname:port')

proxy_password

Sets the password for the user that should be used to send requests to the HTTP proxy for requests to bugsnag.

config.proxy_password = 'proxy_secret_password_here'

proxy_port

Sets the port of the HTTP proxy that should be used for requests to BugSnag.

config.proxy_port = 1089

proxy_user

Sets the user that should be used to send requests to the HTTP proxy for requests to bugsnag.

config.proxy_user = 'proxy_user'

redacted_keys

Sets which values should be removed from any metadata before sending them to BugSnag. Use this if you want to ensure you don’t transmit sensitive data such as passwords and credit card numbers.

When adding strings, keys that are equal to the string (ignoring case) will be redacted. When adding regular expressions, any keys which match the regular expression will be redacted.

config.redacted_keys += ['credit_card_number', /^password$/]

By default, the following values will be redacted:

[
  /authorization/i,
  /cookie/i,
  /password/i,
  /secret/i,
  /warden\.user\.([^.]+)\.key/,
  "rack.request.form_vars"
]

and for Rails apps, all values from Rails.configuration.filter_parameters are added as well. String values within Rails.configuration.filter_parameters are matched as case-sensitive substrings and regular expression values are imported as-is.

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.

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.

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.

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:

config.timeout = 10

vendor_path

Sets the regular expression used to determine whether a stacktrace line is considered out of project.

config.vendor_path = %r{^(vendor\/|\.bundle\/|third_party\/)}

By default this includes vendor/ and .bundle/ but can be expanded to include further directories under the project root that you would like BugSnag to consider “out of project” for grouping purposes.

vendor_paths

An array of paths within the project root that should not be considered as “in project”.

These paths should be relative to the project root and will only match whole directory names.

config.vendor_paths = ['vendor', '.bundle', 'third_party']

By default, vendor and .bundle will not be considered in project.

Custom middleware loading

By default all Ruby framework integrations BugSnag provides will be initialized when the notifier is loaded. This behaviour can be disabled by setting the environment variable BUGSNAG_DISABLE_AUTOCONFIGURE to true inside of your application. Integrations can then be required as necessary using:

Bugsnag.load_integration(:sidekiq)