Class: Honeybadger::Agent

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Includes:
Logging::Helper
Defined in:
lib/honeybadger/agent.rb

Overview

The Honeybadger agent contains all the methods for interacting with the Honeybadger service. It can be used to send notifications to multiple projects in large apps. The global agent instance (Agent.instance) should always be accessed through the Honeybadger singleton.

Context

Context is global by default, meaning agents created via Honeybadger::Agent.new will share context (added via Honeybadger.context or #context) with other agents. This also includes the Rack environment when using the Rack::ErrorNotifier middleware. To localize context for a custom agent, use the local_context: true option when initializing.

Examples:


# Standard usage:
OtherBadger = Honeybadger::Agent.new

# With local context:
OtherBadger = Honeybadger::Agent.new(local_context: true)

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

begin
  # Risky operation
rescue => e
  OtherBadger.notify(e)
end

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(opts = {}) ⇒ Agent

Returns a new instance of Agent



58
59
60
61
62
63
64
65
66
67
68
69
70
# File 'lib/honeybadger/agent.rb', line 58

def initialize(opts = {})
  if opts.kind_of?(Config)
    @config = opts
    opts = {}
  end

  @context = opts.delete(:context)
  @context ||= ContextManager.new if opts.delete(:local_context)

  @config ||= Config.new(opts)

  init_worker
end

Instance Attribute Details

#configObject (readonly)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.



272
273
274
# File 'lib/honeybadger/agent.rb', line 272

def config
  @config
end

#workerObject (readonly)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.



343
344
345
# File 'lib/honeybadger/agent.rb', line 343

def worker
  @worker
end

Class Method Details

.instanceObject

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.



49
50
51
# File 'lib/honeybadger/agent.rb', line 49

def self.instance
  @instance
end

.instance=(instance) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.



54
55
56
# File 'lib/honeybadger/agent.rb', line 54

def self.instance=(instance)
  @instance = instance
end

Instance Method Details

#backendObject

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

See Also:



353
# File 'lib/honeybadger/agent.rb', line 353

def_delegators :config, :backend

#backtrace_filter {|line| ... } ⇒ Object

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

Yield Parameters:

  • line (String)

    The backtrace line to modify.

Yield Returns:

  • (String)

    The new (modified) backtrace line.



332
# File 'lib/honeybadger/agent.rb', line 332

def_delegator :config, :backtrace_filter

#check_in(id) ⇒ Boolean

Perform a synchronous check_in.

Examples:

Honeybadger.check_in('1MqIo1')

Parameters:

  • id (String)

    The unique check in id (e.g. '1MqIo1') or the check in url.

Returns:

  • (Boolean)

    true if the check in was successful and false otherwise.



160
161
162
163
164
165
# File 'lib/honeybadger/agent.rb', line 160

def check_in(id)
  # this is to allow check ins even if a url is passed
  check_in_id = id.to_s.strip.gsub(/\/$/, '').split('/').last
  response = backend.check_in(check_in_id)
  response.success?
end

#clear!Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Used to clear context via `#context.clear!`.



211
212
213
# File 'lib/honeybadger/agent.rb', line 211

def clear! # :nodoc:
  context_manager.clear!
end

#configure {|Config::Ruby| ... } ⇒ Object

Configure the Honeybadger agent via Ruby.

Examples:

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

Yields:



284
# File 'lib/honeybadger/agent.rb', line 284

def_delegator :config, :configure

#context(context = nil) ⇒ self

Save global context for the current request.

Examples:

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

# Inside a Rails controller:
before_action do
  Honeybadger.context({user_id: current_user.id})
end

# Explicit conversion
class User < ActiveRecord::Base
  def to_honeybadger_context
    { user_id: id, user_email: email }
  end
end

user = User.first
Honeybadger.context(user)

# Clearing global context:
Honeybadger.context.clear!

Parameters:

  • context (Hash) (defaults to: nil)

    A Hash of data which will be sent to Honeybadger when an error occurs. If the object responds to #to_honeybadger_context, the return value of that method will be used (explicit conversion). Can include any key/value, but a few keys have a special meaning in Honeybadger.

Options Hash (context):

  • :user_id (String)

    The user ID used by Honeybadger to aggregate user data across occurrences on the error page (optional).

  • :user_email (String)

    The user email address (optional).

  • :tags (String)

    The comma-separated list of tags. When present, tags will be applied to errors with this context (optional).

Returns:

  • (self)

    so that method calls can be chained.



204
205
206
207
# File 'lib/honeybadger/agent.rb', line 204

def context(context = nil)
  context_manager.set_context(context) unless context.nil?
  self
end

#exception_filterObject

Callback to ignore exceptions.

See public API documentation for Notice for available attributes.

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

Yield Returns:

  • (Boolean)

    true (to ignore) or false (to send).



303
# File 'lib/honeybadger/agent.rb', line 303

def_delegator :config, :exception_filter

#exception_fingerprintObject

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.

See public API documentation for Notice for available attributes.

Examples:

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

Yield Returns:

  • (#to_s)

    The fingerprint of the error.



318
# File 'lib/honeybadger/agent.rb', line 318

def_delegator :config, :exception_fingerprint

#flush { ... } ⇒ Object, Boolean

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

Yields:

  • An optional block to execute (exceptions will propagate after data is flushed).

Returns:

  • (Object, Boolean)

    value of block if block is given, otherwise true on success or false if Honeybadger isn't running.



255
256
257
258
259
260
# File 'lib/honeybadger/agent.rb', line 255

def flush
  return true unless block_given?
  yield
ensure
  worker.flush
end

#get_contextHash?

Get global context for the current request.

Examples:

Honeybadger.context({my_data: 'my value'})
Honeybadger.get_context # => {my_data: 'my value'}

Returns:

  • (Hash, nil)


222
223
224
# File 'lib/honeybadger/agent.rb', line 222

def get_context
  context_manager.get_context
end

#init!(...) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

See Also:



348
# File 'lib/honeybadger/agent.rb', line 348

def_delegators :config, :init!

#notify(exception_or_opts, opts = {}) ⇒ String, false

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

Examples:

# With an exception:
begin
  fail 'oops'
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:

  • exception_or_opts (Exception, Hash, Object)

    An Exception object, or a Hash of options which is used to build the notice. All other types of objects will be converted to a String and used as the :error_message.

  • opts (Hash) (defaults to: {})

    The options Hash when the first argument is an Exception.

Options Hash (opts):

  • :error_message (String)

    The error message.

  • :error_class (String) — default: 'Notice'

    The class name of the error.

  • :backtrace (Array)

    The backtrace of the error (optional).

  • :fingerprint (String)

    The grouping fingerprint of the exception (optional).

  • :force (Boolean) — default: false

    Always report the exception when true, even when ignored (optional).

  • :tags (String)

    The comma-separated list of tags (optional).

  • :context (Hash)

    The context to associate with the exception (optional).

  • :controller (String)

    The controller name (such as a Rails controller) (optional).

  • :action (String)

    The action name (such as a Rails controller action) (optional).

  • :parameters (Hash)

    The HTTP request paramaters (optional).

  • :session (Hash)

    The HTTP request session (optional).

  • :url (String)

    The HTTP request URL (optional).

  • :cause (Exception)

    The cause for this error (optional).

Returns:

  • (String)

    UUID reference to the notice within Honeybadger.

  • (false)

    when ignored.



112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
# File 'lib/honeybadger/agent.rb', line 112

def notify(exception_or_opts, opts = {})
  return false if config.disabled?

  if exception_or_opts.is_a?(Exception)
    opts[:exception] = exception_or_opts
  elsif exception_or_opts.respond_to?(:to_hash)
    opts.merge!(exception_or_opts.to_hash)
  else
    opts[:error_message] = exception_or_opts.to_s
  end

  validate_notify_opts!(opts)

  opts[:rack_env] ||= context_manager.get_rack_env
  opts[:global_context] ||= context_manager.get_context

  notice = Notice.new(config, opts)

  unless notice.api_key =~ NOT_BLANK
    error { sprintf('Unable to send error report: API key is missing. id=%s', notice.id) }
    return false
  end

  if !opts[:force] && notice.ignore?
    debug { sprintf('ignore notice feature=notices id=%s', notice.id) }
    return false
  end

  info { sprintf('Reporting error id=%s', notice.id) }

  if opts[:sync]
    send_now(notice)
  else
    push(notice)
  end

  notice.id
end

#stop(force = false) ⇒ Object

Stops the Honeybadger service.

Examples:

Honeybadger.stop # => nil


266
267
268
269
# File 'lib/honeybadger/agent.rb', line 266

def stop(force = false)
  worker.send(force ? :shutdown! : :shutdown)
  true
end

#with_rack_env(rack_env, &block) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.



335
336
337
338
339
340
# File 'lib/honeybadger/agent.rb', line 335

def with_rack_env(rack_env, &block)
  context_manager.set_rack_env(rack_env)
  yield
ensure
  context_manager.set_rack_env(nil)
end