Upgrading the ruby gem from 1.x to 2.x

Upgrading to the new Ruby gem

2.0 of our Ruby gem is here! If you're not using Honeybadger yet, then check out our  installation instructions to get up and running. If you're currently running 1.x of the gem, then this article is for you.

Why should I upgrade?

Simply put the new gem is: harder, better, faster, stronger. Not convinced? Then check it:

  • It's way faster; all data is now sent asynchronously by default.

  • Way better performance: we've tuned object allocation, profiled the memory footprint, and oiled the hinges (except there are no hinges -- just pure elegance). Don't believe us? Under MRI Ruby 2.1, sending 1000 error reports now allocates around 1.2 million less objects than it used to.

  • Better configuration with full support for ENV variables in addition to a new honeybadger.yml file (no more initializers).

How long will this take?

For most projects, it should take around  5-10 minutes  to upgrade your gem and convert the configuration. While Honeybadger 1.x and 2.x maintain largely the same public API, the configuration has changed significantly. If you have made a lot of changes to your current config/initializers/honeybadger.rb file, you'll need to translate that configuration to the new format.

Let's get started

First, let's update the actual Honeybadger gem. Lock  honeybadger _to version ~> 2.0.0 i_n your Gemfile_:_

gem 'honeybadger', '~> 2.0.0'

Next, run bundle update to update your Gemfile.lock:

bundle update honeybadger

Now for the fun part: backup/delete your honeybadger.rb initializer and run the new installer. First, we'll start by moving the old initializer so that we can reference it later (skip this step if you don't have one). From your project root:

mv config/initializers/honeybadger.rb old_honeybadger_initializer.rb

It's time to run the new installer! Grab your api_key from old_honeybadger_initializer.rb, or find it on your project settings page. Then run (replacing [api_key] with your real API key):

bundle exec honeybadger install [api_key]
# Or, if you're on Heroku:
bundle exec honeybadger heroku install [api_key]

For non-Heroku users, this should have created a new file at config/honeybadger.yml (_Heroku uses ENV for configuration instead). In either case you should see a new test error notification in your Honeybadger project. Note: _If you don't see a test notification for some reason, contact us and we'll help you finish the upgrade.

If all you had in your initializer was an API key, then congrats, you're done! (Don't forget to rm old_honeybadger_initializer.rb if you created that file.) Celebrate by checking out some of the other helpful CLI commands by running bundle exec honeybadger -h, and  read about the new configuration options.

If you have some configuration left to transfer, please note that the configuration options may be slightly different, and you also have the option of using ENV variables instead of the YAML file (if you're on Heroku, for example).  Go read about the new configuration options. As you change your settings, you may want to send some additional test notifications. We've got you covered! Just run:

bundle exec honeybadger test

If you have difficulty with any part of this guide, we're here to help.

Lastly, we want your feedback. if you find a bug, the new gem is missing a feature, or even if you think it sucks, please  let us know about it. Badgers are standing by!