sentry-ruby-core 4.8.0 → 4.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f675111daf93ba05db7de62dcfa1dd9268f6ba009265de08e0e4f118ffea0c62
-  data.tar.gz: 2ece2ccaf14be6cc5fa762b77a57cd63dcc3fe52a03987c8c4136a43ec62bbd1
+  metadata.gz: acac59016a784fe97a900098b0dbd42d74996a3193d8e8f6026da3d097593d19
+  data.tar.gz: 2e670fbe76abfbd62e0c45e5272929a5cce1ba3ffb556afb68b50f35b4969be3
 SHA512:
-  metadata.gz: d5d9405c41879a40ba0c0205fa08e38fa5b3ed243276181239be63f0baa0b739b37ac91ecb86abd76768c4c5a706f1f7b7e47d7eadd357f2116ec2ec9bd913d5
-  data.tar.gz: abb46869f2eba00f053096e5568829815b02520db31fe9c98bbfabea40b5dcbe6d438ca97287ca7f9b4fee9a4710b49dec73b9196a3650d3a811184a960a09a7
+  metadata.gz: 68fd8755acacba19433d948722cb02a751c61ea822360a6dcfb245a9657f197df08f11ceef800f6db06bc75b4c5e39862b8d2f2cb88c0f844718bccf2dffec77
+  data.tar.gz: f3083e8f467ecc06c878aa568c01dfcfd4c793da989196f1397684ef0276107b2500eeb2233557e34a55ad6e7a53e9110fcfb06ccb68077cac63d1f3810ae3b4

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "concurrent/executor/thread_pool_executor"
 require "concurrent/executor/immediate_executor"
 require "concurrent/configuration"
@@ -6,12 +8,18 @@ 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)
       @max_queue = 30
+      @shutdown_timeout = 1
       @number_of_threads = configuration.background_worker_threads
       @logger = configuration.logger
+      @debug = configuration.debug
+      @shutdown_callback = nil
 
       @executor =
         if configuration.async
@@ -23,19 +31,41 @@ module Sentry
         else
           log_debug("initialized a background worker with #{@number_of_threads} threads")
 
-          Concurrent::ThreadPoolExecutor.new(
+          executor = Concurrent::ThreadPoolExecutor.new(
             min_threads: 0,
             max_threads: @number_of_threads,
             max_queue: @max_queue,
             fallback_policy: :discard
           )
+
+          @shutdown_callback = proc do
+            executor.shutdown
+            executor.wait_for_termination(@shutdown_timeout)
+          end
+
+          executor
         end
     end
 
+    # if you want to monkey-patch this method, please override `_perform` instead
     def perform(&block)
       @executor.post do
-        block.call
+        begin
+          _perform(&block)
+        rescue Exception => e
+          log_error("exception happened in background worker", e, debug: @debug)
+        end
       end
     end
+
+    def shutdown
+      @shutdown_callback&.call
+    end
+
+    private
+
+    def _perform(&block)
+      block.call
+    end
   end
 end

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/sentry_logger.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'logger'
 
 module Sentry

data/lib/sentry/breadcrumb.rb

@@ -1,10 +1,28 @@
+# frozen_string_literal: true
+
 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 || {}
@@ -14,6 +32,7 @@ module Sentry
       self.message = message
     end
 
+    # @return [Hash]
     def to_hash
       {
         category: @category,
@@ -25,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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "sentry/breadcrumb"
 
 module Sentry
@@ -5,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

@@ -1,11 +1,22 @@
+# frozen_string_literal: true
+
 require "sentry/transport"
 
 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
@@ -23,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?
 
@@ -55,6 +71,10 @@ 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 = {})
       integration_meta = Sentry.integrations[hint[:integration]]
       return unless @configuration.exception_class_allowed?(exception)
@@ -65,6 +85,10 @@ 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)
       integration_meta = Sentry.integrations[hint[:integration]]
       event = Event.new(configuration: configuration, integration_meta: integration_meta, message: message)
@@ -72,6 +96,9 @@ module Sentry
       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
@@ -84,6 +111,7 @@ module Sentry
       end
     end
 
+    # @!macro send_event
     def send_event(event, hint = nil)
       event_type = event.is_a?(Event) ? event.type : event["type"]
 
@@ -110,6 +138,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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "concurrent/utility/processor_counter"
 
 require "sentry/utils/exception_cause_chain"
@@ -15,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
@@ -28,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
@@ -285,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
@@ -311,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,
@@ -321,6 +370,7 @@ module Sentry
       )
     end
 
+    # @api private
     def detect_release
       return unless sending_allowed?
 
@@ -333,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/core_ext/object/deep_dup.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 return if Object.method_defined?(:deep_dup)
 
 require 'sentry/core_ext/object/duplicable'

data/lib/sentry/core_ext/object/duplicable.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 return if Object.method_defined?(:duplicable?)
 
 #########################################

data/lib/sentry/dsn.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "uri"
 
 module Sentry

data/lib/sentry/envelope.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Sentry
+  # @api private
+  class Envelope
+    def initialize(headers)
+      @headers = headers
+      @items = []
+    end
+
+    def add_item(headers, payload)
+      @items << [headers, payload]
+    end
+
+    def to_s
+      payload = @items.map do |item_headers, item_payload|
+        <<~ENVELOPE
+          #{JSON.generate(item_headers)}
+          #{JSON.generate(item_payload)}
+        ENVELOPE
+      end.join("\n")
+
+      "#{JSON.generate(@headers)}\n#{payload}"
+    end
+  end
+end