Class: Bugsnag::Configuration

Inherits:
Object
  • Object
show all
Defined in:
lib/bugsnag/configuration.rb

Constant Summary collapse

API_KEY_REGEX =
/[0-9a-f]{32}/i
THREAD_LOCAL_NAME =
"bugsnag_req_data"
DEFAULT_NOTIFY_ENDPOINT =
"https://notify.bugsnag.com"
DEFAULT_SESSION_ENDPOINT =
"https://sessions.bugsnag.com"
DEFAULT_ENDPOINT =
DEFAULT_NOTIFY_ENDPOINT
DEFAULT_META_DATA_FILTERS =
[
  /authorization/i,
  /cookie/i,
  /password/i,
  /secret/i,
  /warden\.user\.([^.]+)\.key/,
  "rack.request.form_vars"
].freeze
DEFAULT_MAX_BREADCRUMBS =
25
DEFAULT_VENDOR_PATH =

Path to vendored code. Used to mark file paths as out of project.

%r{^(vendor/|\.bundle/)}

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initializeConfiguration

Returns a new instance of Configuration.


216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
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
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
# File 'lib/bugsnag/configuration.rb', line 216

def initialize
  @mutex = Mutex.new

  # Set up the defaults
  self.auto_notify = true
  self.send_environment = false
  self.send_code = true
  self. = Set.new(DEFAULT_META_DATA_FILTERS)
  @redacted_keys = Set.new
  self.scopes_to_filter = DEFAULT_SCOPES_TO_FILTER
  self.hostname = default_hostname
  self.runtime_versions = {}
  self.runtime_versions["ruby"] = RUBY_VERSION
  self.runtime_versions["jruby"] = JRUBY_VERSION if defined?(JRUBY_VERSION)
  self.timeout = 15
  self.release_stage = ENV['BUGSNAG_RELEASE_STAGE']
  self.notify_release_stages = nil
  self.auto_capture_sessions = true

  # All valid breadcrumb types should be allowable initially
  self.enabled_automatic_breadcrumb_types = Bugsnag::Breadcrumbs::VALID_BREADCRUMB_TYPES.dup
  self.before_breadcrumb_callbacks = []
  @on_breadcrumb_callbacks = Breadcrumbs::OnBreadcrumbCallbackList.new(self)

  # Store max_breadcrumbs here instead of outputting breadcrumbs.max_items
  # to avoid infinite recursion when creating breadcrumb buffer
  @max_breadcrumbs = DEFAULT_MAX_BREADCRUMBS

  @endpoints = EndpointConfiguration.new(DEFAULT_NOTIFY_ENDPOINT, DEFAULT_SESSION_ENDPOINT)

  @enable_events = true
  @enable_sessions = true

  @metadata = {}
  @metadata_delegate = Utility::MetadataDelegate.new

  # SystemExit and SignalException are common Exception types seen with
  # successful exits and are not automatically reported to Bugsnag
  # TODO move these defaults into `discard_classes` when `ignore_classes`
  #      is removed
  self.ignore_classes = Set.new([SystemExit, SignalException])
  self.discard_classes = Set.new([])

  # Read the API key from the environment
  self.api_key = ENV["BUGSNAG_API_KEY"]

  # Read NET::HTTP proxy environment variables
  if (proxy_uri = ENV["https_proxy"] || ENV['http_proxy'])
    parse_proxy(proxy_uri)
  end

  # Set up vendor_path regex to mark stacktrace file paths as out of project.
  # Stacktrace lines that matches regex will be marked as "out of project"
  # will only appear in the full trace.
  self.vendor_path = DEFAULT_VENDOR_PATH
  @vendor_paths = []

  # Set up logging
  self.logger = Logger.new(STDOUT)
  self.logger.level = Logger::INFO
  self.logger.formatter = proc do |severity, datetime, progname, msg|
    "** #{progname} #{datetime}: #{msg}\n"
  end

  # Configure the bugsnag middleware stack
  self.internal_middleware = Bugsnag::MiddlewareStack.new
  self.internal_middleware.use Bugsnag::Middleware::ExceptionMetaData
  self.internal_middleware.use Bugsnag::Middleware::DiscardErrorClass
  self.internal_middleware.use Bugsnag::Middleware::IgnoreErrorClass
  self.internal_middleware.use Bugsnag::Middleware::SuggestionData
  self.internal_middleware.use Bugsnag::Middleware::ClassifyError
  self.internal_middleware.use Bugsnag::Middleware::SessionData
  self.internal_middleware.use Bugsnag::Middleware::Breadcrumbs

  self.middleware = Bugsnag::MiddlewareStack.new
  self.middleware.use Bugsnag::Middleware::Callbacks
end

Instance Attribute Details

#api_keyString?

Your Integration API Key

Returns:

  • (String, nil)

23
24
25
# File 'lib/bugsnag/configuration.rb', line 23

def api_key
  @api_key
end

#app_versionString?

The current version of your application

Returns:

  • (String, nil)

55
56
57
# File 'lib/bugsnag/configuration.rb', line 55

def app_version
  @app_version
end

#auto_capture_sessionsBoolean Also known as: track_sessions

Deprecated.

Use #auto_track_sessions instead

Whether Bugsnag should automatically record sessions

Returns:

  • (Boolean)

124
125
126
# File 'lib/bugsnag/configuration.rb', line 124

def auto_capture_sessions
  @auto_capture_sessions
end

#auto_notifyBoolean

Whether notifications should automatically be sent

Returns:

  • (Boolean)

36
37
38
# File 'lib/bugsnag/configuration.rb', line 36

def auto_notify
  @auto_notify
end

#auto_track_sessionsBoolean

Whether sessions should be tracked automatically

Returns:

  • (Boolean)

714
715
716
# File 'lib/bugsnag/configuration.rb', line 714

def auto_track_sessions
  @auto_capture_sessions
end

#before_breadcrumb_callbacksArray<#call>

Callables to be run before a breadcrumb is logged

Returns:

  • (Array<#call>)

152
153
154
# File 'lib/bugsnag/configuration.rb', line 152

def before_breadcrumb_callbacks
  @before_breadcrumb_callbacks
end

#ca_fileString?

Returns:

  • (String, nil)

39
40
41
# File 'lib/bugsnag/configuration.rb', line 39

def ca_file
  @ca_file
end

#contextString?

The default context for all future events Setting this will disable automatic context setting

Returns:

  • (String, nil)

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

def context
  @context
end

#discard_classesSet<String, Regexp>

Exception classes that will be discarded and not sent to Bugsnag

Returns:

  • (Set<String, Regexp>)

119
120
121
# File 'lib/bugsnag/configuration.rb', line 119

def discard_classes
  @discard_classes
end

#enabled_automatic_breadcrumb_typesArray<String>

Deprecated.

A list of strings indicating allowable automatic breadcrumb types

Returns:

  • (Array<String>)

See Also:


148
149
150
# File 'lib/bugsnag/configuration.rb', line 148

def enabled_automatic_breadcrumb_types
  @enabled_automatic_breadcrumb_types
end

#enabled_breadcrumb_typesArray<String>

A list of breadcrumb types that Bugsnag will collect automatically

Returns:

  • (Array<String>)

See Also:


701
702
703
# File 'lib/bugsnag/configuration.rb', line 701

def enabled_breadcrumb_types
  @enabled_automatic_breadcrumb_types
end

#enabled_release_stagesArray<String>?

A list of which release stages should cause notifications to be sent

Returns:

  • (Array<String>, nil)

687
688
689
# File 'lib/bugsnag/configuration.rb', line 687

def enabled_release_stages
  @notify_release_stages
end

#endpointsEndpointConfiguration

The URLs to send events and sessions to


132
133
134
# File 'lib/bugsnag/configuration.rb', line 132

def endpoints
  @endpoints
end

#hostnameString

The name or descriptor of the Ruby server host

Returns:

  • (String)

111
112
113
# File 'lib/bugsnag/configuration.rb', line 111

def hostname
  @hostname
end

#ignore_classesSet<Class, Proc>

Deprecated.

Use #discard_classes instead

Returns:

  • (Set<Class, Proc>)

128
129
130
# File 'lib/bugsnag/configuration.rb', line 128

def ignore_classes
  @ignore_classes
end

#loggerLogger

The logger to use for Bugsnag log messages

Returns:

  • (Logger)

75
76
77
# File 'lib/bugsnag/configuration.rb', line 75

def logger
  @logger
end

#max_breadcrumbsInteger

The maximum allowable amount of breadcrumbs per thread

Returns:

  • (Integer)

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

def max_breadcrumbs
  @max_breadcrumbs
end

#meta_data_filtersSet<String, Regexp>

Deprecated.

Use #redacted_keys instead

A list of keys that should be filtered out from the report and breadcrumb metadata before sending them to Bugsnag

Returns:

  • (Set<String, Regexp>)

61
62
63
# File 'lib/bugsnag/configuration.rb', line 61

def 
  @meta_data_filters
end

#metadataHash (readonly)

Global metadata added to every event

Returns:

  • (Hash)

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

def 
  @metadata
end

#middlewareMiddlewareStack

The middleware stack that will run on every notification

Returns:


79
80
81
# File 'lib/bugsnag/configuration.rb', line 79

def middleware
  @middleware
end

#notify_endpointString Also known as: endpoint

Deprecated.

Use #endpoints instead

The URL error notifications will be delivered to

Returns:

  • (String)

498
499
500
# File 'lib/bugsnag/configuration.rb', line 498

def notify_endpoint
  @endpoints.notify
end

#notify_release_stagesArray<String>?

Deprecated.

A list of which release stages should cause notifications to be sent

Returns:

  • (Array<String>, nil)

32
33
34
# File 'lib/bugsnag/configuration.rb', line 32

def notify_release_stages
  @notify_release_stages
end

#project_rootString?

Any stacktrace lines that match this path will be marked as 'in project'

Returns:

  • (String, nil)

51
52
53
# File 'lib/bugsnag/configuration.rb', line 51

def project_root
  @project_root
end

#proxy_hostString?

The host address of the HTTP proxy that should be used when making requests

Returns:

  • (String, nil)

See Also:


88
89
90
# File 'lib/bugsnag/configuration.rb', line 88

def proxy_host
  @proxy_host
end

#proxy_passwordString?

The password for the user that should be used when making requests via a HTTP proxy

Returns:

  • (String, nil)

See Also:


103
104
105
# File 'lib/bugsnag/configuration.rb', line 103

def proxy_password
  @proxy_password
end

#proxy_portInteger?

The port number of the HTTP proxy that should be used when making requests

Returns:

  • (Integer, nil)

See Also:


93
94
95
# File 'lib/bugsnag/configuration.rb', line 93

def proxy_port
  @proxy_port
end

#proxy_userString?

The user that should be used when making requests via a HTTP proxy

Returns:

  • (String, nil)

See Also:


98
99
100
# File 'lib/bugsnag/configuration.rb', line 98

def proxy_user
  @proxy_user
end

#redacted_keysSet<String, Regexp>

A set of keys that should be redacted from the report and breadcrumb metadata before sending them to Bugsnag

When adding strings, keys that are equal to the string (ignoring case) will be redacted. When adding regular expressions, any keys which match the regular expression will be redacted

Returns:

  • (Set<String, Regexp>)

71
72
73
# File 'lib/bugsnag/configuration.rb', line 71

def redacted_keys
  @redacted_keys
end

#release_stageString?

The current stage of the release process, e.g. 'development', production'

Returns:

  • (String, nil)

27
28
29
# File 'lib/bugsnag/configuration.rb', line 27

def release_stage
  @release_stage
end

#send_codeBoolean

Whether code snippets from the exception stacktrace should be sent with notifications

Returns:

  • (Boolean)

47
48
49
# File 'lib/bugsnag/configuration.rb', line 47

def send_code
  @send_code
end

#send_environmentBoolean

Whether to automatically attach the Rack environment to notifications

Returns:

  • (Boolean)

43
44
45
# File 'lib/bugsnag/configuration.rb', line 43

def send_environment
  @send_environment
end

#session_endpointString

Deprecated.

Use #endpoints instead

The URL session notifications will be delivered to

Returns:

  • (String)

519
520
521
# File 'lib/bugsnag/configuration.rb', line 519

def session_endpoint
  @endpoints.sessions
end

#timeoutInteger

The HTTP request timeout, defaults to 15 seconds

Returns:

  • (Integer)

107
108
109
# File 'lib/bugsnag/configuration.rb', line 107

def timeout
  @timeout
end

#vendor_pathRegexp

Deprecated.

Use #vendor_paths instead

Returns:

  • (Regexp)

160
161
162
# File 'lib/bugsnag/configuration.rb', line 160

def vendor_path
  @vendor_path
end

#vendor_pathsArray<String>

An array of paths within the #project_root that should not be considered as “in project”

These paths should be relative to the #project_root and will only match whole directory names

Returns:

  • (Array<String>)

169
170
171
# File 'lib/bugsnag/configuration.rb', line 169

def vendor_paths
  @vendor_paths
end

Instance 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

642
643
644
645
646
# File 'lib/bugsnag/configuration.rb', line 642

def (section, key_or_data, *args)
  @mutex.synchronize do
    @metadata_delegate.(@metadata, section, key_or_data, *args)
  end
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)

610
611
612
# File 'lib/bugsnag/configuration.rb', line 610

def add_on_breadcrumb(callback)
  @on_breadcrumb_callbacks.add(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)

583
584
585
# File 'lib/bugsnag/configuration.rb', line 583

def add_on_error(callback)
  middleware.use(callback)
end

#app_typeString?

Get the type of application executing the current code

This is usually used to represent if you are running in a Rails server, Sidekiq job, Rake task etc… Bugsnag will automatically detect most application types for you

Returns:

  • (String, nil)

335
336
337
# File 'lib/bugsnag/configuration.rb', line 335

def app_type
  @app_type || @detected_app_type
end

#app_type=(app_type) ⇒ void

This method returns an undefined value.

Set the type of application executing the current code

If an app_type is set, this will be used instead of the automatically detected app_type that Bugsnag would otherwise use

Parameters:

  • app_type (String)

347
348
349
# File 'lib/bugsnag/configuration.rb', line 347

def app_type=(app_type)
  @app_type = app_type
end

Returns the current list of breadcrumbs

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

Returns:

  • (Bugsnag::Utility::CircularBuffer)

490
491
492
# File 'lib/bugsnag/configuration.rb', line 490

def breadcrumbs
  request_data[:breadcrumbs] ||= Bugsnag::Utility::CircularBuffer.new(@max_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)

661
662
663
664
665
# File 'lib/bugsnag/configuration.rb', line 661

def (section, *args)
  @mutex.synchronize do
    @metadata_delegate.(@metadata, section, *args)
  end
end

#clear_request_datavoid

This method returns an undefined value.

Clears the array of data attached to every error notification.


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

def clear_request_data
  Thread.current[THREAD_LOCAL_NAME] = nil
end

#debug(message) ⇒ Object

Logs a debug level message

Parameters:

  • message (String, #to_s)

    The message to log


456
457
458
# File 'lib/bugsnag/configuration.rb', line 456

def debug(message)
  logger.debug(PROG_NAME) { message }
end

#delivery_methodSymbol

Gets the delivery_method that Bugsnag will use to communicate with the notification endpoint.

Returns:

  • (Symbol)

299
300
301
# File 'lib/bugsnag/configuration.rb', line 299

def delivery_method
  @delivery_method || @default_delivery_method || :thread_queue
end

#delivery_method=(delivery_method) ⇒ void

This method returns an undefined value.

Sets the delivery_method that Bugsnag will use to communicate with the notification endpoint.

The default delivery methods are ':thread_queue' and ':synchronous'.

Parameters:

  • delivery_method (Symbol)

311
312
313
# File 'lib/bugsnag/configuration.rb', line 311

def delivery_method=(delivery_method)
  @delivery_method = delivery_method
end

#disable_sessionsvoid

This method returns an undefined value.

Disables session tracking and delivery. Cannot be undone


567
568
569
570
# File 'lib/bugsnag/configuration.rb', line 567

def disable_sessions
  self.auto_capture_sessions = false
  @enable_sessions = false
end

#endpoint=(new_notify_endpoint) ⇒ void

Deprecated.

Use #endpoints instead

This method returns an undefined value.

Sets the notification endpoint

Parameters:

  • new_notify_endpoint (String)

    The URL to deliver error notifications to


510
511
512
513
# File 'lib/bugsnag/configuration.rb', line 510

def endpoint=(new_notify_endpoint)
  warn("The 'endpoint' configuration option is deprecated. Set both endpoints with the 'endpoints=' method instead")
  set_endpoints(new_notify_endpoint, session_endpoint) # Pass the existing session_endpoint through so it doesn't get overwritten
end

#error(message) ⇒ Object

Logs an error level message

Parameters:

  • message (String, #to_s)

    The message to log


448
449
450
# File 'lib/bugsnag/configuration.rb', line 448

def error(message)
  logger.error(PROG_NAME) { message }
end

#info(message) ⇒ Object

Logs an info level message

Parameters:

  • message (String, #to_s)

    The message to log


432
433
434
# File 'lib/bugsnag/configuration.rb', line 432

def info(message)
  logger.info(PROG_NAME) { message }
end

#parse_proxy(uri) ⇒ void

This method returns an undefined value.

Parses and sets proxy from a uri

Parameters:

  • uri (String, #to_s)

    The URI to parse and extract proxy details from


465
466
467
468
469
470
471
# File 'lib/bugsnag/configuration.rb', line 465

def parse_proxy(uri)
  proxy = URI.parse(uri)
  self.proxy_host = proxy.host
  self.proxy_port = proxy.port
  self.proxy_user = proxy.user
  self.proxy_password = proxy.password
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)

622
623
624
# File 'lib/bugsnag/configuration.rb', line 622

def remove_on_breadcrumb(callback)
  @on_breadcrumb_callbacks.remove(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 instance that was passed to #add_on_error, otherwise it will not be removed

Parameters:

  • callback (Proc, Method, #call)

595
596
597
# File 'lib/bugsnag/configuration.rb', line 595

def remove_on_error(callback)
  middleware.remove(callback)
end

#request_dataHash

Returns the array of data that will be automatically attached to every error notification.

Returns:

  • (Hash)

397
398
399
# File 'lib/bugsnag/configuration.rb', line 397

def request_data
  Thread.current[THREAD_LOCAL_NAME] ||= {}
end

#set_endpoints(new_notify_endpoint, new_session_endpoint) ⇒ void

Deprecated.

Use #endpoints instead

This method returns an undefined value.

Sets the notification and session endpoints

Parameters:

  • new_notify_endpoint (String)

    The URL to deliver error notifications to

  • new_session_endpoint (String)

    The URL to deliver session notifications to


542
543
544
# File 'lib/bugsnag/configuration.rb', line 542

def set_endpoints(new_notify_endpoint, new_session_endpoint)
  self.endpoints = EndpointConfiguration.new(new_notify_endpoint, new_session_endpoint)
end

#set_request_data(key, value) ⇒ void

This method returns an undefined value.

Sets an entry in the array of data attached to every error notification.

Parameters:

  • key (String, #to_s)
  • value (Object)

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

def set_request_data(key, value)
  self.request_data[key] = value
end

#should_notify_release_stage?Boolean

Indicates whether the notifier should send a notification based on the configured release stage.

Returns:

  • (Boolean)

380
381
382
# File 'lib/bugsnag/configuration.rb', line 380

def should_notify_release_stage?
  @release_stage.nil? || @notify_release_stages.nil? || @notify_release_stages.include?(@release_stage)
end

#unset_request_data(key, value) ⇒ void

This method returns an undefined value.

Unsets an entry in the array of data attached to every error notification.

Parameters:

  • key (String, #to_s)
  • value (Object)

416
417
418
# File 'lib/bugsnag/configuration.rb', line 416

def unset_request_data(key, value)
  self.request_data.delete(key)
end

#valid_api_key?Boolean

Tests whether the configured API key is valid.

Returns:

  • (Boolean)

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

def valid_api_key?
  !api_key.nil? && api_key =~ API_KEY_REGEX
end

#warn(message) ⇒ Object

Logs a warning level message

Parameters:

  • message (String, #to_s)

    The message to log


440
441
442
# File 'lib/bugsnag/configuration.rb', line 440

def warn(message)
  logger.warn(PROG_NAME) { message }
end