Class: Sentry::Configuration

Inherits:
Object
  • Object
show all
Includes:
ArgumentCheckingHelper, CustomInspection, LoggingHelper
Defined in:
lib/sentry/configuration.rb

Constant Summary collapse

PUMA_IGNORE_DEFAULT =

These exceptions could enter Puma’s ‘lowlevel_error_handler` callback and the SDK’s Puma integration But they are mostly considered as noise and should be ignored by default Please see github.com/getsentry/sentry-ruby/pull/2026 for more information

[
  "Puma::MiniSSL::SSLError",
  "Puma::HttpParserError",
  "Puma::HttpParserError501"
].freeze
IGNORE_DEFAULT =

Most of these errors generate 4XX responses. In general, Sentry clients only automatically report 5xx responses.

[
  "Mongoid::Errors::DocumentNotFound",
  "Rack::QueryParser::InvalidParameterError",
  "Rack::QueryParser::ParameterTypeError",
  "Sinatra::NotFound"
].freeze
RACK_ENV_WHITELIST_DEFAULT =
%w[
  REMOTE_ADDR
  SERVER_NAME
  SERVER_PORT
].freeze
HEROKU_DYNO_METADATA_MESSAGE =
"You are running on Heroku but haven't enabled Dyno Metadata. For Sentry's "\
"release detection to work correctly, please run `heroku labs:enable runtime-dyno-metadata`"
LOG_PREFIX =
"** [Sentry] "
MODULE_SEPARATOR =
"::"
SKIP_INSPECTION_ATTRIBUTES =
[:@linecache, :@stacktrace_builder]
INSTRUMENTERS =
[:sentry, :otel]
PROPAGATION_TARGETS_MATCH_ALL =
/.*/
DEFAULT_PATCHES =
%i[redis puma http].freeze
APP_DIRS_PATTERN =
/(bin|exe|app|config|lib|test|spec)/

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initializeConfiguration

Returns a new instance of Configuration.



365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
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
# File 'lib/sentry/configuration.rb', line 365

def initialize
  self.app_dirs_pattern = APP_DIRS_PATTERN
  self.debug = Sentry::Utils::EnvHelper.env_to_bool(ENV["SENTRY_DEBUG"])
  self.background_worker_threads = (processor_count / 2.0).ceil
  self.background_worker_max_queue = BackgroundWorker::DEFAULT_MAX_QUEUE
  self.backtrace_cleanup_callback = nil
  self.strip_backtrace_load_path = true
  self.max_breadcrumbs = BreadcrumbBuffer::DEFAULT_SIZE
  self.breadcrumbs_logger = []
  self.context_lines = 3
  self.include_local_variables = false
  self.environment = environment_from_env
  self.enabled_environments = []
  self.exclude_loggers = []
  self.excluded_exceptions = IGNORE_DEFAULT + PUMA_IGNORE_DEFAULT
  self.inspect_exception_causes_for_exclusion = true
  self.linecache = ::Sentry::LineCache.new
  self.logger = ::Sentry::Logger.new(STDOUT)
  self.project_root = Dir.pwd
  self.propagate_traces = true

  self.sample_rate = 1.0
  self.send_modules = true
  self.send_default_pii = false
  self.skip_rake_integration = false
  self.send_client_reports = true
  self.auto_session_tracking = true
  self.enable_backpressure_handling = false
  self.trusted_proxies = []
  self.dsn = ENV["SENTRY_DSN"]

  spotlight_env = ENV["SENTRY_SPOTLIGHT"]
  spotlight_bool = Sentry::Utils::EnvHelper.env_to_bool(spotlight_env, strict: true)
  self.spotlight = spotlight_bool.nil? ? (spotlight_env || false) : spotlight_bool
  self.server_name = server_name_from_env
  self.instrumenter = :sentry
  self.trace_propagation_targets = [PROPAGATION_TARGETS_MATCH_ALL]
  self.enabled_patches = DEFAULT_PATCHES.dup

  self.before_send = nil
  self.before_send_transaction = nil
  self.rack_env_whitelist = RACK_ENV_WHITELIST_DEFAULT
  self.traces_sampler = nil
  self.enable_tracing = nil

  self.profiler_class = Sentry::Profiler

  @transport = Transport::Configuration.new
  @cron = Cron::Configuration.new
  @metrics = Metrics::Configuration.new
  @gem_specs = Hash[Gem::Specification.map { |spec| [spec.name, spec.version.to_s] }] if Gem::Specification.respond_to?(:map)

  run_post_initialization_callbacks
end

Instance Attribute Details

#app_dirs_patternRegexp?

Directories to be recognized as part of your app. e.g. if you have an ‘engines` dir at the root of your project, you may want to set this to something like /(app|config|engines|lib)/

The default is value is /(bin|exe|app|config|lib|test|spec)/

Returns:

  • (Regexp, nil)


29
30
31
# File 'lib/sentry/configuration.rb', line 29

def app_dirs_pattern
  @app_dirs_pattern
end

#asyncProc?

Deprecated.

It will be removed in the next major release. Please read github.com/getsentry/sentry-ruby/issues/1522 for more information

Provide an object that responds to ‘call` to send events asynchronously. E.g.: lambda { |event| Thread.new { Sentry.send_event(event) } }

Returns:

  • (Proc, nil)


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

def async
  @async
end

#auto_session_trackingBoolean

Track sessions in request/response cycles automatically

Returns:

  • (Boolean)


277
278
279
# File 'lib/sentry/configuration.rb', line 277

def auto_session_tracking
  @auto_session_tracking
end

#background_worker_max_queueInteger

The maximum queue size for the background worker. Jobs will be rejected above this limit.

Default is BackgroundWorker::DEFAULT_MAX_QUEUE.

Returns:

  • (Integer)


53
54
55
# File 'lib/sentry/configuration.rb', line 53

def background_worker_max_queue
  @background_worker_max_queue
end

#background_worker_threadsInteger

to send events in a non-blocking way, sentry-ruby has its own background worker by default, the worker holds a thread pool that has [the number of processors] threads but you can configure it with this configuration option E.g.: config.background_worker_threads = 5

if you want to send events synchronously, set the value to 0 E.g.: config.background_worker_threads = 0

Returns:

  • (Integer)


46
47
48
# File 'lib/sentry/configuration.rb', line 46

def background_worker_threads
  @background_worker_threads
end

#backtrace_cleanup_callbackProc?

a proc/lambda that takes an array of stack traces it’ll be used to silence (reduce) backtrace of the exception

Examples:

config.backtrace_cleanup_callback = lambda do |backtrace|
  Rails.backtrace_cleaner.clean(backtrace)
end

Returns:

  • (Proc, nil)


64
65
66
# File 'lib/sentry/configuration.rb', line 64

def backtrace_cleanup_callback
  @backtrace_cleanup_callback
end

#before_breadcrumbProc

Optional Proc, called before adding the breadcrumb to the current scope

Examples:

config.before = lambda do |breadcrumb, hint|
  breadcrumb.message = 'a'
  breadcrumb
end

Returns:

  • (Proc)


73
74
75
# File 'lib/sentry/configuration.rb', line 73

def before_breadcrumb
  @before_breadcrumb
end

#before_sendProc

Optional Proc, called before sending an event to the server

Examples:

config.before_send = lambda do |event, hint|
  # skip ZeroDivisionError exceptions
  # note: hint[:exception] would be a String if you use async callback
  if hint[:exception].is_a?(ZeroDivisionError)
    nil
  else
    event
  end
end

Returns:

  • (Proc)


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

def before_send
  @before_send
end

#before_send_transactionProc

Optional Proc, called before sending an event to the server

Examples:

config.before_send_transaction = lambda do |event, hint|
  # skip unimportant transactions or strip sensitive data
  if event.transaction == "/healthcheck/route"
    nil
  else
    event
  end
end

Returns:

  • (Proc)


100
101
102
# File 'lib/sentry/configuration.rb', line 100

def before_send_transaction
  @before_send_transaction
end

An array of breadcrumbs loggers to be used. Available options are:

  • :sentry_logger

  • :http_logger

  • :redis_logger

And if you also use sentry-rails:

  • :active_support_logger

  • :monotonic_active_support_logger

Returns:

  • (Array<Symbol>)


112
113
114
# File 'lib/sentry/configuration.rb', line 112

def breadcrumbs_logger
  @breadcrumbs_logger
end

#context_linesInteger?

Number of lines of code context to capture, or nil for none

Returns:

  • (Integer, nil)


120
121
122
# File 'lib/sentry/configuration.rb', line 120

def context_lines
  @context_lines
end

#cronCron::Configuration (readonly)

Cron related configuration.

Returns:



245
246
247
# File 'lib/sentry/configuration.rb', line 245

def cron
  @cron
end

#debugBoolean

Whether the SDK should run in the debugging mode. Default is false. If set to true, SDK errors will be logged with backtrace

Returns:

  • (Boolean)


129
130
131
# File 'lib/sentry/configuration.rb', line 129

def debug
  @debug
end

#dsnString

the dsn value, whether it’s set via ‘config.dsn=` or `ENV`

Returns:

  • (String)


133
134
135
# File 'lib/sentry/configuration.rb', line 133

def dsn
  @dsn
end

#enable_backpressure_handlingBoolean

Whether to downsample transactions automatically because of backpressure. Starts a new monitor thread to check health of the SDK every 10 seconds. Default is false

Returns:

  • (Boolean)


283
284
285
# File 'lib/sentry/configuration.rb', line 283

def enable_backpressure_handling
  @enable_backpressure_handling
end

#enable_tracingBoolean?

Easier way to use performance tracing If set to true, will set traces_sample_rate to 1.0

Returns:

  • (Boolean, nil)


268
269
270
# File 'lib/sentry/configuration.rb', line 268

def enable_tracing
  @enable_tracing
end

#enabled_environmentsArray<String>

Whitelist of enabled_environments that will send notifications to Sentry. Array of Strings.

Returns:

  • (Array<String>)


137
138
139
# File 'lib/sentry/configuration.rb', line 137

def enabled_environments
  @enabled_environments
end

#enabled_patchesArray<Symbol>

Array of patches to apply. Default is DEFAULT_PATCHES

Returns:

  • (Array<Symbol>)


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

def enabled_patches
  @enabled_patches
end

#environmentString

RACK_ENV by default.

Returns:

  • (String)


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

def environment
  @environment
end

#exclude_loggersArray<String>

Logger ‘progname’s to exclude from breadcrumbs

Returns:

  • (Array<String>)


141
142
143
# File 'lib/sentry/configuration.rb', line 141

def exclude_loggers
  @exclude_loggers
end

#excluded_exceptionsArray<String>

Array of exception classes that should never be sent. See IGNORE_DEFAULT. You should probably append to this rather than overwrite it.

Returns:

  • (Array<String>)


146
147
148
# File 'lib/sentry/configuration.rb', line 146

def excluded_exceptions
  @excluded_exceptions
end

#include_local_variablesBoolean Also known as: capture_exception_frame_locals

Whether to capture local variables from the raised exception’s frame. Default is false.

Returns:

  • (Boolean)


155
156
157
# File 'lib/sentry/configuration.rb', line 155

def include_local_variables
  @include_local_variables
end

#inspect_exception_causes_for_exclusionBoolean Also known as: inspect_exception_causes_for_exclusion?

Boolean to check nested exceptions when deciding if to exclude. Defaults to true

Returns:

  • (Boolean)


150
151
152
# File 'lib/sentry/configuration.rb', line 150

def inspect_exception_causes_for_exclusion
  @inspect_exception_causes_for_exclusion
end

#instrumenterSymbol

The instrumenter to use, :sentry or :otel

Returns:

  • (Symbol)


292
293
294
# File 'lib/sentry/configuration.rb', line 292

def instrumenter
  @instrumenter
end

#linecacheLineCache

You may provide your own LineCache for matching paths with source files. This may be useful if you need to get source code from places other than the disk.

Returns:

See Also:



181
182
183
# File 'lib/sentry/configuration.rb', line 181

def linecache
  @linecache
end

#loggerLogger

Logger used by Sentry. In Rails, this is the Rails logger, otherwise Sentry provides its own Sentry::Logger.

Returns:



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

def logger
  @logger
end

#max_breadcrumbsInteger

Max number of breadcrumbs a breadcrumb buffer can hold

Returns:

  • (Integer)


116
117
118
# File 'lib/sentry/configuration.rb', line 116

def max_breadcrumbs
  @max_breadcrumbs
end

#metricsMetrics::Configuration (readonly)

Metrics related configuration.



249
250
251
# File 'lib/sentry/configuration.rb', line 249

def metrics
  @metrics
end

#profiler_classClass

The profiler class

Returns:

  • (Class)


296
297
298
# File 'lib/sentry/configuration.rb', line 296

def profiler_class
  @profiler_class
end

#profiles_sample_rateFloat?

Take a float between 0.0 and 1.0 as the sample rate for capturing profiles. Note that this rate is relative to traces_sample_rate / traces_sampler, i.e. the profile is sampled by this rate after the transaction is sampled.

Returns:

  • (Float, nil)


302
303
304
# File 'lib/sentry/configuration.rb', line 302

def profiles_sample_rate
  @profiles_sample_rate
end

#project_rootString

Project directory root for in_app detection. Could be Rails root, etc. Set automatically for Rails.

Returns:

  • (String)


191
192
193
# File 'lib/sentry/configuration.rb', line 191

def project_root
  @project_root
end

#propagate_tracesBoolean

Insert sentry-trace to outgoing requests’ headers

Returns:

  • (Boolean)


200
201
202
# File 'lib/sentry/configuration.rb', line 200

def propagate_traces
  @propagate_traces
end

#rack_env_whitelistArray<String>

Array of rack env parameters to be included in the event sent to sentry.

Returns:

  • (Array<String>)


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

def rack_env_whitelist
  @rack_env_whitelist
end

#releaseString

Release tag to be passed with every event sent to Sentry. We automatically try to set this to a git SHA or Capistrano release.

Returns:

  • (String)


209
210
211
# File 'lib/sentry/configuration.rb', line 209

def release
  @release
end

#sample_rateFloat

The sampling factor to apply to events. A value of 0.0 will not send any events, and a value of 1.0 will send 100% of events.

Returns:

  • (Float)


214
215
216
# File 'lib/sentry/configuration.rb', line 214

def sample_rate
  @sample_rate
end

#send_client_reportsBoolean

Send diagnostic client reports about dropped events, true by default tries to attach to an existing envelope max once every 30s

Returns:

  • (Boolean)


273
274
275
# File 'lib/sentry/configuration.rb', line 273

def send_client_reports
  @send_client_reports
end

#send_default_piiBoolean

When send_default_pii’s value is false (default), sensitive information like

  • user ip

  • user cookie

  • request body

  • query string

will not be sent to Sentry.

Returns:

  • (Boolean)


227
228
229
# File 'lib/sentry/configuration.rb', line 227

def send_default_pii
  @send_default_pii
end

#send_modulesBoolean

Include module versions in reports - boolean.

Returns:

  • (Boolean)


218
219
220
# File 'lib/sentry/configuration.rb', line 218

def send_modules
  @send_modules
end

#server_nameString

Returns:

  • (String)


237
238
239
# File 'lib/sentry/configuration.rb', line 237

def server_name
  @server_name
end

#skip_rake_integrationBoolean

Allow to skip Sentry emails within rake tasks

Returns:

  • (Boolean)


231
232
233
# File 'lib/sentry/configuration.rb', line 231

def skip_rake_integration
  @skip_rake_integration
end

#spotlightBoolean, String

Whether to capture events and traces into Spotlight. Default is false. If you set this to true, Sentry will send events and traces to the local Sidecar proxy at localhost:8969/stream. If you want to use a different Sidecar proxy address, set this to String with the proxy URL.

Returns:

  • (Boolean, String)


163
164
165
# File 'lib/sentry/configuration.rb', line 163

def spotlight
  @spotlight
end

#strip_backtrace_load_pathBoolean

Whether to strip the load path while constructing the backtrace frame filename. Defaults to true.

Returns:

  • (Boolean)


196
197
198
# File 'lib/sentry/configuration.rb', line 196

def strip_backtrace_load_path
  @strip_backtrace_load_path
end

#trace_propagation_targetsArray<String, Regexp>

Allowlist of outgoing request targets to which sentry-trace and baggage headers are attached. Default is all (/.*/)

Returns:

  • (Array<String, Regexp>)


288
289
290
# File 'lib/sentry/configuration.rb', line 288

def trace_propagation_targets
  @trace_propagation_targets
end

#traces_sample_rateFloat?

Take a float between 0.0 and 1.0 as the sample rate for tracing events (transactions).

Returns:

  • (Float, nil)


253
254
255
# File 'lib/sentry/configuration.rb', line 253

def traces_sample_rate
  @traces_sample_rate
end

#traces_samplerProc

Take a Proc that controls the sample rate for every tracing event, e.g.

Examples:

config.traces_sampler =  lambda do |tracing_context|
  # tracing_context[:transaction_context] contains the information about the transaction
  # tracing_context[:parent_sampled] contains the transaction's parent's sample decision
  true # return value can be a boolean or a float between 0.0 and 1.0
end

Returns:

  • (Proc)


263
264
265
# File 'lib/sentry/configuration.rb', line 263

def traces_sampler
  @traces_sampler
end

#transportTransport::Configuration (readonly)

Transport related configuration.



241
242
243
# File 'lib/sentry/configuration.rb', line 241

def transport
  @transport
end

#trusted_proxiesObject

IP ranges for trusted proxies that will be skipped when calculating IP address.



234
235
236
# File 'lib/sentry/configuration.rb', line 234

def trusted_proxies
  @trusted_proxies
end

Class Method Details

.add_post_initialization_callback(&block) ⇒ Object

allow extensions to add their hooks to the Configuration class



360
361
362
# File 'lib/sentry/configuration.rb', line 360

def add_post_initialization_callback(&block)
  post_initialization_callbacks << block
end

.post_initialization_callbacksObject

Post initialization callbacks are called at the end of initialization process allowing extending the configuration of sentry-ruby by multiple extensions



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

def post_initialization_callbacks
  @post_initialization_callbacks ||= []
end

Instance Method Details

#capture_exception_frame_locals=(value) ⇒ Object

Deprecated.


169
170
171
172
173
174
175
# File 'lib/sentry/configuration.rb', line 169

def capture_exception_frame_locals=(value)
  log_warn <<~MSG
    `capture_exception_frame_locals` is now deprecated in favor of `include_local_variables`.
  MSG

  self.include_local_variables = value
end

#csp_report_uriString?

Returns:

  • (String, nil)


574
575
576
577
578
579
580
581
# File 'lib/sentry/configuration.rb', line 574

def csp_report_uri
  if dsn && dsn.valid?
    uri = dsn.csp_report_uri
    uri += "&sentry_release=#{CGI.escape(release)}" if release && !release.empty?
    uri += "&sentry_environment=#{CGI.escape(environment)}" if environment && !environment.empty?
    uri
  end
end

#detect_releaseObject

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.



596
597
598
599
600
601
602
603
604
605
606
# File 'lib/sentry/configuration.rb', line 596

def detect_release
  return unless sending_allowed?

  @release ||= ReleaseDetector.detect_release(project_root: project_root, running_on_heroku: running_on_heroku?)

  if running_on_heroku? && release.nil?
    log_warn(HEROKU_DYNO_METADATA_MESSAGE)
  end
rescue => e
  log_error("Error detecting release", e, debug: debug)
end

#enabled_in_current_env?Boolean

Returns:

  • (Boolean)


552
553
554
# File 'lib/sentry/configuration.rb', line 552

def enabled_in_current_env?
  enabled_environments.empty? || enabled_environments.include?(environment)
end

#error_messagesObject

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.



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

def error_messages
  @errors = [@errors[0]] + @errors[1..-1].map(&:downcase) # fix case of all but first
  @errors.join(", ")
end

#exception_class_allowed?(exc) ⇒ Boolean

Returns:

  • (Boolean)


539
540
541
542
543
544
545
546
547
548
549
550
# File 'lib/sentry/configuration.rb', line 539

def exception_class_allowed?(exc)
  if exc.is_a?(Sentry::Error)
    # Try to prevent error reporting loops
    log_debug("Refusing to capture Sentry error: #{exc.inspect}")
    false
  elsif excluded_exception?(exc)
    log_debug("User excluded error: #{exc.inspect}")
    false
  else
    true
  end
end

#is_numeric_or_nil?(value) ⇒ Boolean

Returns:

  • (Boolean)


492
493
494
# File 'lib/sentry/configuration.rb', line 492

def is_numeric_or_nil?(value)
  value.is_a?(Numeric) || value.nil?
end

#profiling_enabled?Boolean

Returns:

  • (Boolean)


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

def profiling_enabled?
  valid_sampler = !!(valid_sample_rate?(@profiles_sample_rate))

  tracing_enabled? && valid_sampler && sending_allowed?
end

#sample_allowed?Boolean

Returns:

  • (Boolean)


529
530
531
532
533
# File 'lib/sentry/configuration.rb', line 529

def sample_allowed?
  return true if sample_rate == 1.0

  Random.rand < sample_rate
end

#sending_allowed?Boolean

Returns:

  • (Boolean)


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

def sending_allowed?
  spotlight || sending_to_dsn_allowed?
end

#sending_to_dsn_allowed?Boolean

Returns:

  • (Boolean)


523
524
525
526
527
# File 'lib/sentry/configuration.rb', line 523

def sending_to_dsn_allowed?
  @errors = []

  valid? && capture_in_environment?
end

#session_tracking?Boolean

Returns:

  • (Boolean)


535
536
537
# File 'lib/sentry/configuration.rb', line 535

def session_tracking?
  auto_session_tracking && enabled_in_current_env?
end

#stacktrace_builderObject

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.



584
585
586
587
588
589
590
591
592
593
# File 'lib/sentry/configuration.rb', line 584

def stacktrace_builder
  @stacktrace_builder ||= StacktraceBuilder.new(
    project_root: @project_root.to_s,
    app_dirs_pattern: @app_dirs_pattern,
    linecache: @linecache,
    context_lines: @context_lines,
    backtrace_cleanup_callback: @backtrace_cleanup_callback,
    strip_backtrace_load_path: @strip_backtrace_load_path
  )
end

#tracing_enabled?Boolean

Returns:

  • (Boolean)


561
562
563
564
565
# File 'lib/sentry/configuration.rb', line 561

def tracing_enabled?
  valid_sampler = !!((valid_sample_rate?(@traces_sample_rate)) || @traces_sampler)

  (@enable_tracing != false) && valid_sampler && sending_allowed?
end

#valid_sample_rate?(sample_rate) ⇒ Boolean

Returns:

  • (Boolean)


556
557
558
559
# File 'lib/sentry/configuration.rb', line 556

def valid_sample_rate?(sample_rate)
  return false unless sample_rate.is_a?(Numeric)
  sample_rate >= 0.0 && sample_rate <= 1.0
end