Rack Exception & Error Tracking

Typical installation time: 4 minutes

Hi there! You've found Honeybadger's guide to Rack 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.

On this page:

Installation
Identifying Users
Collecting User Feedback

Installation

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

ruby

gem 'honeybadger'

Tell bundler to install:

bash

bundle install

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

bash

bundle exec honeybadger install [Your project API key]

This will do three things:

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

Now it's time to set up your Rack app. Start by requiring the honeybadger gem after any other gems you're using:

ruby

require 'rack'
# ...
require 'honeybadger'

Then add the middleware to your app. Make sure Honeybadger's middleware is the first middleware you define so that it can catch exceptions in your other middleware:

ruby

use Honeybadger::Rack::ErrorNotifier
# ...

Example app

ruby

  

require 'rack'

# Load the gem
require 'honeybadger'

# Write your app
app = Rack::Builder.app do
  run lambda { |env| raise "Rack down" }
end

# These middleware are optional, but for them to work, 
# they must be placed *before* the ErrorNotifier middleware
use Honeybadger::Rack::UserFeedback
use Honeybadger::Rack::UserInformer

# Use Honeybadger's Rack middleware
use Honeybadger::Rack::ErrorNotifier

# Use your other middleware here

run app

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), use Honeybadger.context to associate the current user:

ruby

  

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

Collecting User Feedback

The Honeybadger gem has a few special tags that it looks for whenever you render an error page in a Rack-based application. These can be used to display extra information about the error, or to ask the user for information about how they triggered the error. You can enable them by adding the middleware to your application:

ruby

  

use Honeybadger::Rack::UserInformer
use Honeybadger::Rack::UserFeedback
# ^^^ These middleware must be placed *before* the ErrorNotifier
use Honeybadger::Rack::ErrorNotifier

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

html

<!-- 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):

yaml

# 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):

html

<!-- HONEYBADGER FEEDBACK -->

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

yaml

# 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):

yaml

# config/honeybadger.yml
feedback:
  enabled: true