sentry-ruby-core 4.8.3 → 5.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8b41956862e17f8b60319bac7a72b253889aad50b0518b4dd119bcc5da246c2c
-  data.tar.gz: 8e37db5f09d89bf1382e89744ae2a4c3a5112d4d0a5aa3f105b754974cb5d1a7
+  metadata.gz: f87f499a85374ffedb9efc48ae758ea007a44276d85af7ca7899f4d30d44cd73
+  data.tar.gz: 613088c3759d726b675992785bcfb76996227af0ac5ee04b196140b4f0d17903
 SHA512:
-  metadata.gz: 9603b5d16ee470d52fa2052a7f9156c7a2e709d906e7299e661648bec6ab56b1c076de19c8b9ea37a97dafc0f21f59dc12898e2b1bde02d14de4e725d5aa1120
-  data.tar.gz: 2c511329f550a6d9c495b55d9e40731d55e953ffc9632dcdcbfcc88266edc95287fc7d912161b853421ec0e281e9dc6dc1574d4523939b92d1c08cca569e7185
+  metadata.gz: 95bd72a765827b11e63deeb884057e3365590a96e2417185996e4bac3880c2df26daf9fcff36e1c7eb145fbe481b001e6d0113ea7caad8e0f72d88a7e4eb4446
+  data.tar.gz: 39256b355acf287b49bddb5f2e35c2c2fe761723a738165b0a79bd66927a07d5f170a7d6e5eb66dd6e019af8278dbbf0cc6a52238dafa9a3b3bd90e30b805b9e

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,6 @@
 # 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

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

@@ -46,7 +46,7 @@ module Sentry
     #     Rails.backtrace_cleaner.clean(backtrace)
     #   end
     #
-    # @return [Proc]
+    # @return [Proc, nil]
     attr_accessor :backtrace_cleanup_callback
 
     # Optional Proc, called before adding the breadcrumb to the current scope
@@ -127,8 +127,9 @@ module Sentry
     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

data/lib/sentry/event.rb

@@ -10,31 +10,40 @@ require 'sentry/utils/custom_inspection'
 
 module Sentry
   class Event
+    # These are readable attributes.
     SERIALIZEABLE_ATTRIBUTES = %i(
       event_id level timestamp
       release environment server_name modules
       message user tags contexts extra
-      fingerprint breadcrumbs backtrace transaction
+      fingerprint breadcrumbs transaction
       platform sdk type
     )
 
+    # These are writable attributes.
     WRITER_ATTRIBUTES = SERIALIZEABLE_ATTRIBUTES - %i(type timestamp level)
 
     MAX_MESSAGE_SIZE_IN_BYTES = 1024 * 8
 
-    SKIP_INSPECTION_ATTRIBUTES = [:@configuration, :@modules, :@backtrace]
+    SKIP_INSPECTION_ATTRIBUTES = [:@modules, :@stacktrace_builder, :@send_default_pii, :@trusted_proxies, :@rack_env_whitelist]
 
     include CustomInspection
 
     attr_writer(*WRITER_ATTRIBUTES)
     attr_reader(*SERIALIZEABLE_ATTRIBUTES)
 
-    attr_reader :configuration, :request, :exception, :threads
+    # @return [RequestInterface]
+    attr_reader :request
 
-    def initialize(configuration:, integration_meta: nil, message: nil)
-      # this needs to go first because some setters rely on configuration
-      @configuration = configuration
+    # @return [ExceptionInterface]
+    attr_reader :exception
+
+    # @return [ThreadsInterface]
+    attr_reader :threads
 
+    # @param configuration [Configuration]
+    # @param integration_meta [Hash, nil]
+    # @param message [String, nil]
+    def initialize(configuration:, integration_meta: nil, message: nil)
       # Set some simple default values
       @event_id      = SecureRandom.uuid.delete("-")
       @timestamp     = Sentry.utc_now.iso8601
@@ -48,17 +57,25 @@ module Sentry
 
       @fingerprint = []
 
+      # configuration data that's directly used by events
       @server_name = configuration.server_name
       @environment = configuration.environment
       @release = configuration.release
       @modules = configuration.gem_specs if configuration.send_modules
 
+      # configuration options to help events process data
+      @send_default_pii = configuration.send_default_pii
+      @trusted_proxies = configuration.trusted_proxies
+      @stacktrace_builder = configuration.stacktrace_builder
+      @rack_env_whitelist = configuration.rack_env_whitelist
+
       @message = (message || "").byteslice(0..MAX_MESSAGE_SIZE_IN_BYTES)
 
       self.level = :error
     end
 
     class << self
+      # @!visibility private
       def get_log_message(event_hash)
         message = event_hash[:message] || event_hash['message']
 
@@ -75,6 +92,7 @@ module Sentry
         '<no message value>'
       end
 
+      # @!visibility private
       def get_message_from_exception(event_hash)
         if exception = event_hash.dig(:exception, :values, 0)
           "#{exception[:type]}: #{exception[:value]}"
@@ -84,21 +102,35 @@ module Sentry
       end
     end
 
+    # @deprecated This method will be removed in v5.0.0. Please just use Sentry.configuration
+    # @return [Configuration]
+    def configuration
+      Sentry.configuration
+    end
+
+    # Sets the event's timestamp.
+    # @param time [Time, Float]
+    # @return [void]
     def timestamp=(time)
       @timestamp = time.is_a?(Time) ? time.to_f : time
     end
 
-    def level=(new_level) # needed to meet the Sentry spec
-      @level = new_level.to_s == "warn" ? :warning : new_level
+    # Sets the event's level.
+    # @param level [String, Symbol]
+    # @return [void]
+    def level=(level) # needed to meet the Sentry spec
+      @level = level.to_s == "warn" ? :warning : level
     end
 
+    # Sets the event's request environment data with RequestInterface.
+    # @see RequestInterface
+    # @param env [Hash]
+    # @return [void]
     def rack_env=(env)
       unless request || env.empty?
-        env = env.dup
-
         add_request_interface(env)
 
-        if configuration.send_default_pii
+        if @send_default_pii
           user[:ip_address] = calculate_real_ip_from_rack(env)
         end
 
@@ -108,6 +140,7 @@ module Sentry
       end
     end
 
+    # @return [Hash]
     def to_hash
       data = serialize_attributes
       data[:breadcrumbs] = breadcrumbs.to_hash if breadcrumbs
@@ -118,32 +151,35 @@ module Sentry
       data
     end
 
+    # @return [Hash]
     def to_json_compatible
       JSON.parse(JSON.generate(to_hash))
     end
 
-    def add_request_interface(env)
-      @request = Sentry::RequestInterface.build(env: env)
-    end
-
+    # @!visibility private
     def add_threads_interface(backtrace: nil, **options)
       @threads = ThreadsInterface.build(
         backtrace: backtrace,
-        stacktrace_builder: configuration.stacktrace_builder,
+        stacktrace_builder: @stacktrace_builder,
         **options
       )
     end
 
+    # @!visibility private
     def add_exception_interface(exception)
       if exception.respond_to?(:sentry_context)
         @extra.merge!(exception.sentry_context)
       end
 
-      @exception = Sentry::ExceptionInterface.build(exception: exception, stacktrace_builder: configuration.stacktrace_builder)
+      @exception = Sentry::ExceptionInterface.build(exception: exception, stacktrace_builder: @stacktrace_builder)
     end
 
     private
 
+    def add_request_interface(env)
+      @request = Sentry::RequestInterface.new(env: env, send_default_pii: @send_default_pii, rack_env_whitelist: @rack_env_whitelist)
+    end
+
     def serialize_attributes
       self.class::SERIALIZEABLE_ATTRIBUTES.each_with_object({}) do |att, memo|
         if value = public_send(att)
@@ -160,7 +196,7 @@ module Sentry
         :client_ip => env["HTTP_CLIENT_IP"],
         :real_ip => env["HTTP_X_REAL_IP"],
         :forwarded_for => env["HTTP_X_FORWARDED_FOR"],
-        :trusted_proxies => configuration.trusted_proxies
+        :trusted_proxies => @trusted_proxies
       ).calculate_ip
     end
   end

data/lib/sentry/hub.rb

@@ -114,6 +114,9 @@ module Sentry
       options[:hint][:message] = message
       backtrace = options.delete(:backtrace)
       event = current_client.event_from_message(message, options[:hint], backtrace: backtrace)
+
+      return unless event
+
       capture_event(event, **options, &block)
     end
 

data/lib/sentry/interface.rb

@@ -2,16 +2,7 @@
 
 module Sentry
   class Interface
-    def self.inherited(klass)
-      name = klass.name.split("::").last.downcase.gsub("interface", "")
-      registered[name.to_sym] = klass
-      super
-    end
-
-    def self.registered
-      @@registered ||= {} # rubocop:disable Style/ClassVars
-    end
-
+    # @return [Hash]
     def to_hash
       Hash[instance_variables.map { |name| [name[1..-1].to_sym, instance_variable_get(name)] }]
     end

data/lib/sentry/interfaces/exception.rb

@@ -2,16 +2,24 @@
 
 module Sentry
   class ExceptionInterface < Interface
-    def initialize(values:)
-      @values = values
+    # @param exceptions [Array<SingleExceptionInterface>]
+    def initialize(exceptions:)
+      @values = exceptions
     end
 
+    # @return [Hash]
     def to_hash
       data = super
       data[:values] = data[:values].map(&:to_hash) if data[:values]
       data
     end
 
+    # Builds ExceptionInterface with given exception and stacktrace_builder.
+    # @param exception [Exception]
+    # @param stacktrace_builder [StacktraceBuilder]
+    # @see SingleExceptionInterface#build_with_stacktrace
+    # @see SingleExceptionInterface#initialize
+    # @return [ExceptionInterface]
     def self.build(exception:, stacktrace_builder:)
       exceptions = Sentry::Utils::ExceptionCauseChain.exception_to_array(exception).reverse
       processed_backtrace_ids = Set.new
@@ -25,7 +33,7 @@ module Sentry
         end
       end
 
-      new(values: exceptions)
+      new(exceptions: exceptions)
     end
   end
 end

data/lib/sentry/interfaces/request.rb

@@ -15,29 +15,45 @@ module Sentry
     # https://github.com/getsentry/sentry/blob/master/src/sentry/conf/server.py
     MAX_BODY_LIMIT = 4096 * 4
 
-    attr_accessor :url, :method, :data, :query_string, :cookies, :headers, :env
+    # @return [String]
+    attr_accessor :url
 
-    def self.build(env:)
-      env = clean_env(env)
-      request = ::Rack::Request.new(env)
-      self.new(request: request)
-    end
+    # @return [String]
+    attr_accessor :method
+
+    # @return [Hash]
+    attr_accessor :data
+
+    # @return [String]
+    attr_accessor :query_string
+
+    # @return [String]
+    attr_accessor :cookies
+
+    # @return [Hash]
+    attr_accessor :headers
 
-    def self.clean_env(env)
-      unless Sentry.configuration.send_default_pii
+    # @return [Hash]
+    attr_accessor :env
+
+    # @param env [Hash]
+    # @param send_default_pii [Boolean]
+    # @param rack_env_whitelist [Array]
+    # @see Configuration#send_default_pii
+    # @see Configuration#rack_env_whitelist
+    def initialize(env:, send_default_pii:, rack_env_whitelist:)
+      env = env.dup
+
+      unless send_default_pii
         # need to completely wipe out ip addresses
         RequestInterface::IP_HEADERS.each do |header|
           env.delete(header)
         end
       end
 
-      env
-    end
-
-    def initialize(request:)
-      env = request.env
+      request = ::Rack::Request.new(env)
 
-      if Sentry.configuration.send_default_pii
+      if send_default_pii
         self.data = read_data_from(request)
         self.cookies = request.cookies
         self.query_string = request.query_string
@@ -47,7 +63,7 @@ module Sentry
       self.method = request.request_method
 
       self.headers = filter_and_format_headers(env)
-      self.env     = filter_and_format_env(env)
+      self.env     = filter_and_format_env(env, rack_env_whitelist)
     end
 
     private
@@ -116,11 +132,11 @@ module Sentry
       key == 'HTTP_VERSION' && value == protocol_version
     end
 
-    def filter_and_format_env(env)
-      return env if Sentry.configuration.rack_env_whitelist.empty?
+    def filter_and_format_env(env, rack_env_whitelist)
+      return env if rack_env_whitelist.empty?
 
       env.select do |k, _v|
-        Sentry.configuration.rack_env_whitelist.include? k.to_s
+        rack_env_whitelist.include? k.to_s
       end
     end
   end

data/lib/sentry/interfaces/stacktrace.rb

@@ -2,16 +2,20 @@
 
 module Sentry
   class StacktraceInterface
+    # @return [<Array[Frame]>]
     attr_reader :frames
 
+    # @param frames [<Array[Frame]>]
     def initialize(frames:)
       @frames = frames
     end
 
+    # @return [Hash]
     def to_hash
       { frames: @frames.map(&:to_hash) }
     end
 
+    # @return [String]
     def inspect
       @frames.map(&:to_s)
     end

data/lib/sentry/interfaces/stacktrace_builder.rb

@@ -2,8 +2,31 @@
 
 module Sentry
   class StacktraceBuilder
-    attr_reader :project_root, :app_dirs_pattern, :linecache, :context_lines, :backtrace_cleanup_callback
+    # @return [String]
+    attr_reader :project_root
 
+    # @return [Regexp, nil]
+    attr_reader :app_dirs_pattern
+
+    # @return [LineCache]
+    attr_reader :linecache
+
+    # @return [Integer, nil]
+    attr_reader :context_lines
+
+    # @return [Proc, nil]
+    attr_reader :backtrace_cleanup_callback
+
+    # @param project_root [String]
+    # @param app_dirs_pattern [Regexp, nil]
+    # @param linecache [LineCache]
+    # @param context_lines [Integer, nil]
+    # @param backtrace_cleanup_callback [Proc, nil]
+    # @see Configuration#project_root
+    # @see Configuration#app_dirs_pattern
+    # @see Configuration#linecache
+    # @see Configuration#context_lines
+    # @see Configuration#backtrace_cleanup_callback
     def initialize(project_root:, app_dirs_pattern:, linecache:, context_lines:, backtrace_cleanup_callback: nil)
       @project_root = project_root
       @app_dirs_pattern = app_dirs_pattern
@@ -12,17 +35,21 @@ module Sentry
       @backtrace_cleanup_callback = backtrace_cleanup_callback
     end
 
-    # you can pass a block to customize/exclude frames:
+    # Generates a StacktraceInterface with the given backtrace.
+    # You can pass a block to customize/exclude frames:
     #
-    # ```ruby
-    # builder.build(backtrace) do |frame|
-    #   if frame.module.match?(/a_gem/)
-    #     nil
-    #   else
-    #     frame
+    # @example
+    #   builder.build(backtrace) do |frame|
+    #     if frame.module.match?(/a_gem/)
+    #       nil
+    #     else
+    #       frame
+    #     end
     #   end
-    # end
-    # ```
+    # @param backtrace [Array<String>]
+    # @param frame_callback [Proc]
+    # @yieldparam frame [StacktraceInterface::Frame]
+    # @return [StacktraceInterface]
     def build(backtrace:, &frame_callback)
       parsed_lines = parse_backtrace_lines(backtrace).select(&:file)