sentry-ruby-core 4.4.0 → 5.1.1

data/lib/sentry/span.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 require "securerandom"
 
 module Sentry
@@ -17,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,
@@ -44,6 +85,8 @@ module Sentry
       @tags = {}
     end
 
+    # Finishes the span by adding a timestamp.
+    # @return [self]
     def finish
       # already finished
       return if @timestamp
@@ -52,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?
@@ -59,6 +104,7 @@ module Sentry
       "#{@trace_id}-#{@span_id}-#{sampled_flag}"
     end
 
+    # @return [Hash]
     def to_hash
       {
         trace_id: @trace_id,
@@ -74,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,
@@ -85,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
 
@@ -98,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)
 
@@ -110,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)
@@ -139,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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Sentry
   class Transaction < Span
     SENTRY_TRACE_REGEXP = Regexp.new(
@@ -12,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)
@@ -21,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
@@ -44,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)
@@ -63,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
@@ -111,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(
@@ -129,10 +164,12 @@ module Sentry
         @name = UNLABELD_NAME
       end
 
-      return unless @sampled || @parent_sampled
-
-      event = hub.current_client.event_from_transaction(self)
-      hub.capture_event(event)
+      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

data/lib/sentry/transaction_event.rb

@@ -4,24 +4,37 @@ module Sentry
   class TransactionEvent < Event
     TYPE = "transaction"
 
-    ATTRIBUTES = %i(
+    SERIALIZEABLE_ATTRIBUTES = %i(
       event_id level timestamp start_timestamp
       release environment server_name modules
       user tags contexts extra
       transaction platform sdk type
     )
 
-    attr_accessor(*ATTRIBUTES)
+    WRITER_ATTRIBUTES = SERIALIZEABLE_ATTRIBUTES - %i(type timestamp start_timestamp level)
+
+    attr_writer(*WRITER_ATTRIBUTES)
+    attr_reader(*SERIALIZEABLE_ATTRIBUTES)
+
+    # @return [<Array[Span]>]
     attr_accessor :spans
 
-    def start_timestamp=(time)
-      @start_timestamp = time.is_a?(Time) ? time.to_f : time
+    # @param configuration [Configuration]
+    # @param integration_meta [Hash, nil]
+    # @param message [String, nil]
+    def initialize(configuration:, integration_meta: nil, message: nil)
+      super
+      @type = TYPE
     end
 
-    def type
-      TYPE
+    # 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

@@ -1,8 +1,10 @@
+# frozen_string_literal: true
+
 module Sentry
   class Transport
     class Configuration
-      attr_accessor :timeout, :open_timeout, :proxy, :ssl, :ssl_ca_file, :ssl_verification, :http_adapter, :faraday_builder,
-        :transport_class, :encoding
+      attr_accessor :timeout, :open_timeout, :proxy, :ssl, :ssl_ca_file, :ssl_verification, :encoding
+      attr_reader :transport_class
 
       def initialize
         @ssl_verification = true

data/lib/sentry/transport/dummy_transport.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Sentry
   class DummyTransport < Transport
     attr_accessor :events

data/lib/sentry/transport/http_transport.rb

@@ -1,5 +1,7 @@
-require 'faraday'
-require 'zlib'
+# frozen_string_literal: true
+
+require "net/http"
+require "zlib"
 
 module Sentry
   class HTTPTransport < Transport
@@ -10,14 +12,13 @@ module Sentry
     DEFAULT_DELAY = 60
     RETRY_AFTER_HEADER = "retry-after"
     RATE_LIMIT_HEADER = "x-sentry-rate-limits"
-
-    attr_reader :conn, :adapter
+    USER_AGENT = "sentry-ruby/#{Sentry::VERSION}"
 
     def initialize(*args)
       super
-      @adapter = @transport_configuration.http_adapter || Faraday.default_adapter
-      @conn = set_conn
       @endpoint = @dsn.envelope_endpoint
+
+      log_debug("Sentry HTTP Transport will connect to #{@dsn.server}")
     end
 
     def send_data(data)
@@ -28,29 +29,37 @@ module Sentry
         encoding = GZIP_ENCODING
       end
 
-      response = conn.post @endpoint do |req|
-        req.headers['Content-Type'] = CONTENT_TYPE
-        req.headers['Content-Encoding'] = encoding
-        req.headers['X-Sentry-Auth'] = generate_auth_header
-        req.body = data
+      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 has_rate_limited_header?(response.headers)
-        handle_rate_limited_response(response.headers)
-      end
-    rescue Faraday::Error => e
-      error_info = e.message
+      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 e.response
-        if e.response[:status] == 429
-          handle_rate_limited_response(e.response[:headers])
+        if response.code == "429"
+          handle_rate_limited_response(response)
         else
-          error_info += "\nbody: #{e.response[:body]}"
-          error_info += " Error in headers is: #{e.response[:headers]['x-sentry-error']}" if e.response[:headers]['x-sentry-error']
+          error_info += "\nbody: #{response.body}"
+          error_info += " Error in headers is: #{response['x-sentry-error']}" if response['x-sentry-error']
         end
-      end
 
-      raise Sentry::ExternalError, error_info
+        raise Sentry::ExternalError, error_info
+      end
+    rescue SocketError => e
+      raise Sentry::ExternalError.new(e.message)
     end
 
     private
@@ -117,32 +126,36 @@ module Sentry
       @transport_configuration.encoding == GZIP_ENCODING && data.bytesize >= GZIP_THRESHOLD
     end
 
-    def set_conn
-      server = @dsn.server
+    def conn
+      server = URI(@dsn.server)
 
-      log_debug("Sentry HTTP Transport connecting to #{server}")
+      connection =
+        if 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
 
-      Faraday.new(server, :ssl => ssl_configuration, :proxy => @transport_configuration.proxy) do |builder|
-        @transport_configuration.faraday_builder&.call(builder)
-        builder.response :raise_error
-        builder.options.merge! faraday_opts
-        builder.headers[:user_agent] = "sentry-ruby/#{Sentry::VERSION}"
-        builder.adapter(*adapter)
-      end
-    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
 
-    # TODO: deprecate and replace where possible w/Faraday Builder
-    def faraday_opts
-      [:timeout, :open_timeout].each_with_object({}) do |opt, memo|
-        memo[opt] = @transport_configuration.public_send(opt) if @transport_configuration.public_send(opt)
+      ssl_configuration.each do |key, value|
+        connection.send("#{key}=", value)
       end
+
+      connection
     end
 
     def ssl_configuration
-      (@transport_configuration.ssl || {}).merge(
-        :verify => @transport_configuration.ssl_verification,
-        :ca_file => @transport_configuration.ssl_ca_file
-      )
+      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

data/lib/sentry/transport.rb

@@ -1,22 +1,44 @@
+# frozen_string_literal: true
+
 require "json"
 require "base64"
+require "sentry/envelope"
 
 module Sentry
   class Transport
-    PROTOCOL_VERSION = '5'
+    PROTOCOL_VERSION = '7'
     USER_AGENT = "sentry-ruby/#{Sentry::VERSION}"
+    CLIENT_REPORT_INTERVAL = 30
+
+    # https://develop.sentry.dev/sdk/client-reports/#envelope-item-payload
+    CLIENT_REPORT_REASONS = [
+      :ratelimit_backoff,
+      :queue_overflow,
+      :cache_overflow, # NA
+      :network_error,
+      :sample_rate,
+      :before_send,
+      :event_processor
+    ]
 
     include LoggingHelper
 
-    attr_accessor :configuration
-    attr_reader :logger, :rate_limits
+    attr_reader :rate_limits, :discarded_events, :last_client_report_sent
+
+    # @deprecated Use Sentry.logger to retrieve the current logger instead.
+    attr_reader :logger
 
     def initialize(configuration)
-      @configuration = configuration
       @logger = configuration.logger
       @transport_configuration = configuration.transport
       @dsn = configuration.dsn
       @rate_limits = {}
+      @send_client_reports = configuration.send_client_reports
+
+      if @send_client_reports
+        @discarded_events = Hash.new(0)
+        @last_client_report_sent = Time.now
+      end
     end
 
     def send_data(data, options = {})
@@ -24,28 +46,19 @@ module Sentry
     end
 
     def send_event(event)
-      event_hash = event.to_hash
-      item_type = get_item_type(event_hash)
-
-      unless configuration.sending_allowed?
-        log_debug("Envelope [#{item_type}] not sent: #{configuration.error_messages}")
+      envelope = envelope_from_event(event)
+      send_envelope(envelope)
 
-        return
-      end
-
-      if is_rate_limited?(item_type)
-        log_info("Envelope [#{item_type}] not sent: rate limiting")
-
-        return
-      end
-
-      encoded_data = encode(event)
+      event
+    end
 
-      return nil unless encoded_data
+    def send_envelope(envelope)
+      reject_rate_limited_items(envelope)
 
-      send_data(encoded_data)
+      return if envelope.items.empty?
 
-      event
+      log_info("[Transport] Sending envelope with items [#{envelope.item_types.join(', ')}] #{envelope.event_id} to Sentry")
+      send_data(envelope.to_s)
     end
 
     def is_rate_limited?(item_type)
@@ -89,29 +102,85 @@ module Sentry
       'Sentry ' + fields.map { |key, value| "#{key}=#{value}" }.join(', ')
     end
 
-    def encode(event)
+    def envelope_from_event(event)
       # Convert to hash
-      event_hash = event.to_hash
+      event_payload = event.to_hash
+      event_id = event_payload[:event_id] || event_payload["event_id"]
+      item_type = get_item_type(event_payload)
 
-      event_id = event_hash[:event_id] || event_hash["event_id"]
-      item_type = get_item_type(event_hash)
+      envelope = Envelope.new(
+        {
+          event_id: event_id,
+          dsn: @dsn.to_s,
+          sdk: Sentry.sdk_meta,
+          sent_at: Sentry.utc_now.iso8601
+        }
+      )
 
-      envelope = <<~ENVELOPE
-        {"event_id":"#{event_id}","dsn":"#{configuration.dsn.to_s}","sdk":#{Sentry.sdk_meta.to_json},"sent_at":"#{Sentry.utc_now.iso8601}"}
-        {"type":"#{item_type}","content_type":"application/json"}
-        #{JSON.generate(event_hash)}
-      ENVELOPE
+      envelope.add_item(
+        { type: item_type, content_type: 'application/json' },
+        event_payload
+      )
+
+      client_report_headers, client_report_payload = fetch_pending_client_report
+      envelope.add_item(client_report_headers, client_report_payload) if client_report_headers
 
-      log_info("Sending envelope [#{item_type}] #{event_id} to Sentry")
 
       envelope
     end
 
+    def record_lost_event(reason, item_type)
+      return unless @send_client_reports
+      return unless CLIENT_REPORT_REASONS.include?(reason)
+
+      item_type ||= 'event'
+      @discarded_events[[reason, item_type]] += 1
+    end
+
     private
 
     def get_item_type(event_hash)
       event_hash[:type] || event_hash["type"] || "event"
     end
+
+    def fetch_pending_client_report
+      return nil unless @send_client_reports
+      return nil if @last_client_report_sent > Time.now - CLIENT_REPORT_INTERVAL
+      return nil if @discarded_events.empty?
+
+      discarded_events_hash = @discarded_events.map do |key, val|
+        reason, type = key
+
+        # 'event' has to be mapped to 'error'
+        category = type == 'transaction' ? 'transaction' : 'error'
+
+        { reason: reason, category: category, quantity: val }
+      end
+
+      item_header = { type: 'client_report' }
+      item_payload = {
+        timestamp: Sentry.utc_now.iso8601,
+        discarded_events: discarded_events_hash
+      }
+
+      @discarded_events = Hash.new(0)
+      @last_client_report_sent = Time.now
+
+      [item_header, item_payload]
+    end
+
+    def reject_rate_limited_items(envelope)
+      envelope.items.reject! do |item|
+        if is_rate_limited?(item.type)
+          log_info("[Transport] Envelope item [#{item.type}] not sent: rate limiting")
+          record_lost_event(:ratelimit_backoff, item.type)
+
+          true
+        else
+          false
+        end
+      end
+    end
   end
 end