Class: Honeybadger::Agent

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

Overview

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

Context is global by default, meaning agents created via `Honeybadger::Agent.new` will share context (added via `Honeybadger.context` or `Honeybadger::Agent#context`) with other agents. This also includes the Rack environment when using the Honeybadger rack middleware.

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



52
53
54
55
56
57
58
59
60
61
62
63
64
# File 'lib/honeybadger/agent.rb', line 52

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)

Returns the value of attribute config



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

def config
  @config
end

#workerObject (readonly)

Internal



370
371
372
# File 'lib/honeybadger/agent.rb', line 370

def worker
  @worker
end

Class Method Details

.instanceObject



44
45
46
# File 'lib/honeybadger/agent.rb', line 44

def self.instance
  @instance
end

.instance=(instance) ⇒ Object



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

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

Instance Method Details

#check_in(id) ⇒ Object

Public: Perform a synchronous check_in.

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

Examples

Honeybadger.check_in('1MqIo1')

Returns a boolean which is true if the check in was successful and false otherwise.



156
157
158
159
160
161
# File 'lib/honeybadger/agent.rb', line 156

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

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



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

def clear!
  context_manager.clear!
end

#context(context = nil) ⇒ Object

Public: Save global context for the current request.

context - 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 (default: nil):
:user_id    - The String user ID used by Honeybadger to aggregate
              user data across occurrences on the error page (optional).
:user_email - The String user email address (optional).
:tags       - The String comma-separated list of tags. When present,
              tags will be applied to errors with this context (optional).

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!

Returns self so that method calls can be chained.



199
200
201
202
# File 'lib/honeybadger/agent.rb', line 199

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

#flushObject

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

block - The optional block to execute (exceptions will propagate after data is flushed).

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

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



252
253
254
255
256
257
# File 'lib/honeybadger/agent.rb', line 252

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

#get_contextObject

Public: Get global context for the current request.

Examples

Honeybadger.context({my_data: 'my value'})
Honeybadger.get_context #now returns {my_data: 'my value'}

Returns hash or nil.



218
219
220
# File 'lib/honeybadger/agent.rb', line 218

def get_context
  context_manager.get_context
end

#notify(exception_or_opts, opts = {}) ⇒ Object

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

exception_or_opts - 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 - The options Hash when the first argument is an

Exception (default: {}):
:error_message - The String error message.
:error_class   - The String class name of the error (default: "Notice").
:backtrace     - The Array backtrace of the error (optional).
:fingerprint   - The String grouping fingerprint of the exception (optional).
:force         - Always report the exception when true, even when ignored (default: false).
:tags          - The String comma-separated list of tags (optional).
:context       - The Hash context to associate with the exception (optional).
:controller    - The String controller name (such as a Rails controller) (optional).
:action        - The String action name (such as a Rails controller action) (optional).
:parameters    - The Hash HTTP request paramaters (optional).
:session       - The Hash HTTP request session (optional).
:url           - The String HTTP request URL (optional).
:cause         - The Exception cause for this error (optional).

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'

Returns a String UUID reference to the notice within Honeybadger or false when ignored.



107
108
109
110
111
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
# File 'lib/honeybadger/agent.rb', line 107

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

  if exception_or_opts.is_a?(Exception)
    opts.merge!(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

Public: Stops the Honeybadger service.

Examples

Honeybadger.stop # => nil

Returns nothing



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

Public: Sets the Rack environment which is used to report request data with errors.

rack_env - The Hash Rack environment. block - A block to call. Errors reported from within the block will

include request data.

Examples

Honeybadger.with_rack_env(env) do
  begin
    # Risky operation
  rescue => e
    Honeybadger.notify(e)
  end
end

Returns the return value of block.



362
363
364
365
366
367
# File 'lib/honeybadger/agent.rb', line 362

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