What's New in the Honeybadger Gem v3

TLDR: For just the bullet points, check out the CHANGELOG.

I recently shipped the latest major update to our gem for reporting exceptions in Ruby. While the v2 release was a full re-write that included a new configuration strategy, v3 contains fewer breaking changes but a lot of feature and usability improvements. There's a lot to cover, so I'm going to dive right in. Enjoy!

Plain ol' Ruby mode

In the Rails world it's pretty much expected that when you install a gem it's going to automatically integrate with your application. For instance, many gems provide their own Railtie to run their own code when Rails initializes.

The honeybadger gem fully embraces that approach, making it really easy to set up comprehensive error reporting for Rails, Sinatra, Sidekiq, and a number of other popular gems and frameworks. It's literally as simple as require 'honeybadger'.

Some Rubyists prefer to roll their own integrations, however. Monkey patching (which happens a lot in Rails) makes them rage, and the last thing they want is for a gem to change their application in less-than-obvious ways by simply requiring it. I completely get that (in fact, I tend towards that mindset myself).

Others may not be using any of the libraries we integrate with and would rather report errors themselves using Honeybadger.notify, avoiding unnecessary initialization at runtime.

That's why I added "Plain ol' Ruby" mode (unofficial title). If you're one of us weirdos who enjoy writing configuration and installing middleware from scratch (or you're just using plain Ruby), you can now require 'honeybadger/ruby' instead of the normal require 'honeybadger'. Now you can use Honeybadger.notify, Honeybadger.context, etc. without any of the automatic integrations being activated: it's minimal, predictable error tracking for Ruby:

require 'honeybadger/ruby'

begin
  # Failing code
rescue => exception
  Honeybadger.notify(exception)
end

Multiple agents

Speaking of plain ol' Ruby, you can now use Ruby to create additional agents, which are what reports errors to your Honeybadger project. This means that you can finally report errors to multiple Honeybadger projects in the same application. Here's what it looks like:

OtherBadger = Honeybadger::Agent.new

OtherBadger.configure do |config|
  config.api_key = 'project api key'
end

begin
  # Failing code
rescue => exception
  OtherBadger.notify(exception)
end

The return of Honeybadger.configure

First of all, if you use honeybadger.yml to configure the gem currently, don't worry -- nothing has changed, and it's still the default!

That said, we've had customers who missed the ability to configure the gem programmatically from Ruby. In v3.0 you get the best of both worlds: we still support full configuration via honeybadger.yml and environment variables and have added back Honeybadger.configure:

Honeybadger.configure do |config|
  config.api_key = 'project api key'
  config.exceptions.ignore += [CustomError]
end

The priority for configuration is YAML -> ENV -> Ruby, meaning that environment variables will override honeybadger.yml, and Honeybadger.configure will override environment variables.

Report errors in cron jobs and command line programs

One of cron's long-standing problems is that its automatic email feature doesn't understand error output. Sure, it will email you if a task fails, but it will also email you when your successful tasks happen to generate standard output.

Hey, don't you use Honeybadger to get fewer unactionable email alerts? Wouldn't it be cool if you could use Honeybadger to report cron failures instead of or in addition to email? Now you can.

We added the honeybadger exec command to our CLI (Command Line Interface) to handle reporting cron failures as well as any command that you normally execute via the command line. That means bash scripts, executables, make tasks, etc. To use it, just add honeybadger exec before any command:

$ honeybadger exec my-command --my-flag

If the command executes successfully it will exit with code 0 and no output (even standard out is disabled by default, but you can enable it with a special flag). If the command fails, however, you'll receive a Honeybadger notification which includes the command that was run and the full output.

Because honeybadger exec silences all output by default for successful commands, it's particularly useful with cron's email feature. By using both honeybadger exec and cron emails you'll get Honeybadger notifications when a command fails; if for some reason the Honeybadger notification also fails (due to a connection issue, for instance), it will dump the output from the original command and cron will still email you about the failure.

Report custom errors from the command line

This one's pretty simple. Want to send a custom Honeybadger notification from a bash script (or any shell)? Use honeybadger notify:

$ honeybadger notify --message "This is an error from the command line"

You can use optional flags like --class, --component, --action, etc. to add additional properties to the notification.

Other improvements

We added even more features and improvements in v3:

• Honeybadger.notify now accepts a string argument in addition to an exception, so you can do Honeybadger.notify("these are not the badgers you're looking for").
• When inside a git repository, the git revision is automatically reported with exceptions. The revision can be added or changed manually with the new :revision config option.
• The CLI's user interface is now much friendlier with verbose error messages, and it may be used as a standalone executable (outside of Rails).
• The test suite is about 10 times faster, meaning we can develop even more new features and integrations faster.
• The request data filter now uses a wildcard match strategy by default. So if you filter "password", the "password" and "password_confirmation" request parameters will both be filtered (this is how Rails filters work).

Changes and removals

We've also made some changes and removed some features which didn't make sense anymore:

• We dropped support for Ruby 1.9.3 and 2.0.x; moving forward 2.1.0 will be the lowest officially supported version.
• We've removed all deprecations from v2.
• The deprecated metrics and tracing code has been removed.
• Honeybadger.start is no longer necessary (and will raise an exception if used). If you previously used Honeybadger outside of Rails, you can use Honeybadger.configure to configure the agent without creating a separate Honeybadger::Config instance or calling Honeybadger.start.
• We renamed the plugins.skip option to skipped_pluggins and sidekiq.use_component is now true by default.
• CGI variables are now whitelisted so that it's harder to leak sensitive data by accident.
• In development, the Honeybadger.notify method now raises an exception when called without valid arguments. In production it logs the error.
• Errors when evaluating honeybadger.yml are now raised instead of logged, helping to identify configuration problems earlier. Backtraces for errors inside ERB tags have also been improved to make the errors easier to debug.