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

#initialize ⇒ Configuration

Returns a new instance of Configuration.



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
293
294
295
296
297
298
299
300
 
# File 'lib/bugsnag/configuration.rb', line 224

def initialize
  @mutex = Mutex.new

  # Set up the defaults
  self.auto_notify = true
  self.send_environment = false
  self.send_code = true
  self.meta_data_filters = 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_key ⇒ String?

Your Integration API Key

Returns:

  • (String, nil) 


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

def api_key
  @api_key
end

#app_version ⇒ String?

The current version of your application

Returns:

  • (String, nil) 


63
64
65
 
# File 'lib/bugsnag/configuration.rb', line 63

def app_version
  @app_version
end

#auto_capture_sessions ⇒ Boolean Also known as: track_sessions

Deprecated.

Use #auto_track_sessions instead

Whether Bugsnag should automatically record sessions

Returns:

  • (Boolean) 


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

def auto_capture_sessions
  @auto_capture_sessions
end

#auto_notify ⇒ Boolean

Whether notifications should automatically be sent

Returns:

  • (Boolean) 


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

def auto_notify
  @auto_notify
end

#auto_track_sessions ⇒ Boolean

Whether sessions should be tracked automatically

Returns:

  • (Boolean) 


736
737
738
 
# File 'lib/bugsnag/configuration.rb', line 736

def auto_track_sessions
  @auto_capture_sessions
end

#before_breadcrumb_callbacks ⇒ Array<#call>

Callables to be run before a breadcrumb is logged

Returns:

  • (Array<#call>) 


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

def before_breadcrumb_callbacks
  @before_breadcrumb_callbacks
end

#ca_file ⇒ String?

Returns:

  • (String, nil) 


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

def ca_file
  @ca_file
end

#context ⇒ String?

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

Returns:

  • (String, nil) 


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

def context
  @context
end

#discard_classes ⇒ Set<String, Regexp>

Exception classes that will be discarded and not sent to Bugsnag

Returns:

  • (Set<String, Regexp>) 


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

def discard_classes
  @discard_classes
end

#enabled_automatic_breadcrumb_types ⇒ Array<String>

Deprecated.

Use #enabled_breadcrumb_types instead

A list of strings indicating allowable automatic breadcrumb types

Returns:

  • (Array<String>)

See Also:



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

def enabled_automatic_breadcrumb_types
  @enabled_automatic_breadcrumb_types
end

#enabled_breadcrumb_types ⇒ Array<String>

A list of breadcrumb types that Bugsnag will collect automatically

Returns:

  • (Array<String>)

See Also:



723
724
725
 
# File 'lib/bugsnag/configuration.rb', line 723

def enabled_breadcrumb_types
  @enabled_automatic_breadcrumb_types
end

#enabled_release_stages ⇒ Array<String>?

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

Returns:

  • (Array<String>, nil) 


709
710
711
 
# File 'lib/bugsnag/configuration.rb', line 709

def enabled_release_stages
  @notify_release_stages
end

#endpoints ⇒ EndpointConfiguration

The URLs to send events and sessions to

Returns:



140
141
142
 
# File 'lib/bugsnag/configuration.rb', line 140

def endpoints
  @endpoints
end

#hostname ⇒ String

The name or descriptor of the Ruby server host

Returns:

  • (String) 


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

def hostname
  @hostname
end

#ignore_classes ⇒ Set<Class, Proc>

Deprecated.

Use #discard_classes instead

Returns:

  • (Set<Class, Proc>) 


136
137
138
 
# File 'lib/bugsnag/configuration.rb', line 136

def ignore_classes
  @ignore_classes
end

#logger ⇒ Logger

The logger to use for Bugsnag log messages

Returns:

  • (Logger) 


83
84
85
 
# File 'lib/bugsnag/configuration.rb', line 83

def logger
  @logger
end

#max_breadcrumbs ⇒ Integer

The maximum allowable amount of breadcrumbs per thread

Returns:

  • (Integer) 


164
165
166
 
# File 'lib/bugsnag/configuration.rb', line 164

def max_breadcrumbs
  @max_breadcrumbs
end

#meta_data_filters ⇒ Set<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>) 


69
70
71
 
# File 'lib/bugsnag/configuration.rb', line 69

def meta_data_filters
  @meta_data_filters
end

#metadata ⇒ Hash (readonly)

Global metadata added to every event

Returns:

  • (Hash) 


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

def metadata
  @metadata
end

#middleware ⇒ MiddlewareStack

The middleware stack that will run on every notification

Returns:



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

def middleware
  @middleware
end

#notify_endpoint ⇒ String Also known as: endpoint

Deprecated.

Use #endpoints instead

The URL error notifications will be delivered to

Returns:

  • (String) 


506
507
508
 
# File 'lib/bugsnag/configuration.rb', line 506

def notify_endpoint
  @endpoints.notify
end

#notify_release_stages ⇒ Array<String>?

Deprecated.

Use #enabled_release_stages instead

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

Returns:

  • (Array<String>, nil) 


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

def notify_release_stages
  @notify_release_stages
end

#project_root ⇒ String?

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

Returns:

  • (String, nil) 


59
60
61
 
# File 'lib/bugsnag/configuration.rb', line 59

def project_root
  @project_root
end

#proxy_host ⇒ String?

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

Returns:

  • (String, nil)

See Also:



96
97
98
 
# File 'lib/bugsnag/configuration.rb', line 96

def proxy_host
  @proxy_host
end

#proxy_password ⇒ String?

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

Returns:

  • (String, nil)

See Also:



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

def proxy_password
  @proxy_password
end

#proxy_port ⇒ Integer?

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

Returns:

  • (Integer, nil)

See Also:



101
102
103
 
# File 'lib/bugsnag/configuration.rb', line 101

def proxy_port
  @proxy_port
end

#proxy_user ⇒ String?

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

Returns:

  • (String, nil)

See Also:



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

def proxy_user
  @proxy_user
end

#redacted_keys ⇒ Set<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>) 


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

def redacted_keys
  @redacted_keys
end

#release_stage ⇒ String?

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

Returns:

  • (String, nil) 


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

def release_stage
  @release_stage
end

#send_code ⇒ Boolean

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

Returns:

  • (Boolean) 


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

def send_code
  @send_code
end

#send_environment ⇒ Boolean

Whether to automatically attach the Rack environment to notifications

Returns:

  • (Boolean) 


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

def send_environment
  @send_environment
end

#session_endpoint ⇒ String

Deprecated.

Use #endpoints instead

The URL session notifications will be delivered to

Returns:

  • (String) 


527
528
529
 
# File 'lib/bugsnag/configuration.rb', line 527

def session_endpoint
  @endpoints.sessions
end

#timeout ⇒ Integer

The HTTP request timeout, defaults to 15 seconds

Returns:

  • (Integer) 


115
116
117
 
# File 'lib/bugsnag/configuration.rb', line 115

def timeout
  @timeout
end

#vendor_path ⇒ Regexp

Deprecated.

Use #vendor_paths instead

Returns:

  • (Regexp) 


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

def vendor_path
  @vendor_path
end

#vendor_paths ⇒ Array<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>) 


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

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 


664
665
666
667
668
 
# File 'lib/bugsnag/configuration.rb', line 664

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


632
633
634
 
# File 'lib/bugsnag/configuration.rb', line 632

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) 


605
606
607
 
# File 'lib/bugsnag/configuration.rb', line 605

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

#app_type ⇒ String?

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) 


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

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) 


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

def app_type=(app_type)
  @app_type = app_type
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) 


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

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) 


683
684
685
686
687
 
# File 'lib/bugsnag/configuration.rb', line 683

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

#clear_request_data ⇒ void

This method returns an undefined value.

Clears the array of data attached to every error notification.



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

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



464
465
466
 
# File 'lib/bugsnag/configuration.rb', line 464

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

#delivery_method ⇒ Symbol

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

Returns:

  • (Symbol) 


307
308
309
 
# File 'lib/bugsnag/configuration.rb', line 307

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) 


319
320
321
 
# File 'lib/bugsnag/configuration.rb', line 319

def delivery_method=(delivery_method)
  @delivery_method = delivery_method
end

#disable_sessions ⇒ void

This method returns an undefined value.

Disables session tracking and delivery. Cannot be undone



575
576
577
578
 
# File 'lib/bugsnag/configuration.rb', line 575

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



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

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



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

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



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

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

#on_error(&block) ⇒ void

This method returns an undefined value.

Add the given block 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



590
591
592
 
# File 'lib/bugsnag/configuration.rb', line 590

def on_error(&block)
  middleware.use(block)
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



473
474
475
476
477
478
479
 
# File 'lib/bugsnag/configuration.rb', line 473

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) 


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

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) 


617
618
619
 
# File 'lib/bugsnag/configuration.rb', line 617

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

#request_data ⇒ Hash

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

Returns:

  • (Hash) 


405
406
407
 
# File 'lib/bugsnag/configuration.rb', line 405

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



550
551
552
 
# File 'lib/bugsnag/configuration.rb', line 550

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) 


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

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) 


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

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) 


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

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) 


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

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



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

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