sentry-ruby-core 4.8.3 → 5.0.0

data/lib/sentry/interfaces/threads.rb

@@ -2,6 +2,8 @@
 
 module Sentry
   class ThreadsInterface
+    # @param crashed [Boolean]
+    # @param stacktrace [Array]
     def initialize(crashed: false, stacktrace: nil)
       @id = Thread.current.object_id
       @name = Thread.current.name
@@ -10,6 +12,7 @@ module Sentry
       @stacktrace = stacktrace
     end
 
+    # @return [Hash]
     def to_hash
       {
         values: [
@@ -24,8 +27,13 @@ module Sentry
       }
     end
 
-    # patch this method if you want to change a threads interface's stacktrace frames
-    # also see `StacktraceBuilder.build`.
+    # Builds the ThreadsInterface with given backtrace and stacktrace_builder.
+    # Patch this method if you want to change a threads interface's stacktrace frames.
+    # @see StacktraceBuilder.build
+    # @param backtrace [Array]
+    # @param stacktrace_builder [StacktraceBuilder]
+    # @param crashed [Hash]
+    # @return [ThreadsInterface]
     def self.build(backtrace:, stacktrace_builder:, **options)
       stacktrace = stacktrace_builder.build(backtrace: backtrace) if backtrace
       new(**options, stacktrace: stacktrace)

data/lib/sentry/net/http.rb

@@ -23,90 +23,67 @@ module Sentry
       # end
       # ```
       #
-      # So when the entire flow looks like this:
-      #
-      # 1. #request is called.
-      #   - But because the request hasn't started yet, it calls #start (which then calls #do_start)
-      #   - At this moment @sentry_span is still nil, so #set_sentry_trace_header returns early
-      # 2. #do_start then creates a new Span and assigns it to @sentry_span
-      # 3. #request is called for the second time.
-      #   - This time @sentry_span should present. So #set_sentry_trace_header will set the sentry-trace header on the request object
-      # 4. Once the request finished, it
-      #   - Records a breadcrumb if http_logger is set
-      #   - Finishes the Span inside @sentry_span and clears the instance variable
-      #
+      # So we're only instrumenting request when `Net::HTTP` is already started
       def request(req, body = nil, &block)
-        set_sentry_trace_header(req)
+        return super unless started?
+
+        sentry_span = start_sentry_span
+        set_sentry_trace_header(req, sentry_span)
 
         super.tap do |res|
           record_sentry_breadcrumb(req, res)
-          record_sentry_span(req, res)
-        end
-      end
-
-      def do_start
-        super.tap do
-          start_sentry_span
-        end
-      end
-
-      def do_finish
-        super.tap do
-          finish_sentry_span
+          record_sentry_span(req, res, sentry_span)
         end
       end
 
       private
 
-      def set_sentry_trace_header(req)
-        return unless @sentry_span
+      def set_sentry_trace_header(req, sentry_span)
+        return unless sentry_span
 
-        trace = Sentry.get_current_client.generate_sentry_trace(@sentry_span)
+        trace = Sentry.get_current_client.generate_sentry_trace(sentry_span)
         req[SENTRY_TRACE_HEADER_NAME] = trace if trace
       end
 
       def record_sentry_breadcrumb(req, res)
-        if Sentry.initialized? && Sentry.configuration.breadcrumbs_logger.include?(:http_logger)
-          return if from_sentry_sdk?
-
-          request_info = extract_request_info(req)
-          crumb = Sentry::Breadcrumb.new(
-            level: :info,
-            category: OP_NAME,
-            type: :info,
-            data: {
-              method: request_info[:method],
-              url: request_info[:url],
-              status: res.code.to_i
-            }
-          )
-          Sentry.add_breadcrumb(crumb)
-        end
+        return unless Sentry.initialized? && Sentry.configuration.breadcrumbs_logger.include?(:http_logger)
+        return if from_sentry_sdk?
+
+        request_info = extract_request_info(req)
+
+        crumb = Sentry::Breadcrumb.new(
+          level: :info,
+          category: OP_NAME,
+          type: :info,
+          data: {
+            status: res.code.to_i,
+            **request_info
+          }
+        )
+        Sentry.add_breadcrumb(crumb)
       end
 
-      def record_sentry_span(req, res)
-        if Sentry.initialized? && @sentry_span
-          request_info = extract_request_info(req)
-          @sentry_span.set_description("#{request_info[:method]} #{request_info[:url]}")
-          @sentry_span.set_data(:status, res.code.to_i)
-        end
+      def record_sentry_span(req, res, sentry_span)
+        return unless Sentry.initialized? && sentry_span
+
+        request_info = extract_request_info(req)
+        sentry_span.set_description("#{request_info[:method]} #{request_info[:url]}")
+        sentry_span.set_data(:status, res.code.to_i)
+        finish_sentry_span(sentry_span)
       end
 
       def start_sentry_span
-        if Sentry.initialized? && transaction = Sentry.get_current_scope.get_transaction
-          return if from_sentry_sdk?
-          return if transaction.sampled == false
+        return unless Sentry.initialized? && transaction = Sentry.get_current_scope.get_transaction
+        return if from_sentry_sdk?
+        return if transaction.sampled == false
 
-          child_span = transaction.start_child(op: OP_NAME, start_timestamp: Sentry.utc_now.to_f)
-          @sentry_span = child_span
-        end
+        transaction.start_child(op: OP_NAME, start_timestamp: Sentry.utc_now.to_f)
       end
 
-      def finish_sentry_span
-        if Sentry.initialized? && @sentry_span
-          @sentry_span.set_timestamp(Sentry.utc_now.to_f)
-          @sentry_span = nil
-        end
+      def finish_sentry_span(sentry_span)
+        return unless Sentry.initialized? && sentry_span
+
+        sentry_span.set_timestamp(Sentry.utc_now.to_f)
       end
 
       def from_sentry_sdk?
@@ -115,9 +92,17 @@ module Sentry
       end
 
       def extract_request_info(req)
-        uri = req.uri
+        uri = req.uri || URI.parse("#{use_ssl? ? 'https' : 'http'}://#{address}#{req.path}")
         url = "#{uri.scheme}://#{uri.host}#{uri.path}" rescue uri.to_s
-        { method: req.method, url: url }
+
+        result = { method: req.method, url: url }
+
+        if Sentry.configuration.send_default_pii
+          result[:url] = result[:url] + "?#{uri.query}"
+          result[:body] = req.body
+        end
+
+        result
       end
     end
   end

data/lib/sentry/scope.rb

@@ -11,15 +11,22 @@ module Sentry
 
     attr_reader(*ATTRIBUTES)
 
+    # @param max_breadcrumbs [Integer] the maximum number of breadcrumbs to be stored in the scope.
     def initialize(max_breadcrumbs: nil)
       @max_breadcrumbs = max_breadcrumbs
       set_default_value
     end
 
+    # Resets the scope's attributes to defaults.
+    # @return [void]
     def clear
       set_default_value
     end
 
+    # Applies stored attributes and event processors to the given event.
+    # @param event [Event]
+    # @param hint [Hash] the hint data that'll be passed to event processors.
+    # @return [Event]
     def apply_to_event(event, hint = nil)
       event.tags = tags.merge(event.tags)
       event.user = user.merge(event.user)
@@ -45,14 +52,20 @@ module Sentry
       event
     end
 
+    # Adds the breadcrumb to the scope's breadcrumbs buffer.
+    # @param breadcrumb [Breadcrumb]
+    # @return [void]
     def add_breadcrumb(breadcrumb)
       breadcrumbs.record(breadcrumb)
     end
 
+    # Clears the scope's breadcrumbs buffer
+    # @return [void]
     def clear_breadcrumbs
       set_new_breadcrumb_buffer
     end
 
+    # @return [Scope]
     def dup
       copy = super
       copy.breadcrumbs = breadcrumbs.dup
@@ -66,6 +79,9 @@ module Sentry
       copy
     end
 
+    # Updates the scope's data from a given scope.
+    # @param scope [Scope]
+    # @return [void]
     def update_from_scope(scope)
       self.breadcrumbs = scope.breadcrumbs
       self.contexts = scope.contexts
@@ -77,6 +93,14 @@ module Sentry
       self.span = scope.span
     end
 
+    # Updates the scope's data from the given options.
+    # @param contexts [Hash]
+    # @param extras [Hash]
+    # @param tags [Hash]
+    # @param user [Hash]
+    # @param level [String, Symbol]
+    # @param fingerprint [Array]
+    # @return [void]
     def update_from_options(
       contexts: nil,
       extra: nil,
@@ -93,39 +117,59 @@ module Sentry
       self.fingerprint = fingerprint if fingerprint
     end
 
+    # Sets the scope's rack_env attribute.
+    # @param env [Hash]
+    # @return [Hash]
     def set_rack_env(env)
       env = env || {}
       @rack_env = env
     end
 
+    # Sets the scope's span attribute.
+    # @param span [Span]
+    # @return [Span]
     def set_span(span)
       check_argument_type!(span, Span)
       @span = span
     end
 
+    # @!macro set_user
     def set_user(user_hash)
       check_argument_type!(user_hash, Hash)
       @user = user_hash
     end
 
+    # @!macro set_extras
     def set_extras(extras_hash)
       check_argument_type!(extras_hash, Hash)
       @extra.merge!(extras_hash)
     end
 
+    # Adds a new key-value pair to current extras.
+    # @param key [String, Symbol]
+    # @param value [Object]
+    # @return [Hash]
     def set_extra(key, value)
       set_extras(key => value)
     end
 
+    # @!macro set_tags
     def set_tags(tags_hash)
       check_argument_type!(tags_hash, Hash)
       @tags.merge!(tags_hash)
     end
 
+    # Adds a new key-value pair to current tags.
+    # @param key [String, Symbol]
+    # @param value [Object]
+    # @return [Hash]
     def set_tag(key, value)
       set_tags(key => value)
     end
 
+    # Updates the scope's contexts attribute by merging with the old value.
+    # @param contexts [Hash]
+    # @return [Hash]
     def set_contexts(contexts_hash)
       check_argument_type!(contexts_hash, Hash)
       @contexts.merge!(contexts_hash) do |key, old, new|
@@ -133,37 +177,58 @@ module Sentry
       end
     end
 
+    # @!macro set_context
     def set_context(key, value)
       check_argument_type!(value, Hash)
       set_contexts(key => value)
     end
 
+    # Sets the scope's level attribute.
+    # @param level [String, Symbol]
+    # @return [void]
     def set_level(level)
       @level = level
     end
 
+    # Appends a new transaction name to the scope.
+    # The "transaction" here does not refer to `Transaction` objects.
+    # @param transaction_name [String]
+    # @return [void]
     def set_transaction_name(transaction_name)
       @transaction_names << transaction_name
     end
 
+    # Returns current transaction name.
+    # The "transaction" here does not refer to `Transaction` objects.
+    # @return [String, nil]
     def transaction_name
       @transaction_names.last
     end
 
+    # Returns the associated Transaction object.
+    # @return [Transaction, nil]
     def get_transaction
       span.transaction if span
     end
 
+    # Returns the associated Span object.
+    # @return [Span, nil]
     def get_span
       span
     end
 
+    # Sets the scope's fingerprint attribute.
+    # @param fingerprint [Array]
+    # @return [Array]
     def set_fingerprint(fingerprint)
       check_argument_type!(fingerprint, Array)
 
       @fingerprint = fingerprint
     end
 
+    # Adds a new event processor [Proc] to the scope.
+    # @param block [Proc]
+    # @return [void]
     def add_event_processor(&block)
       @event_processors << block
     end
@@ -193,8 +258,8 @@ module Sentry
       @breadcrumbs = BreadcrumbBuffer.new(@max_breadcrumbs)
     end
 
-
     class << self
+      # @return [Hash]
       def os_context
         @os_context ||=
           begin
@@ -208,6 +273,7 @@ module Sentry
           end
       end
 
+      # @return [Hash]
       def runtime_context
         @runtime_context ||= {
           name: RbConfig::CONFIG["ruby_install_name"],

data/lib/sentry/span.rb

@@ -18,9 +18,49 @@ module Sentry
       504 => "deadline_exceeded"
     }
 
-
-    attr_reader :trace_id, :span_id, :parent_span_id, :sampled, :start_timestamp, :timestamp, :description, :op, :status, :tags, :data
-    attr_accessor :span_recorder, :transaction
+    # An uuid that can be used to identify a trace.
+    # @return [String]
+    attr_reader :trace_id
+    # An uuid that can be used to identify the span.
+    # @return [String]
+    attr_reader :span_id
+    # Span parent's span_id.
+    # @return [String]
+    attr_reader :parent_span_id
+    # Sampling result of the span.
+    # @return [Boolean, nil]
+    attr_reader :sampled
+    # Starting timestamp of the span.
+    # @return [Float]
+    attr_reader :start_timestamp
+    # Finishing timestamp of the span.
+    # @return [Float]
+    attr_reader :timestamp
+    # Span description
+    # @return [String]
+    attr_reader :description
+    # Span operation
+    # @return [String]
+    attr_reader :op
+    # Span status
+    # @return [String]
+    attr_reader :status
+    # Span tags
+    # @return [Hash]
+    attr_reader :tags
+    # Span data
+    # @return [Hash]
+    attr_reader :data
+
+    # The SpanRecorder the current span belongs to.
+    # SpanRecorder holds all spans under the same Transaction object (including the Transaction itself).
+    # @return [SpanRecorder]
+    attr_accessor :span_recorder
+
+    # The Transaction object the Span belongs to.
+    # Every span needs to be attached to a Transaction and their child spans will also inherit the same transaction.
+    # @return [Transaction]
+    attr_accessor :transaction
 
     def initialize(
       description: nil,
@@ -45,6 +85,8 @@ module Sentry
       @tags = {}
     end
 
+    # Finishes the span by adding a timestamp.
+    # @return [self]
     def finish
       # already finished
       return if @timestamp
@@ -53,6 +95,8 @@ module Sentry
       self
     end
 
+    # Generates a trace string that can be used to connect other transactions.
+    # @return [String]
     def to_sentry_trace
       sampled_flag = ""
       sampled_flag = @sampled ? 1 : 0 unless @sampled.nil?
@@ -60,6 +104,7 @@ module Sentry
       "#{@trace_id}-#{@span_id}-#{sampled_flag}"
     end
 
+    # @return [Hash]
     def to_hash
       {
         trace_id: @trace_id,
@@ -75,6 +120,8 @@ module Sentry
       }
     end
 
+    # Returns the span's context that can be used to embed in an Event.
+    # @return [Hash]
     def get_trace_context
       {
         trace_id: @trace_id,
@@ -86,9 +133,11 @@ module Sentry
       }
     end
 
-    def start_child(**options)
-      options = options.dup.merge(trace_id: @trace_id, parent_span_id: @span_id, sampled: @sampled)
-      new_span = Span.new(**options)
+    # Starts a child span with given attributes.
+    # @param attributes [Hash] the attributes for the child span.
+    def start_child(**attributes)
+      attributes = attributes.dup.merge(trace_id: @trace_id, parent_span_id: @span_id, sampled: @sampled)
+      new_span = Span.new(**attributes)
       new_span.transaction = transaction
       new_span.span_recorder = span_recorder
 
@@ -99,8 +148,17 @@ module Sentry
       new_span
     end
 
-    def with_child_span(**options, &block)
-      child_span = start_child(**options)
+    # Starts a child span, yield it to the given block, and then finish the span after the block is executed.
+    # @example
+    #   span.with_child_span do |child_span|
+    #     # things happen here will be recorded in a child span
+    #   end
+    #
+    # @param attributes [Hash] the attributes for the child span.
+    # @param block [Proc] the action to be recorded in the child span.
+    # @yieldparam child_span [Span]
+    def with_child_span(**attributes, &block)
+      child_span = start_child(**attributes)
 
       yield(child_span)
 
@@ -111,22 +169,33 @@ module Sentry
       dup
     end
 
+    # Sets the span's operation.
+    # @param op [String] operation of the span.
     def set_op(op)
       @op = op
     end
 
+    # Sets the span's description.
+    # @param description [String] description of the span.
     def set_description(description)
       @description = description
     end
 
+
+    # Sets the span's status.
+    # @param satus [String] status of the span.
     def set_status(status)
       @status = status
     end
 
+    # Sets the span's finish timestamp.
+    # @param timestamp [Float] finished time in float format (most precise).
     def set_timestamp(timestamp)
       @timestamp = timestamp
     end
 
+    # Sets the span's status with given http status code.
+    # @param status_code [String] example: "500".
     def set_http_status(status_code)
       status_code = status_code.to_i
       set_data("status_code", status_code)
@@ -140,10 +209,16 @@ module Sentry
       set_status(status)
     end
 
+    # Inserts a key-value pair to the span's data payload.
+    # @param key [String, Symbol]
+    # @param value [Object]
     def set_data(key, value)
       @data[key] = value
     end
 
+    # Sets a tag to the span.
+    # @param key [String, Symbol]
+    # @param value [String]
     def set_tag(key, value)
       @tags[key] = value
     end

data/lib/sentry/transaction.rb

@@ -14,7 +14,22 @@ module Sentry
 
     include LoggingHelper
 
-    attr_reader :name, :parent_sampled, :hub, :configuration, :logger
+    # The name of the transaction.
+    # @return [String]
+    attr_reader :name
+
+    # The sampling decision of the parent transaction, which will be considered when making the current transaction's sampling decision.
+    # @return [String]
+    attr_reader :parent_sampled
+
+    # @deprecated Use Sentry.get_current_hub instead.
+    attr_reader :hub
+
+    # @deprecated Use Sentry.configuration instead.
+    attr_reader :configuration
+
+    # @deprecated Use Sentry.logger instead.
+    attr_reader :logger
 
     def initialize(name: nil, parent_sampled: nil, hub:, **options)
       super(**options)
@@ -23,11 +38,23 @@ module Sentry
       @parent_sampled = parent_sampled
       @transaction = self
       @hub = hub
-      @configuration = hub.configuration
-      @logger = configuration.logger
+      @configuration = hub.configuration # to be removed
+      @tracing_enabled = hub.configuration.tracing_enabled?
+      @traces_sampler = hub.configuration.traces_sampler
+      @traces_sample_rate = hub.configuration.traces_sample_rate
+      @logger = hub.configuration.logger
       init_span_recorder
     end
 
+    # Initalizes a Transaction instance with a Sentry trace string from another transaction (usually from an external request).
+    #
+    # The original transaction will become the parent of the new Transaction instance. And they will share the same `trace_id`.
+    #
+    # The child transaction will also store the parent's sampling decision in its `parent_sampled` attribute.
+    # @param sentry_trace [String] the trace string from the previous transaction.
+    # @param hub [Hub] the hub that'll be responsible for sending this transaction when it's finished.
+    # @param options [Hash] the options you want to use to initialize a Transaction instance.
+    # @return [Transaction, nil]
     def self.from_sentry_trace(sentry_trace, hub: Sentry.get_current_hub, **options)
       return unless hub.configuration.tracing_enabled?
       return unless sentry_trace
@@ -46,12 +73,14 @@ module Sentry
       new(trace_id: trace_id, parent_span_id: parent_span_id, parent_sampled: parent_sampled, hub: hub, **options)
     end
 
+    # @return [Hash]
     def to_hash
       hash = super
       hash.merge!(name: @name, sampled: @sampled, parent_sampled: @parent_sampled)
       hash
     end
 
+    # @return [Transaction]
     def deep_dup
       copy = super
       copy.init_span_recorder(@span_recorder.max_length)
@@ -65,23 +94,24 @@ module Sentry
       copy
     end
 
+    # Sets initial sampling decision of the transaction.
+    # @param sampling_context [Hash] a context Hash that'll be passed to `traces_sampler` (if provided).
+    # @return [void]
     def set_initial_sample_decision(sampling_context:)
-      unless configuration.tracing_enabled?
+      unless @tracing_enabled
         @sampled = false
         return
       end
 
       return unless @sampled.nil?
 
-      traces_sampler = configuration.traces_sampler
-
       sample_rate =
-        if traces_sampler.is_a?(Proc)
-          traces_sampler.call(sampling_context)
+        if @traces_sampler.is_a?(Proc)
+          @traces_sampler.call(sampling_context)
         elsif !sampling_context[:parent_sampled].nil?
           sampling_context[:parent_sampled]
         else
-          configuration.traces_sample_rate
+          @traces_sample_rate
         end
 
       transaction_description = generate_transaction_description
@@ -113,6 +143,9 @@ module Sentry
       end
     end
 
+    # Finishes the transaction's recording and send it to Sentry.
+    # @param hub [Hub] the hub that'll send this transaction. (Deprecated)
+    # @return [TransactionEvent]
     def finish(hub: nil)
       if hub
         log_warn(

data/lib/sentry/transaction_event.rb

@@ -16,17 +16,25 @@ module Sentry
     attr_writer(*WRITER_ATTRIBUTES)
     attr_reader(*SERIALIZEABLE_ATTRIBUTES)
 
+    # @return [<Array[Span]>]
     attr_accessor :spans
 
+    # @param configuration [Configuration]
+    # @param integration_meta [Hash, nil]
+    # @param message [String, nil]
     def initialize(configuration:, integration_meta: nil, message: nil)
       super
       @type = TYPE
     end
 
+    # Sets the event's start_timestamp.
+    # @param time [Time, Float]
+    # @return [void]
     def start_timestamp=(time)
       @start_timestamp = time.is_a?(Time) ? time.to_f : time
     end
 
+    # @return [Hash]
     def to_hash
       data = super
       data[:spans] = @spans.map(&:to_hash) if @spans

data/lib/sentry/transport/configuration.rb

@@ -3,8 +3,7 @@
 module Sentry
   class Transport
     class Configuration
-      attr_accessor :timeout, :open_timeout, :proxy, :ssl, :ssl_ca_file, :ssl_verification, :http_adapter, :faraday_builder,
-        :encoding
+      attr_accessor :timeout, :open_timeout, :proxy, :ssl, :ssl_ca_file, :ssl_verification, :encoding
       attr_reader :transport_class
 
       def initialize