Module: Bugsnag

Defined in:
lib/bugsnag.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/session_tracker.rb,
lib/bugsnag/middleware_stack.rb,
lib/bugsnag/integrations/rack.rb,
lib/bugsnag/integrations/rake.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/integrations/shoryuken.rb

Overview

rubocop:todo Metrics/ModuleLength

Defined Under Namespace

Modules: Breadcrumbs, Delivery, Helpers, MetaData, Middleware, Rails, RakeTask, Stacktrace, Utility Classes: Configuration, 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"
VERSION = 
File.read(File.join(File.dirname(__FILE__), "../../VERSION")).strip

Class Method Summary collapse

Class Method Details

.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) 


270
271
272
 
# File 'lib/bugsnag.rb', line 270

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) 


157
158
159
 
# File 'lib/bugsnag.rb', line 157

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.



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

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

.configuration ⇒ Configuration

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

Returns:



165
166
167
168
 
# File 'lib/bugsnag.rb', line 165

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:



50
51
52
53
54
55
56
57
58
59
60
61
62
63
 
# File 'lib/bugsnag.rb', line 50

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, from Bugsnag::Breadcrumbs::VALID_BREADCRUMB_TYPES

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

    set to :auto if the breadcrumb is automatically created



233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
 
# File 'lib/bugsnag.rb', line 233

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 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?

  # 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



216
217
218
219
220
221
222
223
 
# File 'lib/bugsnag.rb', line 216

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.



201
202
203
204
205
206
207
208
209
 
# File 'lib/bugsnag.rb', line 201

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

.notify(exception, auto_notify = false) {|report| ... } ⇒ Object

Explicitly notify of an exception.

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

Yields:

  • (report) 


69
70
71
72
73
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
 
# File 'lib/bugsnag.rb', line 69

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
  yield(report) if block_given? && auto_notify

  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.
    yield(report) if block_given? && !auto_notify

    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

    deliver_notification(report)
  end
end

.register_at_exit ⇒ void

This method returns an undefined value.

Registers an at_exit function to automatically catch errors on exit.



133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
 
# File 'lib/bugsnag.rb', line 133

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_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) 


282
283
284
 
# File 'lib/bugsnag.rb', line 282

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

.session_tracker ⇒ SessionTracker

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

Returns:



174
175
176
177
 
# File 'lib/bugsnag.rb', line 174

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

.start_session ⇒ Object

Starts a session.

Allows Bugsnag to track error rates across releases.



183
184
185
 
# File 'lib/bugsnag.rb', line 183

def start_session
  session_tracker.start_session
end