Class: Honeybadger::Agent
- Inherits:
-
Object
- Object
- Honeybadger::Agent
- 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.
Instance Attribute Summary collapse
- #config ⇒ Object readonly private
- #events_worker ⇒ Object readonly private
- #metrics_worker ⇒ Object readonly private
- #worker ⇒ Object readonly private
Class Method Summary collapse
- .instance ⇒ Object private
- .instance=(instance) ⇒ Object private
Instance Method Summary collapse
-
#add_breadcrumb(message, metadata: {}, category: "custom") ⇒ Object
Appends a breadcrumb to the trace.
- #backend ⇒ Object private
-
#backtrace_filter {|line| ... } ⇒ Object
DEPRECATED: Callback to filter backtrace lines.
-
#breadcrumbs ⇒ Object
private
Direct access to the Breadcrumbs::Collector instance.
-
#check_in(id) ⇒ Boolean
Perform a synchronous check_in.
-
#clear! ⇒ Object
Clear all transaction scoped data.
- #collect(collector) ⇒ Object private
-
#configure {|Config::Ruby| ... } ⇒ Object
Configure the Honeybadger agent via Ruby.
-
#context(context = nil, &block) ⇒ Object, self
Save global context for the current request.
- #decrement_counter ⇒ Object private
-
#event(event_type, payload = {}) ⇒ void
Sends event to events backend.
-
#exception_filter ⇒ Object
DEPRECATED: Callback to ignore exceptions.
-
#exception_fingerprint ⇒ Object
DEPRECATED: Callback to add a custom grouping strategy for exceptions.
-
#flush { ... } ⇒ Object, Boolean
Flushes all data from workers before returning.
- #gauge ⇒ Object private
-
#get_context ⇒ Hash?
Get global context for the current request.
- #histogram ⇒ Object private
- #increment_counter ⇒ Object private
- #init!(...) ⇒ Object private
-
#initialize(opts = {}) ⇒ Agent
constructor
A new instance of Agent.
- #instrumentation ⇒ Object
-
#notify(exception_or_opts = nil, opts = {}, **kwargs) ⇒ String, false
Sends an exception to Honeybadger.
- #registry ⇒ Object private
-
#stop(force = false) ⇒ Object
Stops the Honeybadger service.
- #time ⇒ Object private
-
#track_deployment(environment: nil, revision: nil, local_username: nil, repository: nil) ⇒ Boolean
Track a new deployment.
- #with_rack_env(rack_env, &block) ⇒ Object private
Constructor Details
#initialize(opts = {}) ⇒ Agent
Returns a new instance of Agent.
64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 |
# File 'lib/honeybadger/agent.rb', line 64 def initialize(opts = {}) if opts.kind_of?(Config) @config = opts opts = {} end @context = opts.delete(:context) local_context = opts.delete(:local_context) @config ||= Config.new(opts) if local_context @context ||= ContextManager.new @breadcrumbs = Breadcrumbs::Collector.new(config) else @breadcrumbs = nil end init_worker end |
Instance Attribute Details
#config ⇒ Object (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.
441 442 443 |
# File 'lib/honeybadger/agent.rb', line 441 def config @config end |
#events_worker ⇒ Object (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.
514 515 516 |
# File 'lib/honeybadger/agent.rb', line 514 def events_worker @events_worker end |
#metrics_worker ⇒ Object (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.
514 515 516 |
# File 'lib/honeybadger/agent.rb', line 514 def metrics_worker @metrics_worker end |
#worker ⇒ Object (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.
514 515 516 |
# File 'lib/honeybadger/agent.rb', line 514 def worker @worker end |
Class Method Details
.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.
55 56 57 |
# File 'lib/honeybadger/agent.rb', line 55 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.
60 61 62 |
# File 'lib/honeybadger/agent.rb', line 60 def self.instance=(instance) @instance = instance end |
Instance Method Details
#add_breadcrumb(message, metadata: {}, category: "custom") ⇒ Object
Appends a breadcrumb to the trace. Use this when you want to add some custom data to your breadcrumb trace in effort to help debugging. If a notice is reported to Honeybadger, all breadcrumbs within the execution path will be appended to the notice. You will be able to view the breadcrumb trace in the Honeybadger interface to see what events led up to the notice.
318 319 320 321 322 323 324 325 326 327 328 |
# File 'lib/honeybadger/agent.rb', line 318 def (, metadata: {}, category: "custom") params = Util::Sanitizer.new(max_depth: 2).sanitize({ category: category, message: , metadata: }) .add!(Breadcrumbs::Breadcrumb.new(**params)) self end |
#backend ⇒ 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.
524 |
# File 'lib/honeybadger/agent.rb', line 524 def_delegators :config, :backend |
#backtrace_filter {|line| ... } ⇒ Object
DEPRECATED: 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.
501 |
# File 'lib/honeybadger/agent.rb', line 501 def_delegator :config, :backtrace_filter |
#breadcrumbs ⇒ 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.
Direct access to the Breadcrumbs::Collector instance
292 293 294 295 296 |
# File 'lib/honeybadger/agent.rb', line 292 def return @breadcrumbs if @breadcrumbs Thread.current[:__hb_breadcrumbs] ||= Breadcrumbs::Collector.new(config) end |
#check_in(id) ⇒ Boolean
Perform a synchronous check_in.
199 200 201 202 203 204 |
# File 'lib/honeybadger/agent.rb', line 199 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
Clear all transaction scoped data.
274 275 276 277 |
# File 'lib/honeybadger/agent.rb', line 274 def clear! context_manager.clear! .clear! end |
#collect(collector) ⇒ 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.
425 426 427 428 429 430 |
# File 'lib/honeybadger/agent.rb', line 425 def collect(collector) return unless config.insights_enabled? init_metrics_worker metrics_worker.push(collector) end |
#configure {|Config::Ruby| ... } ⇒ Object
Configure the Honeybadger agent via Ruby.
453 |
# File 'lib/honeybadger/agent.rb', line 453 def_delegator :config, :configure |
#context(context = nil, &block) ⇒ Object, self
Save global context for the current request.
266 267 268 269 270 271 |
# File 'lib/honeybadger/agent.rb', line 266 def context(context = nil, &block) block_result = context_manager.set_context(context, &block) unless context.nil? return block_result if block_given? self end |
#decrement_counter ⇒ 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.
549 |
# File 'lib/honeybadger/agent.rb', line 549 def_delegator :instrumentation, :decrement_counter |
#event(event_type, payload = {}) ⇒ void
This method returns an undefined value.
Sends event to events backend
393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 |
# File 'lib/honeybadger/agent.rb', line 393 def event(event_type, payload = {}) init_events_worker extra_payload = {}.tap do |p| p[:request_id] = context_manager.get_request_id if context_manager.get_request_id p[:hostname] = config[:hostname].to_s if config[:'events.attach_hostname'] end event = Event.new(event_type, extra_payload.merge(payload)) config.before_event_hooks.each do |hook| with_error_handling { hook.call(event) } end return if config.ignored_events.any? do |check| with_error_handling do check.all? do |keys, value| if keys == [:event_type] event.event_type&.match?(value) elsif event.dig(*keys) event.dig(*keys).to_s.match?(value) end end end end return if event.halted? events_worker.push(event.as_json) end |
#exception_filter ⇒ Object
DEPRECATED: Callback to ignore exceptions.
See public API documentation for Notice for available attributes.
472 |
# File 'lib/honeybadger/agent.rb', line 472 def_delegator :config, :exception_filter |
#exception_fingerprint ⇒ Object
DEPRECATED: 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.
487 |
# File 'lib/honeybadger/agent.rb', line 487 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.
359 360 361 362 363 364 365 366 |
# File 'lib/honeybadger/agent.rb', line 359 def flush return true unless block_given? yield ensure worker.flush events_worker&.flush metrics_worker&.flush end |
#gauge ⇒ 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.
539 |
# File 'lib/honeybadger/agent.rb', line 539 def_delegator :instrumentation, :gauge |
#get_context ⇒ Hash?
Get global context for the current request.
286 287 288 |
# File 'lib/honeybadger/agent.rb', line 286 def get_context context_manager.get_context end |
#histogram ⇒ 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.
534 |
# File 'lib/honeybadger/agent.rb', line 534 def_delegator :instrumentation, :histogram |
#increment_counter ⇒ 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.
544 |
# File 'lib/honeybadger/agent.rb', line 544 def_delegator :instrumentation, :increment_counter |
#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.
519 |
# File 'lib/honeybadger/agent.rb', line 519 def_delegators :config, :init! |
#instrumentation ⇒ Object
551 552 553 |
# File 'lib/honeybadger/agent.rb', line 551 def instrumentation @instrumentation ||= Honeybadger::Instrumentation.new(self) end |
#notify(exception_or_opts = nil, opts = {}, **kwargs) ⇒ String, false
Sends an exception to Honeybadger. Does not report ignored exceptions by default.
127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 |
# File 'lib/honeybadger/agent.rb', line 127 def notify(exception_or_opts = nil, opts = {}, **kwargs) opts = opts.dup opts.merge!(kwargs) if exception_or_opts.is_a?(Exception) already_reported_notice_id = exception_or_opts.instance_variable_get(:@__hb_notice_id) return already_reported_notice_id if already_reported_notice_id opts[:exception] = exception_or_opts elsif exception_or_opts.respond_to?(:to_hash) opts.merge!(exception_or_opts.to_hash) elsif !exception_or_opts.nil? opts[:error_message] = exception_or_opts.to_s end validate_notify_opts!(opts) ( "Honeybadger Notice", metadata: opts, category: "notice" ) if config[:'breadcrumbs.enabled'] opts[:rack_env] ||= context_manager.get_rack_env opts[:global_context] ||= context_manager.get_context opts[:breadcrumbs] ||= .dup notice = Notice.new(config, opts) config.before_notify_hooks.each do |hook| break if notice.halted? with_error_handling { hook.call(notice) } end 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 if notice.halted? debug { 'halted notice feature=notices' } return false end info { sprintf('Reporting error id=%s', notice.id) } if opts[:sync] || config[:sync] send_now(notice) else push(notice) end if exception_or_opts.is_a?(Exception) exception_or_opts.instance_variable_set(:@__hb_notice_id, notice.id) unless exception_or_opts.frozen? end notice.id end |
#registry ⇒ 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.
433 434 435 436 437 438 |
# File 'lib/honeybadger/agent.rb', line 433 def registry return @registry if defined?(@registry) @registry = Honeybadger::Registry.new.tap do |r| collect(Honeybadger::RegistryExecution.new(r, config, {})) end end |
#stop(force = false) ⇒ Object
Stops the Honeybadger service.
372 373 374 375 376 377 |
# File 'lib/honeybadger/agent.rb', line 372 def stop(force = false) worker.shutdown(force) events_worker&.shutdown(force) metrics_worker&.shutdown(force) true end |
#time ⇒ 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.
529 |
# File 'lib/honeybadger/agent.rb', line 529 def_delegator :instrumentation, :time |
#track_deployment(environment: nil, revision: nil, local_username: nil, repository: nil) ⇒ Boolean
Track a new deployment
218 219 220 221 222 223 224 225 226 227 |
# File 'lib/honeybadger/agent.rb', line 218 def track_deployment(environment: nil, revision: nil, local_username: nil, repository: nil) opts = { environment: environment || config[:env], revision: revision || config[:revision], local_username: local_username, repository: repository } response = backend.track_deployment(opts) response.success? 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.
504 505 506 507 508 509 510 511 |
# File 'lib/honeybadger/agent.rb', line 504 def with_rack_env(rack_env, &block) context_manager.set_rack_env(rack_env) context_manager.set_request_id(rack_env["action_dispatch.request_id"] || SecureRandom.uuid) yield ensure context_manager.set_rack_env(nil) context_manager.set_request_id(nil) end |