Adding context to errors

Sometimes, default exception data just isn’t enough. If you have extra data that will help you in debugging, send it as part of an error’s context. Context is what you’re looking for if:

• You want to record the current user’s id or email address at the time of an exception
• You need to send raw POST data for use in debugging
• You have any other metadata you’d like to send with an exception

Honeybadger supports two types of context: global and local.

Global context

Global context is automatically reported with any exception which occurs after the context has been created:

Honeybadger.context({
  my_data: 'my value'
})

A few other methods are also available when working with context:

# Clear the global context:
Honeybadger.context.clear!

# Fetch the global context:
Honeybadger.get_context

Global context is stored in a thread-local variable, which means each thread has its own global context.

Local context

Local context is similar to global context but it is only reported with exceptions that occur within a specific block of code where the local context is set. This is useful when you want to add context data for a specific operation or a set of operations, but you don’t want that context to leak into other parts of your application.

You can set local context by passing a block to the Honeybadger.context method:

Honeybadger.context({ local_data: 'local value' }) do
  # This block of code has access to the local context.
  # If an exception occurs here, the local context will be reported with the exception.
end

The local context is automatically cleared after the block is executed, even if an exception is raised within the block. This ensures that the local context does not leak into other parts of your application.

To fetch the local context, you can call Honeybadger.get_context:

# Set global context
Honeybadger.context({ global_data: 'global value' })

# Fetch and print global context
puts Honeybadger.get_context
# Expected output: { global_data: 'global value' }

# Set local context within a block
Honeybadger.context({ local_data: 'local value' }) do
  # Fetch and print context within the block
  puts Honeybadger.get_context
  # Expected output: { global_data: 'global value', local_data: 'local value' }
end

# Fetch and print context outside the block
puts Honeybadger.get_context
# Expected output: { global_data: 'global value' }

Calling Honeybadger.get_context within a block will return a merged hash of the global and local context. If there are conflicts, the local context will take precedence.

Remember, local context is also stored in a thread-local variable, which means each thread has its own local context.

Context in Honeybadger.notify

You can also add context to a manual error report using the :context option, like this:

Honeybadger.notify(exception, context: {
  my_data: 'my local value'
})

Local context always overrides any global values when the error is reported.

Special context values

While you can add any key/value data to context, a few keys have special meaning in Honeybadger:

Option	Description
:_action	This will set the action attribute of your error data if not already set.
:_component	This will set the component attribute of your error data if not already set.
:user_id	The String user ID used by Honeybadger to aggregate user data across occurrences on the error page.
:user_email	Same as :user_id, but for email addresses
:tags	A String comma-separated list of tags. When present, tags will be applied to errors with this context.

Using the :_action and :_component keys are useful when you are manually reporting errors via Honeybadger.notify or Rails.error.report.

Defining context on objects

Context must either be a Hash, or it must define the method #to_honeybadger_context to return a Hash. For example, to pass a User instance to Honeybadger.context:

class User < ApplicationRecord
  def to_honeybadger_context
    { user_id: id, user_email: email }
  end
end

user = User.last

Honeybadger.context(user)

When the #to_honeybadger_context method is defined on an Exception class, the context will be automatically added when the exception is reported:

class CustomError < StandardError
  def to_honeybadger_context
    { tags: 'custom' }
  end
end

raise CustomError, 'This error will be reported with context'

Limits

Honeybadger uses the following limits to ensure the service operates smoothly for everyone:

• Nested objects have a max depth of 20
• Context values have a max size of 64Kb

When an error notification includes context data that exceed these limits, the context data will be truncated, and the notification will still be processed.