sentry-ruby-core 4.8.1 → 4.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c0d62d3133d461116b39ce7e822a3cc523c378417eafade8b3a904f76bce5289
-  data.tar.gz: 4ae280d6e7d88107e7f34f0794d266182d1c801407373023293c38db038aae50
+  metadata.gz: 581302d8f4b4352dad44e05ccf4bbd052b2444940cde2712dbeb7ba79db8dd6d
+  data.tar.gz: ede4e7f3a4d8c156f19c336fbd52862b84c1ef60e42bdf8e55d491f3634da7c7
 SHA512:
-  metadata.gz: 8027f22238a8012bb1aca95d528cb479e287a5b6b17269c9789056d6959f33cab558fac3166147b82b2bda7ee6ad87f4d484ad83634d41804bf198ea7fddd7b2
-  data.tar.gz: ea6681465bf4f538139b0ba6057ea34dec7cb848e77be48ca65c5d7ee5080c492f324dda7903f40d1db275d4bea4f3887048ebf144d7748d02be35314e5fb977
+  metadata.gz: '02219e1309e5d539c5229ff74aac3e0377cd1480a20b99d6cc9a690e9d16967a742e0f2f5d599ec30e0ee303109b5975b342ea9645f90c4bc24111ee4beec777'
+  data.tar.gz: 76a5a05b324edb0571d1fe61104554444db6210f0ce76b9028e8665fcf2f083fbfa967bb941997006017931d84fdab7d3e45ee1c038d25939f1cd4a8c57ff2e8

data/.yardopts

@@ -0,0 +1,2 @@
+--exclude lib/sentry/utils/
+--exclude lib/sentry/core_ext

data/Gemfile

@@ -22,3 +22,5 @@ gem "benchmark-ips"
 gem "benchmark_driver"
 gem "benchmark-ipsa"
 gem "benchmark-memory"
+
+gem "yard", "~> 0.9.27"

data/README.md

@@ -78,6 +78,8 @@ end
 
 To learn more about sampling transactions, please visit the [official documentation](https://docs.sentry.io/platforms/ruby/configuration/sampling/#configuring-the-transaction-sample-rate).
 
+### [Migration Guide](https://docs.sentry.io/platforms/ruby/migration/)
+
 ### Integrations
 
 - [Rack](https://docs.sentry.io/platforms/ruby/guides/rack/)

data/lib/sentry/background_worker.rb

@@ -8,7 +8,9 @@ module Sentry
   class BackgroundWorker
     include LoggingHelper
 
-    attr_reader :max_queue, :number_of_threads, :logger
+    attr_reader :max_queue, :number_of_threads
+    # @deprecated Use Sentry.logger to retrieve the current logger instead.
+    attr_reader :logger
     attr_accessor :shutdown_timeout
 
     def initialize(configuration)

data/lib/sentry/backtrace.rb

@@ -1,9 +1,7 @@
 # frozen_string_literal: true
 
-## Inspired by Rails' and Airbrake's backtrace parsers.
-
 module Sentry
-  # Front end to parsing the backtrace for each notice
+  # @api private
   class Backtrace
     # Handles backtrace parsing line by line
     class Line

data/lib/sentry/breadcrumb.rb

@@ -4,9 +4,25 @@ module Sentry
   class Breadcrumb
     DATA_SERIALIZATION_ERROR_MESSAGE = "[data were removed due to serialization issues]"
 
-    attr_accessor :category, :data, :level, :timestamp, :type
+    # @return [String, nil]
+    attr_accessor :category
+    # @return [Hash, nil]
+    attr_accessor :data
+    # @return [String, nil]
+    attr_accessor :level
+    # @return [Time, Integer, nil]
+    attr_accessor :timestamp
+    # @return [String, nil]
+    attr_accessor :type
+    # @return [String, nil]
     attr_reader :message
 
+    # @param category [String, nil]
+    # @param data [Hash, nil]
+    # @param message [String, nil]
+    # @param timestamp [Time, Integer, nil]
+    # @param level [String, nil]
+    # @param type [String, nil]
     def initialize(category: nil, data: nil, message: nil, timestamp: nil, level: nil, type: nil)
       @category = category
       @data = data || {}
@@ -16,6 +32,7 @@ module Sentry
       self.message = message
     end
 
+    # @return [Hash]
     def to_hash
       {
         category: @category,
@@ -27,8 +44,10 @@ module Sentry
       }
     end
 
-    def message=(msg)
-      @message = (msg || "").byteslice(0..Event::MAX_MESSAGE_SIZE_IN_BYTES)
+    # @param message [String]
+    # @return [void]
+    def message=(message)
+      @message = (message || "").byteslice(0..Event::MAX_MESSAGE_SIZE_IN_BYTES)
     end
 
     private

data/lib/sentry/breadcrumb_buffer.rb

@@ -7,40 +7,54 @@ module Sentry
     DEFAULT_SIZE = 100
     include Enumerable
 
+    # @return [Array]
     attr_accessor :buffer
 
+    # @param size [Integer, nil] If it's not provided, it'll fallback to DEFAULT_SIZE
     def initialize(size = nil)
       @buffer = Array.new(size || DEFAULT_SIZE)
     end
 
+    # @param crumb [Breadcrumb]
+    # @return [void]
     def record(crumb)
       yield(crumb) if block_given?
       @buffer.slice!(0)
       @buffer << crumb
     end
 
+    # @return [Array]
     def members
       @buffer.compact
     end
 
+    # Returns the last breadcrumb stored in the buffer. If the buffer it's empty, it returns nil.
+    # @return [Breadcrumb, nil]
     def peek
       members.last
     end
 
+    # Iterates through all breadcrumbs.
+    # @param block [Proc]
+    # @yieldparam crumb [Breadcrumb]
+    # @return [Array]
     def each(&block)
       members.each(&block)
     end
 
+    # @return [Boolean]
     def empty?
       members.none?
     end
 
+    # @return [Hash]
     def to_hash
       {
         values: members.map(&:to_hash)
       }
     end
 
+    # @return [BreadcrumbBuffer]
     def dup
       copy = super
       copy.buffer = buffer.deep_dup

data/lib/sentry/client.rb

@@ -6,8 +6,17 @@ module Sentry
   class Client
     include LoggingHelper
 
-    attr_reader :transport, :configuration, :logger
+    # The Transport object that'll send events for the client.
+    # @return [Transport]
+    attr_reader :transport
 
+    # @!macro configuration
+    attr_reader :configuration
+
+    # @deprecated Use Sentry.logger to retrieve the current logger instead.
+    attr_reader :logger
+
+    # @param configuration [Configuration]
     def initialize(configuration)
       @configuration = configuration
       @logger = configuration.logger
@@ -25,6 +34,11 @@ module Sentry
       end
     end
 
+    # Applies the given scope's data to the event and sends it to Sentry.
+    # @param event [Event] the event to be sent.
+    # @param scope [Scope] the scope with contextual data that'll be applied to the event before it's sent.
+    # @param hint [Hash] the hint data that'll be passed to `before_send` callback and the scope's event processors.
+    # @return [Event, nil]
     def capture_event(event, scope, hint = {})
       return unless configuration.sending_allowed?
 
@@ -57,9 +71,14 @@ module Sentry
       nil
     end
 
+    # Initializes an Event object with the given exception. Returns `nil` if the exception's class is excluded from reporting.
+    # @param exception [Exception] the exception to be reported.
+    # @param hint [Hash] the hint data that'll be passed to `before_send` callback and the scope's event processors.
+    # @return [Event, nil]
     def event_from_exception(exception, hint = {})
+      return unless @configuration.sending_allowed? && @configuration.exception_class_allowed?(exception)
+
       integration_meta = Sentry.integrations[hint[:integration]]
-      return unless @configuration.exception_class_allowed?(exception)
 
       Event.new(configuration: configuration, integration_meta: integration_meta).tap do |event|
         event.add_exception_interface(exception)
@@ -67,13 +86,22 @@ module Sentry
       end
     end
 
+    # Initializes an Event object with the given message.
+    # @param message [String] the message to be reported.
+    # @param hint [Hash] the hint data that'll be passed to `before_send` callback and the scope's event processors.
+    # @return [Event]
     def event_from_message(message, hint = {}, backtrace: nil)
+      return unless @configuration.sending_allowed?
+
       integration_meta = Sentry.integrations[hint[:integration]]
       event = Event.new(configuration: configuration, integration_meta: integration_meta, message: message)
       event.add_threads_interface(backtrace: backtrace || caller)
       event
     end
 
+    # Initializes an Event object with the given Transaction object.
+    # @param transaction [Transaction] the transaction to be recorded.
+    # @return [TransactionEvent]
     def event_from_transaction(transaction)
       TransactionEvent.new(configuration: configuration).tap do |event|
         event.transaction = transaction.name
@@ -86,6 +114,7 @@ module Sentry
       end
     end
 
+    # @!macro send_event
     def send_event(event, hint = nil)
       event_type = event.is_a?(Event) ? event.type : event["type"]
 
@@ -112,6 +141,10 @@ module Sentry
       raise
     end
 
+    # Generates a Sentry trace for distribted tracing from the given Span.
+    # Returns `nil` if `config.propagate_traces` is `false`.
+    # @param span [Span] the span to generate trace from.
+    # @return [String, nil]
     def generate_sentry_trace(span)
       return unless configuration.propagate_traces
 

data/lib/sentry/configuration.rb

@@ -17,10 +17,15 @@ module Sentry
     # 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)/
+    #
+    # @return [Regexp, nil]
     attr_accessor :app_dirs_pattern
 
     # Provide an object that responds to `call` to send events asynchronously.
     # E.g.: lambda { |event| Thread.new { Sentry.send_event(event) } }
+    #
+    # @deprecated It will be removed in the next major release. Please read https://github.com/getsentry/sentry-ruby/issues/1522 for more information
+    # @return [Proc, nil]
     attr_reader :async
 
     # to send events in a non-blocking way, sentry-ruby has its own background worker
@@ -30,143 +35,179 @@ module Sentry
     #
     # if you want to send events synchronously, set the value to 0
     # E.g.: config.background_worker_threads = 0
+    # @return [Integer]
     attr_accessor :background_worker_threads
 
     # a proc/lambda that takes an array of stack traces
     # it'll be used to silence (reduce) backtrace of the exception
     #
-    # for example:
-    #
-    # ```ruby
-    # Sentry.configuration.backtrace_cleanup_callback = lambda do |backtrace|
-    #   Rails.backtrace_cleaner.clean(backtrace)
-    # end
-    # ```
+    # @example
+    #   config.backtrace_cleanup_callback = lambda do |backtrace|
+    #     Rails.backtrace_cleaner.clean(backtrace)
+    #   end
     #
+    # @return [Proc, nil]
     attr_accessor :backtrace_cleanup_callback
 
     # Optional Proc, called before adding the breadcrumb to the current scope
-    # E.g.: lambda { |breadcrumb, hint| breadcrumb }
-    # E.g.: lambda { |breadcrumb, hint| nil }
-    # E.g.: lambda { |breadcrumb, hint|
-    #   breadcrumb.message = 'a'
-    #   breadcrumb
-    # }
+    # @example
+    #   config.before = lambda do |breadcrumb, hint|
+    #     breadcrumb.message = 'a'
+    #     breadcrumb
+    #   end
+    # @return [Proc]
     attr_reader :before_breadcrumb
 
-    # Optional Proc, called before sending an event to the server/
-    # E.g.: lambda { |event, hint| event }
-    # E.g.: lambda { |event, hint| nil }
-    # E.g.: lambda { |event, hint|
-    #   event[:message] = 'a'
-    #   event
-    # }
+    # Optional Proc, called before sending an event to the server
+    # @example
+    #   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
+    # @return [Proc]
     attr_reader :before_send
 
     # An array of breadcrumbs loggers to be used. Available options are:
     # - :sentry_logger
+    # - :http_logger
+    #
+    # And if you also use sentry-rails:
     # - :active_support_logger
+    # - :monotonic_active_support_logger
+    #
+    # @return [Array<Symbol>]
     attr_reader :breadcrumbs_logger
 
     # Whether to capture local variables from the raised exception's frame. Default is false.
+    # @return [Boolean]
     attr_accessor :capture_exception_frame_locals
 
     # Max number of breadcrumbs a breadcrumb buffer can hold
+    # @return [Integer]
     attr_accessor :max_breadcrumbs
 
     # Number of lines of code context to capture, or nil for none
+    # @return [Integer, nil]
     attr_accessor :context_lines
 
     # RACK_ENV by default.
+    # @return [String]
     attr_reader :environment
 
     # Whether the SDK should run in the debugging mode. Default is false.
     # If set to true, SDK errors will be logged with backtrace
+    # @return [Boolean]
     attr_accessor :debug
 
     # the dsn value, whether it's set via `config.dsn=` or `ENV["SENTRY_DSN"]`
+    # @return [String]
     attr_reader :dsn
 
     # Whitelist of enabled_environments that will send notifications to Sentry. Array of Strings.
+    # @return [Array<String>]
     attr_accessor :enabled_environments
 
     # Logger 'progname's to exclude from breadcrumbs
+    # @return [Array<String>]
     attr_accessor :exclude_loggers
 
     # Array of exception classes that should never be sent. See IGNORE_DEFAULT.
     # You should probably append to this rather than overwrite it.
+    # @return [Array<String>]
     attr_accessor :excluded_exceptions
 
     # Boolean to check nested exceptions when deciding if to exclude. Defaults to true
+    # @return [Boolean]
     attr_accessor :inspect_exception_causes_for_exclusion
     alias inspect_exception_causes_for_exclusion? inspect_exception_causes_for_exclusion
 
     # 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. See Sentry::LineCache for the required interface you must implement.
+    # This may be useful if you need to get source code from places other than the disk.
+    # @see LineCache
+    # @return [LineCache]
     attr_accessor :linecache
 
     # Logger used by Sentry. In Rails, this is the Rails logger, otherwise
     # Sentry provides its own Sentry::Logger.
+    # @return [Logger]
     attr_accessor :logger
 
     # Project directory root for in_app detection. Could be Rails root, etc.
     # Set automatically for Rails.
+    # @return [String]
     attr_accessor :project_root
 
     # Insert sentry-trace to outgoing requests' headers
+    # @return [Boolean]
     attr_accessor :propagate_traces
 
     # Array of rack env parameters to be included in the event sent to sentry.
+    # @return [Array<String>]
     attr_accessor :rack_env_whitelist
 
     # Release tag to be passed with every event sent to Sentry.
     # We automatically try to set this to a git SHA or Capistrano release.
+    # @return [String]
     attr_accessor :release
 
     # 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.
+    # @return [Float]
     attr_accessor :sample_rate
 
     # Include module versions in reports - boolean.
+    # @return [Boolean]
     attr_accessor :send_modules
 
     # 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.
+    # @return [Boolean]
     attr_accessor :send_default_pii
 
     # Allow to skip Sentry emails within rake tasks
+    # @return [Boolean]
     attr_accessor :skip_rake_integration
 
     # IP ranges for trusted proxies that will be skipped when calculating IP address.
     attr_accessor :trusted_proxies
 
+    # @return [String]
     attr_accessor :server_name
 
     # Return a Transport::Configuration object for transport-related configurations.
+    # @return [Transport]
     attr_reader :transport
 
     # Take a float between 0.0 and 1.0 as the sample rate for tracing events (transactions).
+    # @return [Float]
     attr_accessor :traces_sample_rate
 
     # Take a Proc that controls the sample rate for every tracing event, e.g.
-    # ```
-    # 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
-    # ```
+    # @example
+    #   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
+    # @return [Proc]
     attr_accessor :traces_sampler
 
     # Send diagnostic client reports about dropped events, true by default
     # tries to attach to an existing envelope max once every 30s
+    # @return [Boolean]
     attr_accessor :send_client_reports
 
     # these are not config options
+    # @!visibility private
     attr_reader :errors, :gem_specs
 
     # Most of these errors generate 4XX responses. In general, Sentry clients
@@ -287,11 +328,6 @@ module Sentry
       Random.rand < sample_rate
     end
 
-    def error_messages
-      @errors = [@errors[0]] + @errors[1..-1].map(&:downcase) # fix case of all but first
-      @errors.join(", ")
-    end
-
     def exception_class_allowed?(exc)
       if exc.is_a?(Sentry::Error)
         # Try to prevent error reporting loops
@@ -313,6 +349,17 @@ module Sentry
       !!((@traces_sample_rate && @traces_sample_rate >= 0.0 && @traces_sample_rate <= 1.0) || @traces_sampler) && sending_allowed?
     end
 
+    # @return [String, nil]
+    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
+
+    # @api private
     def stacktrace_builder
       @stacktrace_builder ||= StacktraceBuilder.new(
         project_root: @project_root.to_s,
@@ -323,6 +370,7 @@ module Sentry
       )
     end
 
+    # @api private
     def detect_release
       return unless sending_allowed?
 
@@ -335,13 +383,10 @@ module Sentry
       log_error("Error detecting release", e, debug: debug)
     end
 
-    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
+    # @api private
+    def error_messages
+      @errors = [@errors[0]] + @errors[1..-1].map(&:downcase) # fix case of all but first
+      @errors.join(", ")
     end
 
     private

data/lib/sentry/envelope.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Sentry
+  # @api private
   class Envelope
     def initialize(headers)
       @headers = headers