sentry-ruby-core 4.8.1 → 4.9.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: c0d62d3133d461116b39ce7e822a3cc523c378417eafade8b3a904f76bce5289
4
- data.tar.gz: 4ae280d6e7d88107e7f34f0794d266182d1c801407373023293c38db038aae50
3
+ metadata.gz: 581302d8f4b4352dad44e05ccf4bbd052b2444940cde2712dbeb7ba79db8dd6d
4
+ data.tar.gz: ede4e7f3a4d8c156f19c336fbd52862b84c1ef60e42bdf8e55d491f3634da7c7
5
5
  SHA512:
6
- metadata.gz: 8027f22238a8012bb1aca95d528cb479e287a5b6b17269c9789056d6959f33cab558fac3166147b82b2bda7ee6ad87f4d484ad83634d41804bf198ea7fddd7b2
7
- data.tar.gz: ea6681465bf4f538139b0ba6057ea34dec7cb848e77be48ca65c5d7ee5080c492f324dda7903f40d1db275d4bea4f3887048ebf144d7748d02be35314e5fb977
6
+ metadata.gz: '02219e1309e5d539c5229ff74aac3e0377cd1480a20b99d6cc9a690e9d16967a742e0f2f5d599ec30e0ee303109b5975b342ea9645f90c4bc24111ee4beec777'
7
+ data.tar.gz: 76a5a05b324edb0571d1fe61104554444db6210f0ce76b9028e8665fcf2f083fbfa967bb941997006017931d84fdab7d3e45ee1c038d25939f1cd4a8c57ff2e8
data/.yardopts ADDED
@@ -0,0 +1,2 @@
1
+ --exclude lib/sentry/utils/
2
+ --exclude lib/sentry/core_ext
data/Gemfile CHANGED
@@ -22,3 +22,5 @@ gem "benchmark-ips"
22
22
  gem "benchmark_driver"
23
23
  gem "benchmark-ipsa"
24
24
  gem "benchmark-memory"
25
+
26
+ gem "yard", "~> 0.9.27"
data/README.md CHANGED
@@ -78,6 +78,8 @@ end
78
78
 
79
79
  To learn more about sampling transactions, please visit the [official documentation](https://docs.sentry.io/platforms/ruby/configuration/sampling/#configuring-the-transaction-sample-rate).
80
80
 
81
+ ### [Migration Guide](https://docs.sentry.io/platforms/ruby/migration/)
82
+
81
83
  ### Integrations
82
84
 
83
85
  - [Rack](https://docs.sentry.io/platforms/ruby/guides/rack/)
@@ -8,7 +8,9 @@ module Sentry
8
8
  class BackgroundWorker
9
9
  include LoggingHelper
10
10
 
11
- attr_reader :max_queue, :number_of_threads, :logger
11
+ attr_reader :max_queue, :number_of_threads
12
+ # @deprecated Use Sentry.logger to retrieve the current logger instead.
13
+ attr_reader :logger
12
14
  attr_accessor :shutdown_timeout
13
15
 
14
16
  def initialize(configuration)
@@ -1,9 +1,7 @@
1
1
  # frozen_string_literal: true
2
2
 
3
- ## Inspired by Rails' and Airbrake's backtrace parsers.
4
-
5
3
  module Sentry
6
- # Front end to parsing the backtrace for each notice
4
+ # @api private
7
5
  class Backtrace
8
6
  # Handles backtrace parsing line by line
9
7
  class Line
@@ -4,9 +4,25 @@ module Sentry
4
4
  class Breadcrumb
5
5
  DATA_SERIALIZATION_ERROR_MESSAGE = "[data were removed due to serialization issues]"
6
6
 
7
- attr_accessor :category, :data, :level, :timestamp, :type
7
+ # @return [String, nil]
8
+ attr_accessor :category
9
+ # @return [Hash, nil]
10
+ attr_accessor :data
11
+ # @return [String, nil]
12
+ attr_accessor :level
13
+ # @return [Time, Integer, nil]
14
+ attr_accessor :timestamp
15
+ # @return [String, nil]
16
+ attr_accessor :type
17
+ # @return [String, nil]
8
18
  attr_reader :message
9
19
 
20
+ # @param category [String, nil]
21
+ # @param data [Hash, nil]
22
+ # @param message [String, nil]
23
+ # @param timestamp [Time, Integer, nil]
24
+ # @param level [String, nil]
25
+ # @param type [String, nil]
10
26
  def initialize(category: nil, data: nil, message: nil, timestamp: nil, level: nil, type: nil)
11
27
  @category = category
12
28
  @data = data || {}
@@ -16,6 +32,7 @@ module Sentry
16
32
  self.message = message
17
33
  end
18
34
 
35
+ # @return [Hash]
19
36
  def to_hash
20
37
  {
21
38
  category: @category,
@@ -27,8 +44,10 @@ module Sentry
27
44
  }
28
45
  end
29
46
 
30
- def message=(msg)
31
- @message = (msg || "").byteslice(0..Event::MAX_MESSAGE_SIZE_IN_BYTES)
47
+ # @param message [String]
48
+ # @return [void]
49
+ def message=(message)
50
+ @message = (message || "").byteslice(0..Event::MAX_MESSAGE_SIZE_IN_BYTES)
32
51
  end
33
52
 
34
53
  private
@@ -7,40 +7,54 @@ module Sentry
7
7
  DEFAULT_SIZE = 100
8
8
  include Enumerable
9
9
 
10
+ # @return [Array]
10
11
  attr_accessor :buffer
11
12
 
13
+ # @param size [Integer, nil] If it's not provided, it'll fallback to DEFAULT_SIZE
12
14
  def initialize(size = nil)
13
15
  @buffer = Array.new(size || DEFAULT_SIZE)
14
16
  end
15
17
 
18
+ # @param crumb [Breadcrumb]
19
+ # @return [void]
16
20
  def record(crumb)
17
21
  yield(crumb) if block_given?
18
22
  @buffer.slice!(0)
19
23
  @buffer << crumb
20
24
  end
21
25
 
26
+ # @return [Array]
22
27
  def members
23
28
  @buffer.compact
24
29
  end
25
30
 
31
+ # Returns the last breadcrumb stored in the buffer. If the buffer it's empty, it returns nil.
32
+ # @return [Breadcrumb, nil]
26
33
  def peek
27
34
  members.last
28
35
  end
29
36
 
37
+ # Iterates through all breadcrumbs.
38
+ # @param block [Proc]
39
+ # @yieldparam crumb [Breadcrumb]
40
+ # @return [Array]
30
41
  def each(&block)
31
42
  members.each(&block)
32
43
  end
33
44
 
45
+ # @return [Boolean]
34
46
  def empty?
35
47
  members.none?
36
48
  end
37
49
 
50
+ # @return [Hash]
38
51
  def to_hash
39
52
  {
40
53
  values: members.map(&:to_hash)
41
54
  }
42
55
  end
43
56
 
57
+ # @return [BreadcrumbBuffer]
44
58
  def dup
45
59
  copy = super
46
60
  copy.buffer = buffer.deep_dup
data/lib/sentry/client.rb CHANGED
@@ -6,8 +6,17 @@ module Sentry
6
6
  class Client
7
7
  include LoggingHelper
8
8
 
9
- attr_reader :transport, :configuration, :logger
9
+ # The Transport object that'll send events for the client.
10
+ # @return [Transport]
11
+ attr_reader :transport
10
12
 
13
+ # @!macro configuration
14
+ attr_reader :configuration
15
+
16
+ # @deprecated Use Sentry.logger to retrieve the current logger instead.
17
+ attr_reader :logger
18
+
19
+ # @param configuration [Configuration]
11
20
  def initialize(configuration)
12
21
  @configuration = configuration
13
22
  @logger = configuration.logger
@@ -25,6 +34,11 @@ module Sentry
25
34
  end
26
35
  end
27
36
 
37
+ # Applies the given scope's data to the event and sends it to Sentry.
38
+ # @param event [Event] the event to be sent.
39
+ # @param scope [Scope] the scope with contextual data that'll be applied to the event before it's sent.
40
+ # @param hint [Hash] the hint data that'll be passed to `before_send` callback and the scope's event processors.
41
+ # @return [Event, nil]
28
42
  def capture_event(event, scope, hint = {})
29
43
  return unless configuration.sending_allowed?
30
44
 
@@ -57,9 +71,14 @@ module Sentry
57
71
  nil
58
72
  end
59
73
 
74
+ # Initializes an Event object with the given exception. Returns `nil` if the exception's class is excluded from reporting.
75
+ # @param exception [Exception] the exception to be reported.
76
+ # @param hint [Hash] the hint data that'll be passed to `before_send` callback and the scope's event processors.
77
+ # @return [Event, nil]
60
78
  def event_from_exception(exception, hint = {})
79
+ return unless @configuration.sending_allowed? && @configuration.exception_class_allowed?(exception)
80
+
61
81
  integration_meta = Sentry.integrations[hint[:integration]]
62
- return unless @configuration.exception_class_allowed?(exception)
63
82
 
64
83
  Event.new(configuration: configuration, integration_meta: integration_meta).tap do |event|
65
84
  event.add_exception_interface(exception)
@@ -67,13 +86,22 @@ module Sentry
67
86
  end
68
87
  end
69
88
 
89
+ # Initializes an Event object with the given message.
90
+ # @param message [String] the message to be reported.
91
+ # @param hint [Hash] the hint data that'll be passed to `before_send` callback and the scope's event processors.
92
+ # @return [Event]
70
93
  def event_from_message(message, hint = {}, backtrace: nil)
94
+ return unless @configuration.sending_allowed?
95
+
71
96
  integration_meta = Sentry.integrations[hint[:integration]]
72
97
  event = Event.new(configuration: configuration, integration_meta: integration_meta, message: message)
73
98
  event.add_threads_interface(backtrace: backtrace || caller)
74
99
  event
75
100
  end
76
101
 
102
+ # Initializes an Event object with the given Transaction object.
103
+ # @param transaction [Transaction] the transaction to be recorded.
104
+ # @return [TransactionEvent]
77
105
  def event_from_transaction(transaction)
78
106
  TransactionEvent.new(configuration: configuration).tap do |event|
79
107
  event.transaction = transaction.name
@@ -86,6 +114,7 @@ module Sentry
86
114
  end
87
115
  end
88
116
 
117
+ # @!macro send_event
89
118
  def send_event(event, hint = nil)
90
119
  event_type = event.is_a?(Event) ? event.type : event["type"]
91
120
 
@@ -112,6 +141,10 @@ module Sentry
112
141
  raise
113
142
  end
114
143
 
144
+ # Generates a Sentry trace for distribted tracing from the given Span.
145
+ # Returns `nil` if `config.propagate_traces` is `false`.
146
+ # @param span [Span] the span to generate trace from.
147
+ # @return [String, nil]
115
148
  def generate_sentry_trace(span)
116
149
  return unless configuration.propagate_traces
117
150
 
@@ -17,10 +17,15 @@ module Sentry
17
17
  # Directories to be recognized as part of your app. e.g. if you
18
18
  # have an `engines` dir at the root of your project, you may want
19
19
  # to set this to something like /(app|config|engines|lib)/
20
+ #
21
+ # @return [Regexp, nil]
20
22
  attr_accessor :app_dirs_pattern
21
23
 
22
24
  # Provide an object that responds to `call` to send events asynchronously.
23
25
  # E.g.: lambda { |event| Thread.new { Sentry.send_event(event) } }
26
+ #
27
+ # @deprecated It will be removed in the next major release. Please read https://github.com/getsentry/sentry-ruby/issues/1522 for more information
28
+ # @return [Proc, nil]
24
29
  attr_reader :async
25
30
 
26
31
  # to send events in a non-blocking way, sentry-ruby has its own background worker
@@ -30,143 +35,179 @@ module Sentry
30
35
  #
31
36
  # if you want to send events synchronously, set the value to 0
32
37
  # E.g.: config.background_worker_threads = 0
38
+ # @return [Integer]
33
39
  attr_accessor :background_worker_threads
34
40
 
35
41
  # a proc/lambda that takes an array of stack traces
36
42
  # it'll be used to silence (reduce) backtrace of the exception
37
43
  #
38
- # for example:
39
- #
40
- # ```ruby
41
- # Sentry.configuration.backtrace_cleanup_callback = lambda do |backtrace|
42
- # Rails.backtrace_cleaner.clean(backtrace)
43
- # end
44
- # ```
44
+ # @example
45
+ # config.backtrace_cleanup_callback = lambda do |backtrace|
46
+ # Rails.backtrace_cleaner.clean(backtrace)
47
+ # end
45
48
  #
49
+ # @return [Proc, nil]
46
50
  attr_accessor :backtrace_cleanup_callback
47
51
 
48
52
  # Optional Proc, called before adding the breadcrumb to the current scope
49
- # E.g.: lambda { |breadcrumb, hint| breadcrumb }
50
- # E.g.: lambda { |breadcrumb, hint| nil }
51
- # E.g.: lambda { |breadcrumb, hint|
52
- # breadcrumb.message = 'a'
53
- # breadcrumb
54
- # }
53
+ # @example
54
+ # config.before = lambda do |breadcrumb, hint|
55
+ # breadcrumb.message = 'a'
56
+ # breadcrumb
57
+ # end
58
+ # @return [Proc]
55
59
  attr_reader :before_breadcrumb
56
60
 
57
- # Optional Proc, called before sending an event to the server/
58
- # E.g.: lambda { |event, hint| event }
59
- # E.g.: lambda { |event, hint| nil }
60
- # E.g.: lambda { |event, hint|
61
- # event[:message] = 'a'
62
- # event
63
- # }
61
+ # Optional Proc, called before sending an event to the server
62
+ # @example
63
+ # config.before_send = lambda do |event, hint|
64
+ # # skip ZeroDivisionError exceptions
65
+ # # note: hint[:exception] would be a String if you use async callback
66
+ # if hint[:exception].is_a?(ZeroDivisionError)
67
+ # nil
68
+ # else
69
+ # event
70
+ # end
71
+ # end
72
+ # @return [Proc]
64
73
  attr_reader :before_send
65
74
 
66
75
  # An array of breadcrumbs loggers to be used. Available options are:
67
76
  # - :sentry_logger
77
+ # - :http_logger
78
+ #
79
+ # And if you also use sentry-rails:
68
80
  # - :active_support_logger
81
+ # - :monotonic_active_support_logger
82
+ #
83
+ # @return [Array<Symbol>]
69
84
  attr_reader :breadcrumbs_logger
70
85
 
71
86
  # Whether to capture local variables from the raised exception's frame. Default is false.
87
+ # @return [Boolean]
72
88
  attr_accessor :capture_exception_frame_locals
73
89
 
74
90
  # Max number of breadcrumbs a breadcrumb buffer can hold
91
+ # @return [Integer]
75
92
  attr_accessor :max_breadcrumbs
76
93
 
77
94
  # Number of lines of code context to capture, or nil for none
95
+ # @return [Integer, nil]
78
96
  attr_accessor :context_lines
79
97
 
80
98
  # RACK_ENV by default.
99
+ # @return [String]
81
100
  attr_reader :environment
82
101
 
83
102
  # Whether the SDK should run in the debugging mode. Default is false.
84
103
  # If set to true, SDK errors will be logged with backtrace
104
+ # @return [Boolean]
85
105
  attr_accessor :debug
86
106
 
87
107
  # the dsn value, whether it's set via `config.dsn=` or `ENV["SENTRY_DSN"]`
108
+ # @return [String]
88
109
  attr_reader :dsn
89
110
 
90
111
  # Whitelist of enabled_environments that will send notifications to Sentry. Array of Strings.
112
+ # @return [Array<String>]
91
113
  attr_accessor :enabled_environments
92
114
 
93
115
  # Logger 'progname's to exclude from breadcrumbs
116
+ # @return [Array<String>]
94
117
  attr_accessor :exclude_loggers
95
118
 
96
119
  # Array of exception classes that should never be sent. See IGNORE_DEFAULT.
97
120
  # You should probably append to this rather than overwrite it.
121
+ # @return [Array<String>]
98
122
  attr_accessor :excluded_exceptions
99
123
 
100
124
  # Boolean to check nested exceptions when deciding if to exclude. Defaults to true
125
+ # @return [Boolean]
101
126
  attr_accessor :inspect_exception_causes_for_exclusion
102
127
  alias inspect_exception_causes_for_exclusion? inspect_exception_causes_for_exclusion
103
128
 
104
129
  # You may provide your own LineCache for matching paths with source files.
105
- # This may be useful if you need to get source code from places other than
106
- # the disk. See Sentry::LineCache for the required interface you must implement.
130
+ # This may be useful if you need to get source code from places other than the disk.
131
+ # @see LineCache
132
+ # @return [LineCache]
107
133
  attr_accessor :linecache
108
134
 
109
135
  # Logger used by Sentry. In Rails, this is the Rails logger, otherwise
110
136
  # Sentry provides its own Sentry::Logger.
137
+ # @return [Logger]
111
138
  attr_accessor :logger
112
139
 
113
140
  # Project directory root for in_app detection. Could be Rails root, etc.
114
141
  # Set automatically for Rails.
142
+ # @return [String]
115
143
  attr_accessor :project_root
116
144
 
117
145
  # Insert sentry-trace to outgoing requests' headers
146
+ # @return [Boolean]
118
147
  attr_accessor :propagate_traces
119
148
 
120
149
  # Array of rack env parameters to be included in the event sent to sentry.
150
+ # @return [Array<String>]
121
151
  attr_accessor :rack_env_whitelist
122
152
 
123
153
  # Release tag to be passed with every event sent to Sentry.
124
154
  # We automatically try to set this to a git SHA or Capistrano release.
155
+ # @return [String]
125
156
  attr_accessor :release
126
157
 
127
158
  # The sampling factor to apply to events. A value of 0.0 will not send
128
159
  # any events, and a value of 1.0 will send 100% of events.
160
+ # @return [Float]
129
161
  attr_accessor :sample_rate
130
162
 
131
163
  # Include module versions in reports - boolean.
164
+ # @return [Boolean]
132
165
  attr_accessor :send_modules
133
166
 
134
167
  # When send_default_pii's value is false (default), sensitive information like
135
168
  # - user ip
136
169
  # - user cookie
137
170
  # - request body
171
+ # - query string
138
172
  # will not be sent to Sentry.
173
+ # @return [Boolean]
139
174
  attr_accessor :send_default_pii
140
175
 
141
176
  # Allow to skip Sentry emails within rake tasks
177
+ # @return [Boolean]
142
178
  attr_accessor :skip_rake_integration
143
179
 
144
180
  # IP ranges for trusted proxies that will be skipped when calculating IP address.
145
181
  attr_accessor :trusted_proxies
146
182
 
183
+ # @return [String]
147
184
  attr_accessor :server_name
148
185
 
149
186
  # Return a Transport::Configuration object for transport-related configurations.
187
+ # @return [Transport]
150
188
  attr_reader :transport
151
189
 
152
190
  # Take a float between 0.0 and 1.0 as the sample rate for tracing events (transactions).
191
+ # @return [Float]
153
192
  attr_accessor :traces_sample_rate
154
193
 
155
194
  # Take a Proc that controls the sample rate for every tracing event, e.g.
156
- # ```
157
- # lambda do |tracing_context|
158
- # # tracing_context[:transaction_context] contains the information about the transaction
159
- # # tracing_context[:parent_sampled] contains the transaction's parent's sample decision
160
- # true # return value can be a boolean or a float between 0.0 and 1.0
161
- # end
162
- # ```
195
+ # @example
196
+ # config.traces_sampler = lambda do |tracing_context|
197
+ # # tracing_context[:transaction_context] contains the information about the transaction
198
+ # # tracing_context[:parent_sampled] contains the transaction's parent's sample decision
199
+ # true # return value can be a boolean or a float between 0.0 and 1.0
200
+ # end
201
+ # @return [Proc]
163
202
  attr_accessor :traces_sampler
164
203
 
165
204
  # Send diagnostic client reports about dropped events, true by default
166
205
  # tries to attach to an existing envelope max once every 30s
206
+ # @return [Boolean]
167
207
  attr_accessor :send_client_reports
168
208
 
169
209
  # these are not config options
210
+ # @!visibility private
170
211
  attr_reader :errors, :gem_specs
171
212
 
172
213
  # Most of these errors generate 4XX responses. In general, Sentry clients
@@ -287,11 +328,6 @@ module Sentry
287
328
  Random.rand < sample_rate
288
329
  end
289
330
 
290
- def error_messages
291
- @errors = [@errors[0]] + @errors[1..-1].map(&:downcase) # fix case of all but first
292
- @errors.join(", ")
293
- end
294
-
295
331
  def exception_class_allowed?(exc)
296
332
  if exc.is_a?(Sentry::Error)
297
333
  # Try to prevent error reporting loops
@@ -313,6 +349,17 @@ module Sentry
313
349
  !!((@traces_sample_rate && @traces_sample_rate >= 0.0 && @traces_sample_rate <= 1.0) || @traces_sampler) && sending_allowed?
314
350
  end
315
351
 
352
+ # @return [String, nil]
353
+ def csp_report_uri
354
+ if dsn && dsn.valid?
355
+ uri = dsn.csp_report_uri
356
+ uri += "&sentry_release=#{CGI.escape(release)}" if release && !release.empty?
357
+ uri += "&sentry_environment=#{CGI.escape(environment)}" if environment && !environment.empty?
358
+ uri
359
+ end
360
+ end
361
+
362
+ # @api private
316
363
  def stacktrace_builder
317
364
  @stacktrace_builder ||= StacktraceBuilder.new(
318
365
  project_root: @project_root.to_s,
@@ -323,6 +370,7 @@ module Sentry
323
370
  )
324
371
  end
325
372
 
373
+ # @api private
326
374
  def detect_release
327
375
  return unless sending_allowed?
328
376
 
@@ -335,13 +383,10 @@ module Sentry
335
383
  log_error("Error detecting release", e, debug: debug)
336
384
  end
337
385
 
338
- def csp_report_uri
339
- if dsn && dsn.valid?
340
- uri = dsn.csp_report_uri
341
- uri += "&sentry_release=#{CGI.escape(release)}" if release && !release.empty?
342
- uri += "&sentry_environment=#{CGI.escape(environment)}" if environment && !environment.empty?
343
- uri
344
- end
386
+ # @api private
387
+ def error_messages
388
+ @errors = [@errors[0]] + @errors[1..-1].map(&:downcase) # fix case of all but first
389
+ @errors.join(", ")
345
390
  end
346
391
 
347
392
  private
@@ -1,6 +1,7 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module Sentry
4
+ # @api private
4
5
  class Envelope
5
6
  def initialize(headers)
6
7
  @headers = headers