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



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



228
229
230
# File 'lib/honeybadger/agent.rb', line 228

def config
  @config
end

#workerObject (readonly)

Internal



327
328
329
# File 'lib/honeybadger/agent.rb', line 327

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

#clear!Object

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



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

def clear!
  context_manager.clear!
end

#context(hash = nil) ⇒ Object

Public: Save global context for the current request.

hash - A Hash of data which will be sent to Honeybadger when an error

occurs. (default: nil)

Examples:

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

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

# Clearing global context:
Honeybadger.context.clear!

Returns self so that method calls can be chained.



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

def context(hash = nil)
  context_manager.set_context(hash) unless hash.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.



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

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.



175
176
177
# File 'lib/honeybadger/agent.rb', line 175

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. (optional)
:force         - Always report the exception, even when
                 ignored. (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({
  error_class: 'MyClass',
  error_message: 'Something went wrong.',
  context: {my_data: 'value'}
}) # => '06220c5a-b471-41e5-baeb-de247da45a56'

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



99
100
101
102
103
104
105
106
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
# File 'lib/honeybadger/agent.rb', line 99

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



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

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.



319
320
321
322
323
324
# File 'lib/honeybadger/agent.rb', line 319

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