sentry-ruby 5.3.0 → 5.4.1

data/lib/sentry/span.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Sentry
+  class Span
+    STATUS_MAP = {
+      400 => "invalid_argument",
+      401 => "unauthenticated",
+      403 => "permission_denied",
+      404 => "not_found",
+      409 => "already_exists",
+      429 => "resource_exhausted",
+      499 => "cancelled",
+      500 => "internal_error",
+      501 => "unimplemented",
+      503 => "unavailable",
+      504 => "deadline_exceeded"
+    }
+
+    # 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,
+      op: nil,
+      status: nil,
+      trace_id: nil,
+      parent_span_id: nil,
+      sampled: nil,
+      start_timestamp: nil,
+      timestamp: nil
+    )
+      @trace_id = trace_id || SecureRandom.uuid.delete("-")
+      @span_id = SecureRandom.hex(8)
+      @parent_span_id = parent_span_id
+      @sampled = sampled
+      @start_timestamp = start_timestamp || Sentry.utc_now.to_f
+      @timestamp = timestamp
+      @description = description
+      @op = op
+      @status = status
+      @data = {}
+      @tags = {}
+    end
+
+    # Finishes the span by adding a timestamp.
+    # @return [self]
+    def finish
+      # already finished
+      return if @timestamp
+
+      @timestamp = Sentry.utc_now.to_f
+      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?
+
+      "#{@trace_id}-#{@span_id}-#{sampled_flag}"
+    end
+
+    # @return [Hash]
+    def to_hash
+      {
+        trace_id: @trace_id,
+        span_id: @span_id,
+        parent_span_id: @parent_span_id,
+        start_timestamp: @start_timestamp,
+        timestamp: @timestamp,
+        description: @description,
+        op: @op,
+        status: @status,
+        tags: @tags,
+        data: @data
+      }
+    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,
+        span_id: @span_id,
+        parent_span_id: @parent_span_id,
+        description: @description,
+        op: @op,
+        status: @status
+      }
+    end
+
+    # 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
+
+      if span_recorder
+        span_recorder.add(new_span)
+      end
+
+      new_span
+    end
+
+    # 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)
+
+      child_span.finish
+    end
+
+    def deep_dup
+      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)
+
+      status =
+        if status_code >= 200 && status_code < 299
+          "ok"
+        else
+          STATUS_MAP[status_code]
+        end
+      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
+  end
+end

data/lib/sentry/test_helper.rb

@@ -0,0 +1,76 @@
+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:
+      # - capture_exception_frame_locals
+      # - auto_session_tracking
+      block&.call(copied_config)
+
+      test_client = Sentry::Client.new(copied_config)
+      Sentry.get_current_hub.bind_client(test_client)
+    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 = []
+    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,206 @@
+# frozen_string_literal: true
+
+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]"
+
+    include LoggingHelper
+
+    # 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)
+
+      @name = name
+      @parent_sampled = parent_sampled
+      @transaction = self
+      @hub = hub
+      @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
+
+      match = SENTRY_TRACE_REGEXP.match(sentry_trace)
+      return if match.nil?
+      trace_id, parent_span_id, sampled_flag = match[1..3]
+
+      parent_sampled =
+        if sampled_flag.nil?
+          nil
+        else
+          sampled_flag != "0"
+        end
+
+      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)
+
+      @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 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
+
+      return unless @sampled.nil?
+
+      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
+
+      unless [true, false].include?(sample_rate) || (sample_rate.is_a?(Numeric) && sample_rate >= 0.0 && sample_rate <= 1.0)
+        @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)
+      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() # Span#finish doesn't take arguments
+
+      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
+
+    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
+
+    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,29 @@
+# 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 [Float, nil]
+    attr_reader :start_timestamp
+
+    # 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
+    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