Rails integration guide

Typical installation time: 2 minutes

Hi there! You’ve found Honeybadger’s guide to Ruby on Rails exception and error tracking. Once installed, Honeybadger will automatically report exceptions wherever they may happen:

• During a web request
• In a background job
• In a rake task
• When a process crashes (at_exit)

If you’re new to Honeybadger, read our Getting Started guide to become familiar with our Ruby gem. For a refresher on working with exceptions in Ruby, check out the Honeybadger guide to Ruby exceptions.

Installation

The first step is to add the honeybadger gem to your Gemfile:

gem 'honeybadger'

Tell bundler to install:

bundle install

Next, you'll set the API key for this project.

bundle exec honeybadger install [Your project API key]

This will do three things:

1. Generate a config/honeybadger.yml file. If you don't like config files, you can place your API key in the $HONEYBADGER_API_KEY environment variable.
2. If Capistrano is installed, we'll add a require statement to Capfile.
3. Send a test exception to your Honeybadger project.

Assuming the test completed successfully: you’re done!

Identifying users

If you’re using the devise or the warden gems for user authentication, then we already associate errors with the current user.

For other authentication systems (or to customize the user values), add the following before_action to your ApplicationController:

before_action do
  Honeybadger.context({
    user_id: current_user.id,
    user_email: current_user.email
  })
end

Collecting user feedback

The Honeybadger gem has a few special tags that it looks for whenever you render an error page. These can be used to display extra information about the error, or to ask the user for information about how they triggered the error.

Displaying the error ID

When an error is sent to Honeybadger, our API returns a unique UUID for the occurrence within your project. This UUID can be automatically displayed for reference on error pages.

To include the error id, simply place this magic HTML comment on your error page (normally public/500.html in Rails):

<!-- HONEYBADGER ERROR -->

By default, we will replace this tag with:

Honeybadger Error {{error_id}}

Where {{error_id}} is the UUID. You can customize this output by overriding the user_informer.info option in your honeybadger.yml file (you can also enabled/disable the middleware):

config/honeybadger.yml

user_informer:
  enabled: true
  info: "Error ID: {{error_id}}"

You can use that UUID to load the error at the site by going to https://app.honeybadger.io/notice/some-uuid-goes-here.

Displaying a feedback form

When an error is sent to Honeybadger, an HTML form can be generated so users can fill out relevant information that led up to that error. Feedback responses are displayed inline in the comments section on the fault detail page.

To include a user feedback form on your error page, simply add this magic HTML comment (normally public/500.html in Rails):

<!-- HONEYBADGER FEEDBACK -->

You can change the text displayed in the form via the Rails internationalization system. Here’s an example:

config/locales/en.yml

en:
  honeybadger:
    feedback:
      heading: "Care to help us fix this?"
      explanation:
        "Any information you can provide will help us fix the problem."
      submit: "Send"
      thanks: "Thanks for the feedback!"
      labels:
        name: "Your name"
        email: "Your email address"
        comment: "Comment (required)"

The feedback form can be enabled and disabled using the feedback.enabled config option (defaults to true):

config/honeybadger.yml

feedback:
  enabled: true

The Rails error reporter

On Rails 7 and above, Honeybadger supports the new error reporter included in Rails. This means you can use Rails.error.handle as described in the Rails docs, and errors will be reported as normal, in line with your Honeybadger configuration. Rails.error.record is, however, not supported, since the Honeybadger native error handlers for each integration provide much richer context for your errors than Rails’ default.

On Rails 7.1 and above, each error report can include a source parameter. You can use the Honeybadger config option rails.subscriber_ignore_sources to automatically ignore errors from certain sources:

Honeybadger.configure do |config|
  config.rails.subscriber_ignore_sources += [/some_source/]
end

Content Security Policy reports

You can use Content Security Policy headers to help mitigate XSS attacks, and Rails has a DSL that you can use to configure those headers in your application. When a policy includes a report-uri or report-to directive, reports about blocked resources can be sent to a URL:

Rails.application.config.content_security_policy do |policy|
  policy.default_src :self, :https
  ...
  policy.report_uri -> { "https://api.honeybadger.io/v1/browser/csp?api_key=HB_API_KEY_GOES_HERE&report_only=true&env=#{Rails.env}&context[user_id]=#{respond_to?(:current_user) ? current_user&.id : nil}" }
end

Every parameter in the URL is optional, aside from the api_key parameter. If you don’t need the value to be generated at request time (as in this example, to report the current user’s id), then you can provide a simple string as the argument to report_uri. If you set the report_only parameter to true, then our UI will label reports as “CSP Report”; otherwise, they will be labeled as “CSP Error”.

CSP Reports and Errors show up with the rest of your app’s errors in the Honeybadger UI. For this reason, and since CSP reports can be very numerous, we recommend you create a separate Honeybadger project specifically for CSP reports.

If you use config.exceptions_app

If you use the config.exceptions_app Rails setting to display a custom error page, you may need some extra config for the correct controller and action name to be displayed in Honeybadger. The following snippet assumes that the name of your custom controller is “errors” (e.g. ErrorsController):

Honeybadger.configure do |config|
  config.before_notify do |notice|
    # Change "errors" to match your custom controller name.
    break if notice.component != "errors"

    # Look up original route path and override controller/action
    # in Honeybadger.
    params = Rails.application.routes.recognize_path(notice.url)
    notice.component = params[:controller]
    notice.action = params[:action]
  end
end

JavaScript source maps with esbuild and Sprockets

If you’re using esbuild with Sprockets, you can generate source maps for your JavaScript assets and upload them to Honeybadger. This will allow Honeybadger to display the original source code for your minified JavaScript files. Here’s a Rake Task that uploads source maps to Honeybadger via the assets:precompile step.