Configuration

There are a few ways to configure the Honeybadger gem. You can use a YAML config file. You can use environment variables. You can use Ruby. Or you can use a combination of the three.

We put together a short video highligting a few of the most common configuration options:

YAML Configuration File

By default, Honeybadger looks for a honeybadger.yml configuration file in the root of your project, and then config/honeybadger.yml (in that order).

Here's what the simplest config file looks like:

yaml

---
api_key: "Your project API key"

Nested Options

Some configuration options are written in YAML as nested hashes. For example, here's what the logging.path and request.filter_keys options look like in YAML:

yaml

  

---
logging:
  path: "/path/to/honeybadger.log"
request:
  filter_keys:
    - "credit_card"

Environments

Environment-specific options can be set by name-spacing the options beneath the environment name. For example:

yaml

  

---
api_key: "Your project API key"
production:
  logging:
    path: "/path/to/honeybadger.log"
    level: "WARN"

ERB and Regex

The configuration file is rendered using ERB. That means you can set configuration options programmatically. You can also include regular expressions. Here's what that looks like:

yaml

  

---
api_key: "Your project API key"
request:
  filter_keys:
    - !ruby/regexp '/credit_card/i'

Configuring with Environment Variables (12-factor style)

All configuration options can also be read from environment variables (ENV). To do this, uppercase the option name, replace all non-alphanumeric characters with underscores, and prefix with HONEYBADGER_. For example, logging.path becomes HONEYBADGER_LOGGING_PATH:

export HONEYBADGER_LOGGING_PATH=/path/to/honeybadger.log

ENV options override other options read from framework or honeybadger.yml sources, so both can be used together. For example, if the HONEYBADGER_ENV environment variable is present, it will override the env configuration option and RAILS_ENV environment variable.

Configuration via Ruby (programmatic)

To configure Honeybadger from Ruby, use Honeybadger.configure:

ruby

  

# i.e. config/initializers/honeybadger.rb
Honeybadger.configure do |config|
  config.api_key = "Your project API key"
  config.exceptions.ignore += [CustomError]
end

Note that configuration via Ruby means that until your configuration code is run, Honeybadger will use its default configuration (or the YAML file or environment variables), so for the best experience, this should be as early as possible after startup.

There are also a few special features which can only be configured via Ruby:

Changing Notice Data

Use before_notify callbacks to modify notice data before it's sent to Honeybadger:

ruby

  

Honeybadger.configure do |config|
  config.before_notify do |notice|
    # Use your own error grouping
    notice.fingerprint = App.exception_fingerprint(notice)

    # Ignore notices with sensitive data
    notice.halt! if notice.error_message =~ /sensitive data/

    # Avoid using all your quota for non-production errors by allowing
    # only 10 errors to be sent per minute
    notice.halt! if !Rails.env.production? && Redis.current.incr(key = "honeybadger_errors:#{(Time.now - Time.now.sec).to_i}") > 10
    Redis.current.expire(key, 120)
  end
end

before_notify can be called multiple times to add multiple callbacks.

Changing Event Data

Use before_event callbacks to modify event data before it's sent to Honeybadger:

ruby

  

Honeybadger.configure do |config|
  config.before_event do |event|
    # DB-backed job backends can generate a lot of noisy queries
    if event.event_type == "sql.active_record" && event[:query]&.match?(/good_job|solid_queue/)
      event.halt!
    end

    # Truncate long queries
    if event.event_type == "sql.active_record" && event[:query].present?
      event[:query] = event[:query].first(256)
    end

    # Set some data for each event
    if environment = ENV["HONEYBADGER_ENV"] || Rails.env
      event[:environment] = environment
    end

    # See https://api.rubyonrails.org/classes/ActiveSupport/CurrentAttributes.html for more info about using Current
    event[:user] = { id: Current.user.id, email: Current.user.email } if Current.user

    # Avoid using all your quota for non-production events by allowing
    # only 10 events to be sent per minute
    event.halt! if !Rails.env.production? && Redis.current.incr(key = "honeybadger_event:#{(Time.now - Time.now.sec).to_i}") > 10
    Redis.current.expire(key, 120)
  end
end

before_event can be called multiple times to add multiple callbacks.

Using a Custom `logger`

While you can configure the default logger using the provided options, it's also possible to replace the logger entirely:

ruby

Honeybadger.configure do |config|
  config.logger = MyLogger.new('/path/to/honeybadger.log')
end

Using a Custom `backend`

This option allows you to change the backend which handles all reported data. This is an advanced option—you'll need to read the code to use it:

ruby

Honeybadger.configure do |config|
  config.backend = CustomBackend.new
end

Configuration Options

You can use any of the options below in your config file, or in the environment.

Option	Type	Description
`api_key`	String	The API key for your Honeybadger project. Default: `nil`
`env`	String	The environment the app is running in. In Rails this defaults to `Rails.env`. Default: `nil`
`report_data`	Boolean	Enable/disable reporting of data. Defaults to false for "test", "development", and "cucumber" environments. Default: `true`
`root`	String	The project's absolute root path. Default: `Dir.pwd`
`revision`	String	The project's git revision. Default: revision detected from git
`hostname`	String	The hostname of the current box. Default: `Socket.gethostname`
`backend`	String	An alternate backend to use for reporting data. Default: `nil`
`debug`	Boolean	Enables verbose debug logging. Default: `false`
`send_data_at_exit`	Boolean	Prevent the Ruby program from exiting until all queued notices have been delivered to Honeybadger. (This can take a while in some cases; see `max_queue_size`.) Default: `true`
`max_queue_size`	Integer	Maximum number of notices to queue for delivery at one time; new notices will be dropped if this number is exceeded. Default: `100`
`config_path`	String	The path of the honeybadger config file. Can only be set via the `$HONEYBADGER_CONFIG_PATH` environment variable
`development_environments`	Array	Environments which will not report data by default (use report_data to enable/disable explicitly). Default: `["development", "test", "cucumber"]`
`plugins`	Array	An optional list of plugins to load. Default is to load all plugins. Default: `[]`
`skipped_plugins`	Array	An optional list of plugins to skip. Default: `[]`

INSIGHTS AND EVENTS
`insights.enabled`	Boolean	Enable automatic Insights instrumentation. Default: `false`
`insights.registry_flush_interval`	Integer	Number of seconds to flush the aggregated metrics registry. Set a higher number for greater resolution but use more data. Default: `60`
`events.max_queue_size`	Integer	Number of events before the event queue will start dropping events. Default: `100000`
`events.batch_size`	Integer	Number of events to batch that will trigger the gem to send. Default: `1000`
`events.timeout`	Integer	Number of milliseconds before the event queue will send events regardless of size. Default: `30000`
`events.attach_hostname`	Boolean	Attach server hostname to every event sent by the gem. Default: `true`
`events.ignore`	Array	An list of rules to match against events to be ignored. See Ignoring Events for more information.

LOGGING
`logging.path`	String	The path (absolute, or relative from config.root) to the log file. Defaults to the rails logger or STDOUT. To log to standard out, use 'STDOUT'. Default: `nil`
`logging.level`	String	The log level. Does nothing unless `logging.path` is also set. Default: `INFO`
`logging.tty_level`	String	Level to log when attached to a terminal (anything < `logging.level` will always be ignored). Default: `DEBUG`

HTTP CONNECTION
`connection.secure`	Boolean	Use SSL when sending data. Default: `true`
`connection.host`	String	The host to use when sending data. Default: `api.honeybadger.io`
`connection.port`	Integer	The port to use when sending data. Default: `443`
`connection.http_open_timeout`	Integer	The HTTP open timeout when connecting to the server. Default: `2`
`connection.http_read_timeout`	Integer	The HTTP read timeout when connecting to the server. Default: `5`
`connection.proxy_host`	String	The proxy host to use when sending data. Default: `nil`
`connection.proxy_port`	Integer	The proxy port to use when sending data. Default: `nil`
`connection.proxy_user`	String	The proxy user to use when sending data. Default: `nil`
`connection.proxy_pass`	String	The proxy password to use when sending data. Default: `nil`

REQUEST DATA FILTERING
`request.filter_keys`	Array	A list of keys to filter when sending request data. In Rails, this also includes existing params filters. Default: `['password', 'password_confirmation']`
`request.disable_session`	Boolean	Prevent session from being sent with request data. Default: `false`
`request.disable_params`	Boolean	Prevent params from being sent with request data. Default: `false`
`request.disable_environment`	Boolean	Prevent Rack environment from being sent with request data. Default: `false`
`request.disable_url`	Boolean	Prevent url from being sent with request data (Rack environment may still contain it in some cases). Default: `false`

USER INFORMER
`user_informer.enabled`	Boolean	Enable the UserInformer middleware. The user informer displays information about a Honeybadger error to your end-users when you display a 500 error page. This typically includes the error id which can be used to reference the error inside your Honeybadger account. Learn More Default: `true`
`user_informer.info`	String	Replacement string for HTML comment in templates. Default: `'Honeybadger Error {{error_id}}'`

USER FEEDBACK
`feedback.enabled`	Boolean	Enable the UserFeedback middleware. Feedback displays a comment form to your-end user when they encounter an error. When the user creates a comment, it is added to the error in Honeybadger, and a notification is sent. Learn More Default: `true`

EXCEPTION REPORTING
`exceptions.enabled`	Boolean	Enable error reporting functionality. Default: `true`
`exceptions.ignore`	Array	A list of exception class names to ignore (appends to defaults). Default: ['ActionController::RoutingError', 'AbstractController::ActionNotFound', 'ActionController::MethodNotAllowed', 'ActionController::UnknownHttpMethod', 'ActionController::NotImplemented', 'ActionController::UnknownFormat', 'ActionController::InvalidAuthenticityToken', 'ActionController::InvalidCrossOriginRequest', 'ActionDispatch::ParamsParser::ParseError', 'ActionController::BadRequest', 'ActionController::ParameterMissing', 'ActiveRecord::RecordNotFound', 'ActionController::UnknownAction', 'CGI::Session::CookieStore::TamperedWithCookie', 'Mongoid::Errors::DocumentNotFound', 'Sinatra::NotFound']
`exceptions.ignore_only`	Array	A list of exception class names to ignore (overrides defaults). Default: `[]`
`exceptions.ignored_user_agents`	Array	A list of user agents to ignore. Default: `[]`
`exceptions.rescue_rake`	Boolean	Enable rescuing exceptions in rake tasks. Default: `true` when run in background; `false` when run in terminal.
`exceptions.notify_at_exit`	Boolean	Report unhandled exception when Ruby crashes (at_exit). Default: `true`.
`exceptions.source_radius`	Integer	The number of lines before and after the source when reporting snippets. Default: `2`
`exceptions.local_variables`	Boolean	Enable sending local variables. Requires the binding_of_caller gem. Default: `false`
`exceptions.unwrap`	Boolean	Reports #original_exception or #cause one level up from rescued exception when available. Default: `false`

BREADCRUMBS
`breadcrumbs.enabled`	Boolean	Enable breadcrumb functionality. Default: `true`
`breadcrumbs.active_support_notifications`	Hash	Configuration for automatic Active Support Instrumentation events. Default: `Breadcrumbs::ActiveSupport.default_notifications`
`breadcrumbs.logging.enabled`	Boolean	Enable/Disable automatic breadcrumbs from log messages. Default: `true`
ACTIVE JOB
`active_job.attempt_threshold`	Integer	The number of attempts before notifications will be sent. Default: `0`
`active_job.insights.enabled`	Boolean	Enable automatic Insights instrumentation for this plugin. Default: `true`
SIDEKIQ
`sidekiq.attempt_threshold`	Integer	The number of attempts before notifications will be sent. Default: `0`
`sidekiq.use_component`	Boolean	Automatically set the component to the class of the job. Helps with grouping. Default: `true`
`sidekiq.insights.enabled`	Boolean	Enable automatic Insights instrumentation for Sidekiq. Default: `true`
`sidekiq.insights.collection_interval`	Integer	The frequency, in seconds, in which Sidekiq metrics are sampled. Default: `60`
`sidekiq.insights.cluster_collection`	Boolean	Enable cluster wide metric collection. If you are using Sidekiq Enterprise, this is configured automatically. Default: `true`
`sidekiq.insights.events`	Boolean	Enable sending Sidekiq events to Insights. Default: `true`
`sidekiq.insights.metrics`	Boolean	Enable sending Sidekiq metrics to Insights. Default: `false`
SOLID_QUEUE
`solid_queue.insights.enabled`	Boolean	Enable automatic Insights instrumentation for SolidQueue. Default: `true`
`solid_queue.insights.collection_interval`	Integer	The frequency, in seconds, in which SolidQueue metrics are sampled. Default: `60`
`solid_queue.insights.cluster_collection`	Boolean	Enable cluster wide metric collection. Default: `true`
DELAYED JOB
`delayed_job.attempt_threshold`	Integer	The number of attempts before notifications will be sent. Default: `0`
SHORYUKEN
`shoryuken.attempt_threshold`	Integer	The number of attempts before notifications will be sent. Default: `0`
SINATRA
`sinatra.enabled`	Boolean	Enable Sinatra auto-initialization. Default: `true`
RAILS
`rails.subscriber_ignore_sources`	Array	`source`s (strings or regexes) that should be ignored when using the Rails error reporter. Default: `[]`
`rails.insights.enabled`	Boolean	Enable automatic Insights instrumentation for Rails. Default: `true`
`rails.insights.events`	Boolean	Enable sending Rails events to Insights. Default: `true`
`rails.insights.metrics`	Boolean	Enable sending Rails metrics to Insights. Default: `false`
Autotuner
`autotuner.insights.enabled`	Boolean	Enable automatic Insights data collection for Autotuner. Default: `true`
Karafka
`karafka.insights.enabled`	Boolean	Enable automatic Insights instrumentation for Karafka. Default: `true`
`karafka.insights.events`	Boolean	Enable sending Karafka events to Insights. Default: `true`
`karafka.insights.metrics`	Boolean	Enable sending Karafka metrics to Insights. Default: `false`
Net::HTTP
`net_http.insights.enabled`	Boolean	Enable automatic Insights instrumentation for `Net::HTTP`. Default: `true`
`net_http.insights.full_url`	Boolean	Log the request URL instead of just the domain. Default: `false`
`net_http.insights.events`	Boolean	Enable sending Net::HTTP events to Insights. Default: `true`
`net_http.insights.metrics`	Boolean	Enable sending Net::HTTP metrics to Insights. Default: `false`