Skip to content
Honeybadger Docs

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:

Advanced Honeybadger Gem Usage

YAML configuration file

Section titled “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:

---
api_key: "PROJECT_API_KEY"

Nested options

Section titled “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:

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

Environments

Section titled “Environments”

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

---
api_key: "PROJECT_API_KEY"
production:
  logging:
    path: "/path/to/honeybadger.log"
    level: "WARN"

ERB and Regex

Section titled “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:

---
api_key: "PROJECT_API_KEY"
request:
  filter_keys:
    - !ruby/regexp "/credit_card/i"

Configuring with environment variables (12-factor style)

Section titled “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)

Section titled “Configuration via Ruby (programmatic)”

To configure Honeybadger from Ruby, use Honeybadger.configure:

# i.e. config/initializers/honeybadger.rb
Honeybadger.configure do |config|
  config.api_key = "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

Section titled “Changing notice data”

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

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

Section titled “Changing event data”

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

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

Section titled “Using a custom logger”

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

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

Using a custom backend

Section titled “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:

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

Configuration options

Section titled “Configuration options”

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

OptionTypeDescription
api_keyStringThe API key for your Honeybadger project.
Default: nil
envStringThe environment the app is running in. In Rails this defaults to Rails.env.
Default: nil
report_dataBooleanEnable/disable reporting of data. Defaults to false for “test”, “development”, and “cucumber” environments.
Default: true
rootStringThe project’s absolute root path.
Default: Dir.pwd
revisionStringThe project’s git revision.
Default: revision detected from git
hostnameStringThe hostname of the current box.
Default: Socket.gethostname
backendStringAn alternate backend to use for reporting data.
Default: nil
debugBooleanEnables verbose debug logging.
Default: false
send_data_at_exitBooleanPrevent 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_sizeIntegerMaximum number of notices to queue for delivery at one time; new notices will be dropped if this number is exceeded.
Default: 100
config_pathStringThe path of the honeybadger config file. Can only be set via the $HONEYBADGER_CONFIG_PATH environment variable
development_environmentsArrayEnvironments which will not report data by default (use reportdata to enable/disable explicitly).
_Default: ["development", "test", "cucumber"]
pluginsArrayAn optional list of plugins to load. Default is to load all plugins.
Default: []
skipped_pluginsArrayAn optional list of plugins to skip.
Default: []
 
INSIGHTS AND EVENTS
insights.enabledBooleanEnable automatic Insights instrumentation.
Default: false
insights.registry_flush_intervalIntegerNumber of seconds to flush the aggregated metrics registry. Set a higher number for greater resolution but use more data.
Default: 60
events.max_queue_sizeIntegerNumber of events before the event queue will start dropping events.
Default: 100000
events.batch_sizeIntegerNumber of events to batch that will trigger the gem to send.
Default: 1000
events.timeoutIntegerNumber of milliseconds before the event queue will send events regardless of size.
Default: 30000
events.attach_hostnameBooleanAttach server hostname to every event sent by the gem.
Default: true
events.ignoreArrayAn list of rules to match against events to be ignored. See Ignoring Events for more information.
events.sample_rateIntegerPercentage of events to send. See Sampling Events for more information.
 
LOGGING
logging.pathStringThe 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.levelStringThe log level. Does nothing unless logging.path is also set.
Default: INFO
logging.tty_levelStringLevel to log when attached to a terminal (anything < logging.level will always be ignored).
Default: DEBUG
 
HTTP CONNECTION
connection.secureBooleanUse SSL when sending data.
Default: true
connection.hostStringThe host to use when sending data.
Default: api.honeybadger.io
connection.portIntegerThe port to use when sending data.
Default: 443
connection.http_open_timeoutIntegerThe HTTP open timeout when connecting to the server.
Default: 2
connection.http_read_timeoutIntegerThe HTTP read timeout when connecting to the server.
Default: 5
connection.proxy_hostStringThe proxy host to use when sending data.
Default: nil
connection.proxy_portIntegerThe proxy port to use when sending data.
Default: nil
connection.proxy_userStringThe proxy user to use when sending data.
Default: nil
connection.proxy_passStringThe proxy password to use when sending data.
Default: nil
 
REQUEST DATA FILTERING
request.filter_keysArrayA list of keys to filter when sending request data. In Rails, this also includes existing params filters.
Default: ['password', 'password_confirmation']
request.disable_sessionBooleanPrevent session from being sent with request data.
Default: false
request.disable_paramsBooleanPrevent params from being sent with request data.
Default: false
request.disable_environmentBooleanPrevent Rack environment from being sent with request data.
Default: false
request.disable_urlBooleanPrevent url from being sent with request data (Rack environment may still contain it in some cases).
Default: false
 
USER INFORMER
user_informer.enabledBooleanEnable 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.infoStringReplacement string for HTML comment in templates.
Default: 'Honeybadger Error {{error_id}}'
 
USER FEEDBACK
feedback.enabledBooleanEnable 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.enabledBooleanEnable error reporting functionality.
Default: true
exceptions.ignoreArrayA 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_onlyArrayA list of exception class names to ignore (overrides defaults).
Default: []
exceptions.ignored_user_agentsArrayA list of user agents to ignore.
Default: []
exceptions.rescue_rakeBooleanEnable rescuing exceptions in rake tasks.
Default: true when run in background; false when run in terminal.
exceptions.notify_at_exitBooleanReport unhandled exception when Ruby crashes (atexit).
_Default: true.
exceptions.source_radiusIntegerThe number of lines before and after the source when reporting snippets.
Default: 2
exceptions.local_variablesBooleanEnable sending local variables. Requires the binding_of_caller gem.
Default: false
exceptions.unwrapBooleanReports #originalexception or #cause one level up from rescued exception when available.
_Default: false
 
BREADCRUMBS
breadcrumbs.enabledBooleanEnable breadcrumb functionality.
Default: true
breadcrumbs.active_support_notificationsHashConfiguration for automatic Active Support Instrumentation events.
Default: Breadcrumbs::ActiveSupport.default_notifications
breadcrumbs.logging.enabledBooleanEnable/Disable automatic breadcrumbs from log messages.
Default: true
ACTIVE JOB
active_job.attempt_thresholdIntegerThe number of attempts before notifications will be sent.
Default: 0
active_job.insights.enabledBooleanEnable automatic Insights instrumentation for this plugin.
Default: true
SIDEKIQ
sidekiq.attempt_thresholdIntegerThe number of attempts before notifications will be sent.
Default: 0
sidekiq.use_componentBooleanAutomatically set the component to the class of the job. Helps with grouping.
Default: true
sidekiq.insights.enabledBooleanEnable automatic Insights instrumentation for Sidekiq.
Default: true
sidekiq.insights.collection_intervalIntegerThe frequency, in seconds, in which Sidekiq metrics are sampled.
Default: 60
sidekiq.insights.cluster_collectionBooleanEnable cluster wide metric collection. If you are using Sidekiq Enterprise, this is configured automatically.
Default: true
sidekiq.insights.eventsBooleanEnable sending Sidekiq events to Insights.
Default: true
sidekiq.insights.metricsBooleanEnable sending Sidekiq metrics to Insights.
Default: false
SOLID_QUEUE
solid_queue.insights.enabledBooleanEnable automatic Insights instrumentation for SolidQueue.
Default: true
solid_queue.insights.collection_intervalIntegerThe frequency, in seconds, in which SolidQueue metrics are sampled.
Default: 60
solid_queue.insights.cluster_collectionBooleanEnable cluster wide metric collection.
Default: true
DELAYED JOB
delayed_job.attempt_thresholdIntegerThe number of attempts before notifications will be sent.
Default: 0
SHORYUKEN
shoryuken.attempt_thresholdIntegerThe number of attempts before notifications will be sent.
Default: 0
SINATRA
sinatra.enabledBooleanEnable Sinatra auto-initialization.
Default: true
RAILS
rails.subscriber_ignore_sourcesArraysources (strings or regexes) that should be ignored when using the Rails error reporter.
Default: []
rails.insights.enabledBooleanEnable automatic Insights instrumentation for Rails.
Default: true
rails.insights.eventsBooleanEnable sending Rails events to Insights.
Default: true
rails.insights.metricsBooleanEnable sending Rails metrics to Insights.
Default: false
Autotuner
autotuner.insights.enabledBooleanEnable automatic Insights data collection for Autotuner.
Default: true
Karafka
karafka.insights.enabledBooleanEnable automatic Insights instrumentation for Karafka.
Default: true
karafka.insights.eventsBooleanEnable sending Karafka events to Insights.
Default: true
karafka.insights.metricsBooleanEnable sending Karafka metrics to Insights.
Default: false
Net::HTTP
net_http.insights.enabledBooleanEnable automatic Insights instrumentation for Net::HTTP.
Default: true
net_http.insights.full_urlBooleanLog the request URL instead of just the domain.
Default: false
net_http.insights.eventsBooleanEnable sending Net::HTTP events to Insights.
Default: true
net_http.insights.metricsBooleanEnable sending Net::HTTP metrics to Insights.
Default: false