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:

ruby

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

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

ruby

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

ruby

  

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:

ruby

  

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

ruby

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
`: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.

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:

ruby

  

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:

ruby

  

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.