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

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.

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: []
 
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.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 Disable 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
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
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 sources (strings or regexes) that should be ignored when using the Rails error reporter.
Default: []