Module: Bugsnag

Defined in:
lib/bugsnag.rb,
lib/bugsnag/error.rb,
lib/bugsnag/event.rb,
lib/bugsnag/report.rb,
lib/bugsnag/cleaner.rb,
lib/bugsnag/helpers.rb,
lib/bugsnag/version.rb,
lib/bugsnag/delivery.rb,
lib/bugsnag/meta_data.rb,
lib/bugsnag/stacktrace.rb,
lib/bugsnag/configuration.rb,
lib/bugsnag/code_extractor.rb,
lib/bugsnag/breadcrumb_type.rb,
lib/bugsnag/session_tracker.rb,
lib/bugsnag/middleware_stack.rb,
lib/bugsnag/integrations/rack.rb,
lib/bugsnag/integrations/rake.rb,
lib/bugsnag/endpoint_validator.rb,
lib/bugsnag/integrations/mongo.rb,
lib/bugsnag/on_error_callbacks.rb,
lib/bugsnag/integrations/resque.rb,
lib/bugsnag/delivery/synchronous.rb,
lib/bugsnag/integrations/mailman.rb,
lib/bugsnag/integrations/railtie.rb,
lib/bugsnag/integrations/sidekiq.rb,
lib/bugsnag/delivery/thread_queue.rb,
lib/bugsnag/endpoint_configuration.rb,
lib/bugsnag/integrations/shoryuken.rb

Overview

rubocop:todo Metrics/ModuleLength

Defined Under Namespace

Modules: BreadcrumbType, Breadcrumbs, Delivery, Helpers, MetaData, Middleware, Rails, RakeTask, Stacktrace, Utility Classes: Configuration, EndpointConfiguration, Error, Mailman, MiddlewareStack, Rack, Railtie, Report, Resque, SessionTracker, Shoryuken, Sidekiq

Constant Summary collapse

LOCK = 
Mutex.new
INTEGRATIONS = 
[:resque, :sidekiq, :mailman, :delayed_job, :shoryuken, :que, :mongo]
NIL_EXCEPTION_DESCRIPTION = 
"'nil' was notified as an exception"
Event =

For now Event is just an alias of Report. This points to the same object so any changes to Report will also affect Event

Report
VERSION = 
File.read(File.join(File.dirname(__FILE__), "../../VERSION")).strip

Class Method Summary collapse

Class Method Details

.add_metadata(section, data) ⇒ void .add_metadata(section, key, value) ⇒ void

This method returns an undefined value.

Add values to metadata

Overloads:

  • .add_metadata(section, data) ⇒ void

    Merges data into the given section of metadata

    Parameters:

    • section (String, Symbol)
    • data (Hash)
  • .add_metadata(section, key, value) ⇒ void

    Sets key to value in the given section of metadata. If the value is nil the key will be deleted

    Parameters:

    • section (String, Symbol)
    • key (String, Symbol)
    • value 


408
409
410
 
# File 'lib/bugsnag.rb', line 408

def add_metadata(section, key_or_data, *args)
  configuration.add_metadata(section, key_or_data, *args)
end

.add_on_breadcrumb(callback) ⇒ void

This method returns an undefined value.

Add the given callback to the list of on_breadcrumb callbacks

The on_breadcrumb callbacks will be called when a breadcrumb is left and are passed the Breadcrumb object

Returning false from an on_breadcrumb callback will cause the breadcrumb to be ignored and will prevent any remaining callbacks from being called

Parameters:

  • callback (Proc, Method, #call) 


344
345
346
 
# File 'lib/bugsnag.rb', line 344

def add_on_breadcrumb(callback)
  configuration.add_on_breadcrumb(callback)
end

.add_on_error(callback) ⇒ void

This method returns an undefined value.

Add the given callback to the list of on_error callbacks

The on_error callbacks will be called when an error is captured or reported and are passed a Report object

Returning false from an on_error callback will cause the error to be ignored and will prevent any remaining callbacks from being called

Parameters:

  • callback (Proc, Method, #call) 


317
318
319
 
# File 'lib/bugsnag.rb', line 317

def add_on_error(callback)
  configuration.add_on_error(callback)
end

.at_exit_handler_installed? ⇒ Boolean

Checks if an at_exit handler has been added.

The configure method will add this automatically, but it can be added manually using register_at_exit.

Returns:

  • (Boolean) 


177
178
179
 
# File 'lib/bugsnag.rb', line 177

def at_exit_handler_installed?
  @exit_handler_added ||= false
end

.before_notify_callbacks ⇒ Object

Deprecated.

Use add_on_error instead

Allow access to “before notify” callbacks as an array.

These callbacks will be called whenever an error notification is being made.



236
237
238
 
# File 'lib/bugsnag.rb', line 236

def before_notify_callbacks
  Bugsnag.configuration.request_data[:before_callbacks] ||= []
end

.breadcrumbs ⇒ Bugsnag::Utility::CircularBuffer

Returns the current list of breadcrumbs

This is a per-thread circular buffer, containing at most ‘max_breadcrumbs’ breadcrumbs

Returns:

  • (Bugsnag::Utility::CircularBuffer) 


367
368
369
 
# File 'lib/bugsnag.rb', line 367

def breadcrumbs
  configuration.breadcrumbs
end

.clear_metadata(section) ⇒ void .clear_metadata(section, key) ⇒ void

This method returns an undefined value.

Clear values from metadata

Overloads:

  • .clear_metadata(section) ⇒ void

    Clears the given section of metadata

    Parameters:

    • section (String, Symbol)
  • .clear_metadata(section, key) ⇒ void

    Clears the key in the given section of metadata

    Parameters:

    • section (String, Symbol)
    • key (String, Symbol) 


425
426
427
 
# File 'lib/bugsnag.rb', line 425

def clear_metadata(section, *args)
  configuration.clear_metadata(section, *args)
end

.configuration ⇒ Configuration

Returns the client’s Configuration object, or creates one if not yet created.

Returns:



185
186
187
188
 
# File 'lib/bugsnag.rb', line 185

def configuration
  @configuration = nil unless defined?(@configuration)
  @configuration || LOCK.synchronize { @configuration ||= Bugsnag::Configuration.new }
end

.configure(validate_api_key = true) {|configuration| ... } ⇒ void

This method returns an undefined value.

Configure the Bugsnag notifier application-wide settings.

Yields a Configuration object to use to set application settings.

Yield Parameters:



55
56
57
58
59
60
61
62
63
64
65
66
67
68
 
# File 'lib/bugsnag.rb', line 55

def configure(validate_api_key=true)
  yield(configuration) if block_given?

  # Create the session tracker if sessions are enabled to avoid the overhead
  # of creating it on the first request. We skip this if we're not validating
  # the API key as we use this internally before the user's configure block
  # has run, so we don't know if sessions are enabled yet.
  session_tracker if validate_api_key && configuration.auto_capture_sessions

  check_key_valid if validate_api_key
  check_endpoint_setup

  register_at_exit
end

.leave_breadcrumb(name, meta_data = {}, type = Bugsnag::Breadcrumbs::MANUAL_BREADCRUMB_TYPE, auto = :manual) ⇒ void

This method returns an undefined value.

Leave a breadcrumb to be attached to subsequent reports

Parameters:

  • name (String) —

    the main breadcrumb name/message

  • meta_data (Hash) (defaults to: {}) —

    String, Numeric, or Boolean meta data to attach

  • type (String) (defaults to: Bugsnag::Breadcrumbs::MANUAL_BREADCRUMB_TYPE) —

    the breadcrumb type, see BreadcrumbType

  • auto (Symbol) (defaults to: :manual) —

    set to :auto if the breadcrumb is automatically created



276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
 
# File 'lib/bugsnag.rb', line 276

def leave_breadcrumb(name, meta_data={}, type=Bugsnag::Breadcrumbs::MANUAL_BREADCRUMB_TYPE, auto=:manual)
  breadcrumb = Bugsnag::Breadcrumbs::Breadcrumb.new(name, type, meta_data, auto)
  validator = Bugsnag::Breadcrumbs::Validator.new(configuration)

  # Initial validation
  validator.validate(breadcrumb)

  # Skip if it's already invalid
  return if breadcrumb.ignore?

  # Run before_breadcrumb_callbacks
  configuration.before_breadcrumb_callbacks.each do |c|
    c.arity > 0 ? c.call(breadcrumb) : c.call
    break if breadcrumb.ignore?
  end

  # Return early if ignored
  return if breadcrumb.ignore?

  # Run on_breadcrumb callbacks
  configuration.on_breadcrumb_callbacks.call(breadcrumb)
  return if breadcrumb.ignore?

  # Validate again in case of callback alteration
  validator.validate(breadcrumb)

  # Add to breadcrumbs buffer if still valid
  configuration.breadcrumbs << breadcrumb unless breadcrumb.ignore?
end

.load_integration(integration) ⇒ void

This method returns an undefined value.

Load a specific integration.

Parameters:

  • integration (Symbol) —

    One of the integrations in INTEGRATIONS



259
260
261
262
263
264
265
266
 
# File 'lib/bugsnag.rb', line 259

def load_integration(integration)
  integration = :railtie if integration == :rails
  if INTEGRATIONS.include?(integration) || integration == :railtie
    require "bugsnag/integrations/#{integration}"
  else
    configuration.debug("Integration #{integration} is not currently supported")
  end
end

.load_integrations ⇒ void

This method returns an undefined value.

Attempts to load all integrations through auto-discovery.



244
245
246
247
248
249
250
251
252
 
# File 'lib/bugsnag.rb', line 244

def load_integrations
  require "bugsnag/integrations/railtie" if defined?(Rails::Railtie)
  INTEGRATIONS.each do |integration|
    begin
      require "bugsnag/integrations/#{integration}"
    rescue LoadError
    end
  end
end

.metadata ⇒ Hash

Global metadata added to every event

Returns:

  • (Hash) 


388
389
390
 
# File 'lib/bugsnag.rb', line 388

def metadata
  configuration.metadata
end

.notify(exception, auto_notify = false, &block) ⇒ Object

Explicitly notify of an exception.

Optionally accepts a block to append metadata to the yielded report.



74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
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
137
138
139
140
141
142
143
144
145
146
147
 
# File 'lib/bugsnag.rb', line 74

def notify(exception, auto_notify=false, &block)
  unless auto_notify.is_a? TrueClass or auto_notify.is_a? FalseClass
    configuration.warn("Adding metadata/severity using a hash is no longer supported, please use block syntax instead")
    auto_notify = false
  end

  return unless should_deliver_notification?(exception, auto_notify)

  exception = NIL_EXCEPTION_DESCRIPTION if exception.nil?

  report = Report.new(exception, configuration, auto_notify)

  # If this is an auto_notify we yield the block before the any middleware is run
  begin
    yield(report) if block_given? && auto_notify
  rescue StandardError => e
    configuration.warn("Error in internal notify block: #{e}")
    configuration.warn("Error in internal notify block stacktrace: #{e.backtrace.inspect}")
  end

  if report.ignore?
    configuration.debug("Not notifying #{report.exceptions.last[:errorClass]} due to ignore being signified in auto_notify block")
    return
  end

  # Run internal middleware
  configuration.internal_middleware.run(report)
  if report.ignore?
    configuration.debug("Not notifying #{report.exceptions.last[:errorClass]} due to ignore being signified in internal middlewares")
    return
  end

  # Store before_middleware severity reason for future reference
  initial_severity = report.severity
  initial_reason = report.severity_reason

  # Run users middleware
  configuration.middleware.run(report) do
    if report.ignore?
      configuration.debug("Not notifying #{report.exceptions.last[:errorClass]} due to ignore being signified in user provided middleware")
      return
    end

    # If this is not an auto_notify then the block was provided by the user. This should be the last
    # block that is run as it is the users "most specific" block.
    begin
      yield(report) if block_given? && !auto_notify
    rescue StandardError => e
      configuration.warn("Error in notify block: #{e}")
      configuration.warn("Error in notify block stacktrace: #{e.backtrace.inspect}")
    end

    if report.ignore?
      configuration.debug("Not notifying #{report.exceptions.last[:errorClass]} due to ignore being signified in user provided block")
      return
    end

    # Test whether severity has been changed and ensure severity_reason is consistant in auto_notify case
    if report.severity != initial_severity
      report.severity_reason = {
        :type => Report::USER_CALLBACK_SET_SEVERITY
      }
    else
      report.severity_reason = initial_reason
    end

    if report.unhandled_overridden?
      # let the dashboard know that the unhandled flag was overridden
      report.severity_reason[:unhandledOverridden] = true
    end

    deliver_notification(report)
  end
end

.pause_session ⇒ void

This method returns an undefined value.

Stop any events being attributed to the current session until it is resumed or a new session is started

See Also:



215
216
217
 
# File 'lib/bugsnag.rb', line 215

def pause_session
  session_tracker.pause_session
end

.register_at_exit ⇒ void

This method returns an undefined value.

Registers an at_exit function to automatically catch errors on exit.



153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
 
# File 'lib/bugsnag.rb', line 153

def register_at_exit
  return if at_exit_handler_installed?
  @exit_handler_added = true
  at_exit do
    if $!
      exception = unwrap_bundler_exception($!)

      Bugsnag.notify(exception, true) do |report|
        report.severity = 'error'
        report.severity_reason = {
          :type => Bugsnag::Report::UNHANDLED_EXCEPTION
        }
      end
    end
  end
end

.remove_on_breadcrumb(callback) ⇒ void

This method returns an undefined value.

Remove the given callback from the list of on_breadcrumb callbacks

Note that this must be the same instance that was passed to add_on_breadcrumb, otherwise it will not be removed

Parameters:

  • callback (Proc, Method, #call) 


356
357
358
 
# File 'lib/bugsnag.rb', line 356

def remove_on_breadcrumb(callback)
  configuration.remove_on_breadcrumb(callback)
end

.remove_on_error(callback) ⇒ void

This method returns an undefined value.

Remove the given callback from the list of on_error callbacks

Note that this must be the same Proc instance that was passed to add_on_error, otherwise it will not be removed

Parameters:

  • callback (Proc) 


329
330
331
 
# File 'lib/bugsnag.rb', line 329

def remove_on_error(callback)
  configuration.remove_on_error(callback)
end

.resume_session ⇒ Boolean

Resume the current session if it was previously paused. If there is no current session, a new session will be started

Returns:

  • (Boolean) —

    true if a paused session was resumed

See Also:



226
227
228
 
# File 'lib/bugsnag.rb', line 226

def resume_session
  session_tracker.resume_session
end

.session_tracker ⇒ SessionTracker

Returns the client’s SessionTracker object, or creates one if not yet created.

Returns:



194
195
196
197
 
# File 'lib/bugsnag.rb', line 194

def session_tracker
  @session_tracker = nil unless defined?(@session_tracker)
  @session_tracker || LOCK.synchronize { @session_tracker ||= Bugsnag::SessionTracker.new}
end

.start_session ⇒ void

This method returns an undefined value.

Starts a new session, which allows Bugsnag to track error rates across releases



204
205
206
 
# File 'lib/bugsnag.rb', line 204

def start_session
  session_tracker.start_session
end