API Reference

This is the public ruby API documentation for the honeybadger ruby gem. Check out the Getting Started guide for additional examples and discussion on the methods listed here.

Public methods

Honeybadger.notify(error, opts = {})

Send an exception to Honeybadger. Does not report ignored exceptions by default.

Examples:

# With an exception:
begin
  fail 'badgers!'
rescue => exception
  Honeybadger.notify(exception, context: {
    my_data: 'value'
  }) # => '-1dfb92ae-9b01-42e9-9c13-31205b70744a'
end

# Custom notification:
Honeybadger.notify('Something went wrong.', {
  error_class: 'MyClass',
  context: {my_data: 'value'}
}) # => '06220c5a-b471-41e5-baeb-de247da45a56'

Parameters:

Parameter Description Default
error One of: an Exception object, a String error message, or a Hash of options which is used to build the notice. required
opts The options Hash when the first argument is an Exception {}
Options Hash (opts):
Option Description Default
:error_message The String error message. nil
:error_class The String class name of the error. "Notice"
:backtrace The Array backtrace of the error. nil
:fingerprint The String grouping fingerprint of the exception. nil
:force Always report the exception when true, even when ignored. false
:tags The String comma-separated list of tags. nil
:context The Hash context to associate with the exception. nil
:controller The String controller name (such as a Rails controller). nil
:action The String action name (such as a Rails controller action). nil
:parameters The Hash HTTP request paramaters. nil
:session The Hash HTTP request session. nil
:url The String HTTP request URL. nil

Returns:

  • a String UUID reference to the notice in Honeybadger or false when ignored.

Honeybadger.context(hash = nil)

Add metadata to all errors reported in current thread.

Examples:

# Set the global thread context:
Honeybadger.context({my_data: 'my value'})

# Clearing global thread context:
Honeybadger.context.clear!

Parameters:

Parameter Description Default
hash A Hash of data which will be sent to Honeybadger when an error occurs; can include any key/value, but a few keys have a special meaning in Honeybadger (default: nil): nil
Options Hash (hash):
Option Description Default
:user_id The String user ID used by Honeybadger to aggregate user data across occurrences on the error page. nil
:user_email Same as :user_id, but for email addresses nil
:tags A String comma-separated list of tags. When present, tags will be applied to errors with this context. nil

Returns:

  • object responding to #clear! (clears the global context)

Honeybadger.exception_filter

Callback to ignore exceptions.

Examples:

# Ignoring based on error message:
Honeybadger.exception_filter do |notice|
  notice[:error_message] =~ /sensitive data/
end

# Ignore an entire class of exceptions:
Honeybadger.exception_filter do |notice|
  notice[:exception].class < MyError
end

See Notice properties for available properties for notice.

Properties:

Parameter Description Default
block A block returning TrueClass true (to ignore) or FalseClass false (to send). nil

Returns:

  • no return value.

Honeybadger.exception_fingerprint

Callback to add a custom grouping strategy for exceptions. The return value is hashed and sent to Honeybadger. Errors with the same fingerprint will be grouped.

Examples:

Honeybadger.exception_fingerprint do |notice|
  [notice[:error_class], notice[:component], notice[:backtrace].to_s].join(':')
end

See Notice Properties for available properties for notice.

Properties:

Parameter Description Default
block A block returning TrueClass true (to ignore) or FalseClass false (to send). nil

Returns:

  • no return value.

Honeybadger.flush

Flushes all data from workers before returning. This is most useful in tests when using the test backend, where normally the asynchronous nature of this library could create race conditions.

Examples:

# Without a block:
it "sends a notification to Honeybadger" do
  expect {
    Honeybadger.notify(StandardError.new('test backend'))
    Honeybadger.flush
  }.to change(Honeybadger::Backend::Test.notifications[:notices], :size).by(0)
end

# With a block:
it "sends a notification to Honeybadger" do
  expect {
    Honeybadger.flush do
      49.times do
        Honeybadger.notify(StandardError.new('test backend'))
      end
    end
  }.to change(Honeybadger::Backend::Test.notifications[:notices], :size).by(49)
end

Properties:

Parameter Description Default
block The optional block to execute (exceptions will propagate after data is flushed). nil

Returns:

  • value of block if block is given, otherwise true.

Honeybadger.backtrace_filter

Callback to filter backtrace lines. One use for this is to make additional [PROJECT_ROOT] or [GEM_ROOT] substitutions, which are used by Honeybadger when grouping errors and displaying application traces.

Examples:

Honeybadger.backtrace_filter do |line|
  line.gsub(/^\/my\/unknown\/bundle\/path/, "[GEM_ROOT]")
end

Properties:

Parameter Description Default
block A block which can be used to modify the Backtrace lines sent to Honeybadger. The block expects one argument (line) which is the String line from the Backtrace, and must return the String new line. nil

Returns:

  • no return value.

Notice Properties

The Notice object is the block argument to the Honeybadger.exception_filter, Honeybadger.exception_fingerprint and the Honeybadger.backtrace_filter callback methods.

notice.backtrace

The backtrace from the given exception or hash.

notice.fingerprint

Custom fingerprint for error, used to group similar errors together.

notice.tags

Tags which will be applied to error.

notice.error_class

The name of the class of error (example: RuntimeError).

notice.error_message

The message from the exception, or a general description of the error.

notice.cgi_data

CGI variables such as HTTP_METHOD.

notice.params

A hash of parameters from the query string or post body.

notice.component

The component (if any) which was used in this request (usually the controller).

notice.action

The action (if any) that was called in this request.

notice.session

A hash of session data from the request.

notice.url

The URL at which the error occurred (if any).

notice.api_key

The API key used to deliver this notice.

notice.exception

The exception that caused this notice, if any.

notice.id

The unique ID of this notice which can be used to reference the error in Honeybadger.

notice.local_variables

Local variables are extracted from first frame of backtrace.