sentry-ruby 5.3.0 → 5.8.0

data/lib/sentry/test_helper.rb

@@ -0,0 +1,78 @@
+module Sentry
+  module TestHelper
+    DUMMY_DSN = 'http://12345:67890@sentry.localdomain/sentry/42'
+
+    # Alters the existing SDK configuration with test-suitable options. Mainly:
+    # - Sets a dummy DSN instead of `nil` or an actual DSN.
+    # - Sets the transport to DummyTransport, which allows easy access to the captured events.
+    # - Disables background worker.
+    # - Makes sure the SDK is enabled under the current environment ("test" in most cases).
+    #
+    # It should be called **before** every test case.
+    #
+    # @yieldparam config [Configuration]
+    # @return [void]
+    def setup_sentry_test(&block)
+      raise "please make sure the SDK is initialized for testing" unless Sentry.initialized?
+      copied_config = Sentry.configuration.dup
+      # configure dummy DSN, so the events will not be sent to the actual service
+      copied_config.dsn = DUMMY_DSN
+      # set transport to DummyTransport, so we can easily intercept the captured events
+      copied_config.transport.transport_class = Sentry::DummyTransport
+      # make sure SDK allows sending under the current environment
+      copied_config.enabled_environments << copied_config.environment unless copied_config.enabled_environments.include?(copied_config.environment)
+      # disble async event sending
+      copied_config.background_worker_threads = 0
+
+      # user can overwrite some of the configs, with a few exceptions like:
+      # - include_local_variables
+      # - auto_session_tracking
+      block&.call(copied_config)
+
+      test_client = Sentry::Client.new(copied_config)
+      Sentry.get_current_hub.bind_client(test_client)
+      Sentry.get_current_scope.clear
+    end
+
+    # Clears all stored events and envelopes.
+    # It should be called **after** every test case.
+    # @return [void]
+    def teardown_sentry_test
+      return unless Sentry.initialized?
+
+      sentry_transport.events = []
+      sentry_transport.envelopes = []
+      Sentry.get_current_scope.clear
+    end
+
+    # @return [Transport]
+    def sentry_transport
+      Sentry.get_current_client.transport
+    end
+
+    # Returns the captured event objects.
+    # @return [Array<Event>]
+    def sentry_events
+      sentry_transport.events
+    end
+
+    # Returns the captured envelope objects.
+    # @return [Array<Envelope>]
+    def sentry_envelopes
+      sentry_transport.envelopes
+    end
+
+    # Returns the last captured event object.
+    # @return [Event, nil]
+    def last_sentry_event
+      sentry_events.last
+    end
+
+    # Extracts SDK's internal exception container (not actual exception objects) from an given event.
+    # @return [Array<Sentry::SingleExceptionInterface>]
+    def extract_sentry_exceptions(event)
+      event&.exception&.values || []
+    end
+  end
+end
+

data/lib/sentry/transaction.rb

@@ -0,0 +1,345 @@
+# frozen_string_literal: true
+
+require "sentry/baggage"
+
+module Sentry
+  class Transaction < Span
+    SENTRY_TRACE_REGEXP = Regexp.new(
+      "^[ \t]*" +  # whitespace
+      "([0-9a-f]{32})?" +  # trace_id
+      "-?([0-9a-f]{16})?" +  # span_id
+      "-?([01])?" +  # sampled
+      "[ \t]*$"  # whitespace
+    )
+    UNLABELD_NAME = "<unlabeled transaction>".freeze
+    MESSAGE_PREFIX = "[Tracing]"
+
+    # https://develop.sentry.dev/sdk/event-payloads/transaction/#transaction-annotations
+    SOURCES = %i(custom url route view component task)
+
+    include LoggingHelper
+
+    # The name of the transaction.
+    # @return [String]
+    attr_reader :name
+
+    # The source of the transaction name.
+    # @return [Symbol]
+    attr_reader :source
+
+    # 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
+
+    # The parsed incoming W3C baggage header.
+    # This is only for accessing the current baggage variable.
+    # Please use the #get_baggage method for interfacing outside this class.
+    # @return [Baggage, nil]
+    attr_reader :baggage
+
+    # The measurements added to the transaction.
+    # @return [Hash]
+    attr_reader :measurements
+
+    # @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
+
+    # The effective sample rate at which this transaction was sampled.
+    # @return [Float, nil]
+    attr_reader :effective_sample_rate
+
+    # Additional contexts stored directly on the transaction object.
+    # @return [Hash]
+    attr_reader :contexts
+
+    def initialize(
+      hub:,
+      name: nil,
+      source: :custom,
+      parent_sampled: nil,
+      baggage: nil,
+      **options
+    )
+      super(transaction: self, **options)
+
+      set_name(name, source: source)
+      @parent_sampled = parent_sampled
+      @hub = hub
+      @baggage = baggage
+      @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
+      @release = hub.configuration.release
+      @environment = hub.configuration.environment
+      @dsn = hub.configuration.dsn
+      @effective_sample_rate = nil
+      @contexts = {}
+      @measurements = {}
+      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 baggage [String, nil] the incoming baggage header string.
+    # @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, baggage: nil, hub: Sentry.get_current_hub, **options)
+      return unless hub.configuration.tracing_enabled?
+      return unless sentry_trace
+
+      sentry_trace_data = extract_sentry_trace(sentry_trace)
+      return unless sentry_trace_data
+
+      trace_id, parent_span_id, parent_sampled = sentry_trace_data
+
+      baggage = if baggage && !baggage.empty?
+                  Baggage.from_incoming_header(baggage)
+                else
+                  # If there's an incoming sentry-trace but no incoming baggage header,
+                  # for instance in traces coming from older SDKs,
+                  # baggage will be empty and frozen and won't be populated as head SDK.
+                  Baggage.new({})
+                end
+
+      baggage.freeze!
+
+      new(
+        trace_id: trace_id,
+        parent_span_id: parent_span_id,
+        parent_sampled: parent_sampled,
+        hub: hub,
+        baggage: baggage,
+        **options
+      )
+    end
+
+    # Extract the trace_id, parent_span_id and parent_sampled values from a sentry-trace header.
+    #
+    # @param sentry_trace [String] the sentry-trace header value from the previous transaction.
+    # @return [Array, nil]
+    def self.extract_sentry_trace(sentry_trace)
+      match = SENTRY_TRACE_REGEXP.match(sentry_trace)
+      return nil if match.nil?
+
+      trace_id, parent_span_id, sampled_flag = match[1..3]
+      parent_sampled = sampled_flag.nil? ? nil : sampled_flag != "0"
+
+      [trace_id, parent_span_id, parent_sampled]
+    end
+
+    # @return [Hash]
+    def to_hash
+      hash = super
+
+      hash.merge!(
+        name: @name,
+        source: @source,
+        sampled: @sampled,
+        parent_sampled: @parent_sampled
+      )
+
+      hash
+    end
+
+    # @return [Transaction]
+    def deep_dup
+      copy = super
+      copy.init_span_recorder(@span_recorder.max_length)
+
+      @span_recorder.spans.each do |span|
+        # span_recorder's first span is the current span, which should not be added to the copy's spans
+        next if span == self
+        copy.span_recorder.add(span.dup)
+      end
+
+      copy
+    end
+
+    # Sets a custom measurement on the transaction.
+    # @param name [String] name of the measurement
+    # @param value [Float] value of the measurement
+    # @param unit [String] unit of the measurement
+    # @return [void]
+    def set_measurement(name, value, unit = "")
+      @measurements[name] = { value: value, unit: unit }
+    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 @tracing_enabled
+        @sampled = false
+        return
+      end
+
+      unless @sampled.nil?
+        @effective_sample_rate = @sampled ? 1.0 : 0.0
+        return
+      end
+
+      sample_rate =
+        if @traces_sampler.is_a?(Proc)
+          @traces_sampler.call(sampling_context)
+        elsif !sampling_context[:parent_sampled].nil?
+          sampling_context[:parent_sampled]
+        else
+          @traces_sample_rate
+        end
+
+      transaction_description = generate_transaction_description
+
+      if [true, false].include?(sample_rate)
+        @effective_sample_rate = sample_rate ? 1.0 : 0.0
+      elsif sample_rate.is_a?(Numeric) && sample_rate >= 0.0 && sample_rate <= 1.0
+        @effective_sample_rate = sample_rate.to_f
+      else
+        @sampled = false
+        log_warn("#{MESSAGE_PREFIX} Discarding #{transaction_description} because of invalid sample_rate: #{sample_rate}")
+        return
+      end
+
+      if sample_rate == 0.0 || sample_rate == false
+        @sampled = false
+        log_debug("#{MESSAGE_PREFIX} Discarding #{transaction_description} because traces_sampler returned 0 or false")
+        return
+      end
+
+      if sample_rate == true
+        @sampled = true
+      else
+        @sampled = Random.rand < sample_rate
+      end
+
+      if @sampled
+        log_debug("#{MESSAGE_PREFIX} Starting #{transaction_description}")
+      else
+        log_debug(
+          "#{MESSAGE_PREFIX} Discarding #{transaction_description} because it's not included in the random sample (sampling rate = #{sample_rate})"
+        )
+      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, end_timestamp: nil)
+      if hub
+        log_warn(
+          <<~MSG
+            Specifying a different hub in `Transaction#finish` will be deprecated in version 5.0.
+            Please use `Hub#start_transaction` with the designated hub.
+          MSG
+        )
+      end
+
+      hub ||= @hub
+
+      super(end_timestamp: end_timestamp)
+
+      if @name.nil?
+        @name = UNLABELD_NAME
+      end
+
+      if @sampled
+        event = hub.current_client.event_from_transaction(self)
+        hub.capture_event(event)
+      else
+        hub.current_client.transport.record_lost_event(:sample_rate, 'transaction')
+      end
+    end
+
+    # Get the existing frozen incoming baggage
+    # or populate one with sentry- items as the head SDK.
+    # @return [Baggage]
+    def get_baggage
+      populate_head_baggage if @baggage.nil? || @baggage.mutable
+      @baggage
+    end
+
+    # Set the transaction name directly.
+    # Considered internal api since it bypasses the usual scope logic.
+    # @param name [String]
+    # @param source [Symbol]
+    # @return [void]
+    def set_name(name, source: :custom)
+      @name = name
+      @source = SOURCES.include?(source) ? source.to_sym : :custom
+    end
+
+    # Set contexts directly on the transaction.
+    # @param key [String, Symbol]
+    # @param value [Object]
+    # @return [void]
+    def set_context(key, value)
+      @contexts[key] = value
+    end
+
+    protected
+
+    def init_span_recorder(limit = 1000)
+      @span_recorder = SpanRecorder.new(limit)
+      @span_recorder.add(self)
+    end
+
+    private
+
+    def generate_transaction_description
+      result = op.nil? ? "" : "<#{@op}> "
+      result += "transaction"
+      result += " <#{@name}>" if @name
+      result
+    end
+
+    def populate_head_baggage
+      items = {
+        "trace_id" => trace_id,
+        "sample_rate" => effective_sample_rate&.to_s,
+        "environment" => @environment,
+        "release" => @release,
+        "public_key" => @dsn&.public_key
+      }
+
+      items["transaction"] = name unless source_low_quality?
+
+      user = @hub.current_scope&.user
+      items["user_segment"] = user["segment"] if user && user["segment"]
+
+      items.compact!
+      @baggage = Baggage.new(items, mutable: false)
+    end
+
+    # These are high cardinality and thus bad
+    def source_low_quality?
+      source == :url
+    end
+
+    class SpanRecorder
+      attr_reader :max_length, :spans
+
+      def initialize(max_length)
+        @max_length = max_length
+        @spans = []
+      end
+
+      def add(span)
+        if @spans.count < @max_length
+          @spans << span
+        end
+      end
+    end
+  end
+end

data/lib/sentry/transaction_event.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Sentry
+  # TransactionEvent represents events that carry transaction data (type: "transaction").
+  class TransactionEvent < Event
+    TYPE = "transaction"
+
+    # @return [<Array[Span]>]
+    attr_accessor :spans
+
+    # @return [Hash, nil]
+    attr_accessor :dynamic_sampling_context
+
+    # @return [Hash]
+    attr_accessor :measurements
+
+    # @return [Float, nil]
+    attr_reader :start_timestamp
+
+    def initialize(transaction:, **options)
+      super(**options)
+
+      self.transaction = transaction.name
+      self.transaction_info = { source: transaction.source }
+      self.contexts.merge!(transaction.contexts)
+      self.contexts.merge!(trace: transaction.get_trace_context)
+      self.timestamp = transaction.timestamp
+      self.start_timestamp = transaction.start_timestamp
+      self.tags = transaction.tags
+      self.dynamic_sampling_context = transaction.get_baggage.dynamic_sampling_context
+      self.measurements = transaction.measurements
+
+      finished_spans = transaction.span_recorder.spans.select { |span| span.timestamp && span != transaction }
+      self.spans = finished_spans.map(&:to_hash)
+    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[:start_timestamp] = @start_timestamp
+      data[:measurements] = @measurements
+      data
+    end
+  end
+end

data/lib/sentry/transport/configuration.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Sentry
+  class Transport
+    class Configuration
+      attr_accessor :timeout, :open_timeout, :proxy, :ssl, :ssl_ca_file, :ssl_verification, :encoding
+      attr_reader :transport_class
+
+      def initialize
+        @ssl_verification = true
+        @open_timeout = 1
+        @timeout = 2
+        @encoding = HTTPTransport::GZIP_ENCODING
+      end
+
+      def transport_class=(klass)
+        unless klass.is_a?(Class)
+          raise Sentry::Error.new("config.transport.transport_class must a class. got: #{klass.class}")
+        end
+
+        @transport_class = klass
+      end
+    end
+  end
+end

data/lib/sentry/transport/dummy_transport.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Sentry
+  class DummyTransport < Transport
+    attr_accessor :events, :envelopes
+
+    def initialize(*)
+      super
+      @events = []
+      @envelopes = []
+    end
+
+    def send_event(event)
+      @events << event
+    end
+
+    def send_envelope(envelope)
+      @envelopes << envelope
+    end
+  end
+end

data/lib/sentry/transport/http_transport.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "zlib"
+
+module Sentry
+  class HTTPTransport < Transport
+    GZIP_ENCODING = "gzip"
+    GZIP_THRESHOLD = 1024 * 30
+    CONTENT_TYPE = 'application/x-sentry-envelope'
+
+    DEFAULT_DELAY = 60
+    RETRY_AFTER_HEADER = "retry-after"
+    RATE_LIMIT_HEADER = "x-sentry-rate-limits"
+    USER_AGENT = "sentry-ruby/#{Sentry::VERSION}"
+
+    def initialize(*args)
+      super
+      @endpoint = @dsn.envelope_endpoint
+
+      log_debug("Sentry HTTP Transport will connect to #{@dsn.server}")
+    end
+
+    def send_data(data)
+      encoding = ""
+
+      if should_compress?(data)
+        data = Zlib.gzip(data)
+        encoding = GZIP_ENCODING
+      end
+
+      headers = {
+        'Content-Type' => CONTENT_TYPE,
+        'Content-Encoding' => encoding,
+        'X-Sentry-Auth' => generate_auth_header,
+        'User-Agent' => USER_AGENT
+      }
+
+      response = conn.start do |http|
+        request = ::Net::HTTP::Post.new(@endpoint, headers)
+        request.body = data
+        http.request(request)
+      end
+
+      if response.code.match?(/\A2\d{2}/)
+        if has_rate_limited_header?(response)
+          handle_rate_limited_response(response)
+        end
+      else
+        error_info = "the server responded with status #{response.code}"
+
+        if response.code == "429"
+          handle_rate_limited_response(response)
+        else
+          error_info += "\nbody: #{response.body}"
+          error_info += " Error in headers is: #{response['x-sentry-error']}" if response['x-sentry-error']
+        end
+
+        raise Sentry::ExternalError, error_info
+      end
+    rescue SocketError => e
+      raise Sentry::ExternalError.new(e.message)
+    end
+
+    private
+
+    def has_rate_limited_header?(headers)
+      headers[RETRY_AFTER_HEADER] || headers[RATE_LIMIT_HEADER]
+    end
+
+    def handle_rate_limited_response(headers)
+      rate_limits =
+        if rate_limits = headers[RATE_LIMIT_HEADER]
+          parse_rate_limit_header(rate_limits)
+        elsif retry_after = headers[RETRY_AFTER_HEADER]
+          # although Sentry doesn't send a date string back
+          # based on HTTP specification, this could be a date string (instead of an integer)
+          retry_after = retry_after.to_i
+          retry_after = DEFAULT_DELAY if retry_after == 0
+
+          { nil => Time.now + retry_after }
+        else
+          { nil => Time.now + DEFAULT_DELAY }
+        end
+
+      rate_limits.each do |category, limit|
+        if current_limit = @rate_limits[category]
+          if current_limit < limit
+            @rate_limits[category] = limit
+          end
+        else
+          @rate_limits[category] = limit
+        end
+      end
+    end
+
+    def parse_rate_limit_header(rate_limit_header)
+      time = Time.now
+
+      result = {}
+
+      limits = rate_limit_header.split(",")
+      limits.each do |limit|
+        next if limit.nil? || limit.empty?
+
+        begin
+          retry_after, categories = limit.strip.split(":").first(2)
+          retry_after = time + retry_after.to_i
+          categories = categories.split(";")
+
+          if categories.empty?
+            result[nil] = retry_after
+          else
+            categories.each do |category|
+              result[category] = retry_after
+            end
+          end
+        rescue StandardError
+        end
+      end
+
+      result
+    end
+
+    def should_compress?(data)
+      @transport_configuration.encoding == GZIP_ENCODING && data.bytesize >= GZIP_THRESHOLD
+    end
+
+    def conn
+      server = URI(@dsn.server)
+
+      connection =
+        if proxy = normalize_proxy(@transport_configuration.proxy)
+          ::Net::HTTP.new(server.hostname, server.port, proxy[:uri].hostname, proxy[:uri].port, proxy[:user], proxy[:password])
+        else
+          ::Net::HTTP.new(server.hostname, server.port, nil)
+        end
+
+      connection.use_ssl = server.scheme == "https"
+      connection.read_timeout = @transport_configuration.timeout
+      connection.write_timeout = @transport_configuration.timeout if connection.respond_to?(:write_timeout)
+      connection.open_timeout = @transport_configuration.open_timeout
+
+      ssl_configuration.each do |key, value|
+        connection.send("#{key}=", value)
+      end
+
+      connection
+    end
+
+    def normalize_proxy(proxy)
+      return proxy unless proxy
+
+      case proxy
+      when String
+        uri = URI(proxy)
+        { uri: uri, user: uri.user, password: uri.password }
+      when URI
+        { uri: proxy, user: proxy.user, password: proxy.password }
+      when Hash
+        proxy
+      end
+    end
+
+    def ssl_configuration
+      configuration = {
+        verify: @transport_configuration.ssl_verification,
+        ca_file: @transport_configuration.ssl_ca_file
+      }.merge(@transport_configuration.ssl || {})
+
+      configuration[:verify_mode] = configuration.delete(:verify) ? OpenSSL::SSL::VERIFY_PEER : OpenSSL::SSL::VERIFY_NONE
+      configuration
+    end
+  end
+end