sentry-ruby 5.23.0 → 5.27.0

data/lib/sentry/structured_logger.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module Sentry
+  # The StructuredLogger class implements Sentry's SDK telemetry logs protocol.
+  # It provides methods for logging messages at different severity levels and
+  # sending them to Sentry with structured data.
+  #
+  # This class follows the Sentry Logs Protocol as defined in:
+  # https://develop.sentry.dev/sdk/telemetry/logs/
+  #
+  # @example Basic usage
+  #   Sentry.logger.info("User logged in", user_id: 123)
+  #
+  # @example With structured data
+  #   Sentry.logger.warn("API request failed",
+  #     status_code: 404,
+  #     endpoint: "/api/users",
+  #     request_id: "abc-123"
+  #   )
+  #
+  # @example With a message template
+  #   # Using positional parameters
+  #   Sentry.logger.info("User %s logged in", ["Jane Doe"])
+  #
+  #   # Using hash parameters
+  #   Sentry.logger.info("User %{name} logged in", name: "Jane Doe")
+  #
+  #   # Using hash parameters and extra attributes
+  #   Sentry.logger.info("User %{name} logged in", name: "Jane Doe", user_id: 312)
+  #
+  # @see https://develop.sentry.dev/sdk/telemetry/logs/ Sentry SDK Telemetry Logs Protocol
+  class StructuredLogger
+    # Severity number mapping for log levels according to the Sentry Logs Protocol
+    # @see https://develop.sentry.dev/sdk/telemetry/logs/#log-severity-number
+    LEVELS = {
+      trace: 1,
+      debug: 5,
+      info: 9,
+      warn: 13,
+      error: 17,
+      fatal: 21
+    }.freeze
+
+    # @return [Configuration] The Sentry configuration
+    # @!visibility private
+    attr_reader :config
+
+    # Initializes a new StructuredLogger instance
+    #
+    # @param config [Configuration] The Sentry configuration
+    def initialize(config)
+      @config = config
+    end
+
+    # Logs a message at TRACE level
+    #
+    # @param message [String] The log message
+    # @param parameters [Array] Array of values to replace template parameters in the message
+    # @param attributes [Hash] Additional attributes to include with the log
+    #
+    # @return [LogEvent, nil] The created log event or nil if logging is disabled
+    def trace(message, parameters = [], **attributes)
+      log(__method__, message, parameters: parameters, **attributes)
+    end
+
+    # Logs a message at DEBUG level
+    #
+    # @param message [String] The log message
+    # @param parameters [Array] Array of values to replace template parameters in the message
+    # @param attributes [Hash] Additional attributes to include with the log
+    #
+    # @return [LogEvent, nil] The created log event or nil if logging is disabled
+    def debug(message, parameters = [], **attributes)
+      log(__method__, message, parameters: parameters, **attributes)
+    end
+
+    # Logs a message at INFO level
+    #
+    # @param message [String] The log message
+    # @param parameters [Array] Array of values to replace template parameters in the message
+    # @param attributes [Hash] Additional attributes to include with the log
+    #
+    # @return [LogEvent, nil] The created log event or nil if logging is disabled
+    def info(message, parameters = [], **attributes)
+      log(__method__, message, parameters: parameters, **attributes)
+    end
+
+    # Logs a message at WARN level
+    #
+    # @param message [String] The log message
+    # @param parameters [Array] Array of values to replace template parameters in the message
+    # @param attributes [Hash] Additional attributes to include with the log
+    #
+    # @return [LogEvent, nil] The created log event or nil if logging is disabled
+    def warn(message, parameters = [], **attributes)
+      log(__method__, message, parameters: parameters, **attributes)
+    end
+
+    # Logs a message at ERROR level
+    #
+    # @param message [String] The log message
+    # @param parameters [Array] Array of values to replace template parameters in the message
+    # @param attributes [Hash] Additional attributes to include with the log
+    #
+    # @return [LogEvent, nil] The created log event or nil if logging is disabled
+    def error(message, parameters = [], **attributes)
+      log(__method__, message, parameters: parameters, **attributes)
+    end
+
+    # Logs a message at FATAL level
+    #
+    # @param message [String] The log message
+    # @param parameters [Array] Array of values to replace template parameters in the message
+    # @param attributes [Hash] Additional attributes to include with the log
+    #
+    # @return [LogEvent, nil] The created log event or nil if logging is disabled
+    def fatal(message, parameters = [], **attributes)
+      log(__method__, message, parameters: parameters, **attributes)
+    end
+
+    # Logs a message at the specified level
+    #
+    # @param level [Symbol] The log level (:trace, :debug, :info, :warn, :error, :fatal)
+    # @param message [String] The log message
+    # @param parameters [Array, Hash] Array or Hash of values to replace template parameters in the message
+    # @param attributes [Hash] Additional attributes to include with the log
+    #
+    # @return [LogEvent, nil] The created log event or nil if logging is disabled
+    def log(level, message, parameters:, **attributes)
+      case parameters
+      when Array then
+        Sentry.capture_log(message, level: level, severity: LEVELS[level], parameters: parameters, **attributes)
+      else
+        Sentry.capture_log(message, level: level, severity: LEVELS[level], **parameters)
+      end
+    end
+  end
+end

data/lib/sentry/test_helper.rb

@@ -2,8 +2,13 @@
 
 module Sentry
   module TestHelper
+    module_function
+
     DUMMY_DSN = "http://12345:67890@sentry.localdomain/sentry/42"
 
+    # Not really real, but it will be resolved as a non-local for testing needs
+    REAL_DSN = "https://user:pass@getsentry.io/project/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.
@@ -46,6 +51,8 @@ module Sentry
     def teardown_sentry_test
       return unless Sentry.initialized?
 
+      clear_sentry_events
+
       # pop testing layer created by `setup_sentry_test`
       # but keep the base layer to avoid nil-pointer errors
       # TODO: find a way to notify users if they somehow popped the test layer before calling this method
@@ -55,6 +62,21 @@ module Sentry
       Sentry::Scope.global_event_processors.clear
     end
 
+    def clear_sentry_events
+      return unless Sentry.initialized?
+
+      sentry_transport.clear if sentry_transport.respond_to?(:clear)
+
+      if Sentry.configuration.enable_logs && sentry_logger.respond_to?(:clear)
+        sentry_logger.clear
+      end
+    end
+
+    # @return [Sentry::StructuredLogger, Sentry::DebugStructuredLogger]
+    def sentry_logger
+      Sentry.logger
+    end
+
     # @return [Transport]
     def sentry_transport
       Sentry.get_current_client.transport
@@ -72,6 +94,13 @@ module Sentry
       sentry_transport.envelopes
     end
 
+    def sentry_logs
+      sentry_envelopes
+        .flat_map(&:items)
+        .select { |item| item.headers[:type] == "log" }
+        .flat_map { |item| item.payload[:items] }
+    end
+
     # Returns the last captured event object.
     # @return [Event, nil]
     def last_sentry_event

data/lib/sentry/threaded_periodic_worker.rb

@@ -4,11 +4,11 @@ module Sentry
   class ThreadedPeriodicWorker
     include LoggingHelper
 
-    def initialize(logger, internal)
+    def initialize(sdk_logger, interval)
       @thread = nil
       @exited = false
-      @interval = internal
-      @logger = logger
+      @interval = interval
+      @sdk_logger = sdk_logger
     end
 
     def ensure_thread

data/lib/sentry/transaction.rb

@@ -2,6 +2,7 @@
 
 require "sentry/baggage"
 require "sentry/profiler"
+require "sentry/utils/sample_rand"
 require "sentry/propagation_context"
 
 module Sentry
@@ -45,9 +46,6 @@ module Sentry
     # @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
@@ -60,12 +58,17 @@ module Sentry
     # @return [Profiler]
     attr_reader :profiler
 
+    # Sample rand value generated from trace_id
+    # @return [String]
+    attr_reader :sample_rand
+
     def initialize(
       hub:,
       name: nil,
       source: :custom,
       parent_sampled: nil,
       baggage: nil,
+      sample_rand: nil,
       **options
     )
       super(transaction: self, **options)
@@ -78,19 +81,25 @@ module Sentry
       @tracing_enabled = hub.configuration.tracing_enabled?
       @traces_sampler = hub.configuration.traces_sampler
       @traces_sample_rate = hub.configuration.traces_sample_rate
-      @logger = hub.configuration.logger
+      @sdk_logger = hub.configuration.sdk_logger
       @release = hub.configuration.release
       @environment = hub.configuration.environment
       @dsn = hub.configuration.dsn
       @effective_sample_rate = nil
       @contexts = {}
       @measurements = {}
+      @sample_rand = sample_rand
 
       unless @hub.profiler_running?
         @profiler = @configuration.profiler_class.new(@configuration)
       end
 
       init_span_recorder
+
+      unless @sample_rand
+        generator = Utils::SampleRand.new(trace_id: @trace_id)
+        @sample_rand = generator.generate_from_trace_id
+      end
     end
 
     # @deprecated use Sentry.continue_trace instead.
@@ -126,12 +135,15 @@ module Sentry
 
       baggage.freeze!
 
+      sample_rand = extract_sample_rand_from_baggage(baggage, trace_id, parent_sampled)
+
       new(
         trace_id: trace_id,
         parent_span_id: parent_span_id,
         parent_sampled: parent_sampled,
         hub: hub,
         baggage: baggage,
+        sample_rand: sample_rand,
         **options
       )
     end
@@ -142,6 +154,11 @@ module Sentry
       PropagationContext.extract_sentry_trace(sentry_trace)
     end
 
+    def self.extract_sample_rand_from_baggage(baggage, trace_id, parent_sampled)
+      PropagationContext.extract_sample_rand_from_baggage(baggage, trace_id) ||
+        PropagationContext.generate_sample_rand(baggage, trace_id, parent_sampled)
+    end
+
     # @return [Hash]
     def to_hash
       hash = super
@@ -156,6 +173,13 @@ module Sentry
       hash
     end
 
+    def parent_sample_rate
+      return unless @baggage&.items
+
+      sample_rate_str = @baggage.items["sample_rate"]
+      sample_rate_str&.to_f
+    end
+
     # @return [Transaction]
     def deep_dup
       copy = super
@@ -228,7 +252,7 @@ module Sentry
           @effective_sample_rate /= 2**factor
         end
 
-        @sampled = Random.rand < @effective_sample_rate
+        @sampled = @sample_rand < @effective_sample_rate
       end
 
       if @sampled
@@ -334,6 +358,7 @@ module Sentry
       items = {
         "trace_id" => trace_id,
         "sample_rate" => effective_sample_rate&.to_s,
+        "sample_rand" => Utils::SampleRand.format(@sample_rand),
         "sampled" => sampled&.to_s,
         "environment" => @environment,
         "release" => @release,
@@ -342,9 +367,6 @@ module Sentry
 
       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

data/lib/sentry/transport/debug_transport.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+require "pathname"
+require "delegate"
+
+module Sentry
+  # DebugTransport is a transport that logs events to a file for debugging purposes.
+  #
+  # It can optionally also send events to Sentry via HTTP transport if a real DSN
+  # is provided.
+  class DebugTransport < SimpleDelegator
+    DEFAULT_LOG_FILE_PATH = File.join("log", "sentry_debug_events.log")
+
+    attr_reader :log_file, :backend
+
+    def initialize(configuration)
+      @log_file = initialize_log_file(configuration)
+      @backend = initialize_backend(configuration)
+
+      super(@backend)
+    end
+
+    def send_event(event)
+      log_envelope(envelope_from_event(event))
+      backend.send_event(event)
+    end
+
+    def log_envelope(envelope)
+      envelope_json = {
+        timestamp: Time.now.utc.iso8601,
+        envelope_headers: envelope.headers,
+        items: envelope.items.map do |item|
+          { headers: item.headers, payload: item.payload }
+        end
+      }
+
+      File.open(log_file, "a") { |file| file << JSON.dump(envelope_json) << "\n" }
+    end
+
+    def logged_envelopes
+      return [] unless File.exist?(log_file)
+
+      File.readlines(log_file).map do |line|
+        JSON.parse(line)
+      end
+    end
+
+    def clear
+      File.write(log_file, "")
+      log_debug("DebugTransport: Cleared events from #{log_file}")
+    end
+
+    private
+
+    def initialize_backend(configuration)
+      backend = configuration.dsn.local? ? DummyTransport : HTTPTransport
+      backend.new(configuration)
+    end
+
+    def initialize_log_file(configuration)
+      log_file = Pathname(configuration.sdk_debug_transport_log_file || DEFAULT_LOG_FILE_PATH)
+
+      FileUtils.mkdir_p(log_file.dirname) unless log_file.dirname.exist?
+
+      log_file
+    end
+  end
+end

data/lib/sentry/transport/dummy_transport.rb

@@ -12,6 +12,7 @@ module Sentry
 
     def send_event(event)
       @events << event
+      super
     end
 
     def send_envelope(envelope)

data/lib/sentry/transport/http_transport.rb

@@ -45,11 +45,7 @@ module Sentry
       auth_header = generate_auth_header
       headers["X-Sentry-Auth"] = auth_header if auth_header
 
-      response = conn.start do |http|
-        request = ::Net::HTTP::Post.new(endpoint, headers)
-        request.body = data
-        http.request(request)
-      end
+      response = do_request(endpoint, headers, data)
 
       if response.code.match?(/\A2\d{2}/)
         handle_rate_limited_response(response) if has_rate_limited_header?(response)
@@ -111,6 +107,14 @@ module Sentry
       connection
     end
 
+    def do_request(endpoint, headers, body)
+      conn.start do |http|
+        request = ::Net::HTTP::Post.new(endpoint, headers)
+        request.body = body
+        http.request(request)
+      end
+    end
+
     private
 
     def has_rate_limited_header?(headers)

data/lib/sentry/transport.rb

@@ -26,11 +26,8 @@ module Sentry
 
     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)
-      @logger = configuration.logger
+      @sdk_logger = configuration.sdk_logger
       @transport_configuration = configuration.transport
       @dsn = configuration.dsn
       @rate_limits = {}
@@ -133,10 +130,21 @@ module Sentry
 
       envelope = Envelope.new(envelope_headers)
 
-      envelope.add_item(
-        { type: item_type, content_type: "application/json" },
-        event_payload
-      )
+      if event.is_a?(LogEvent)
+        envelope.add_item(
+          {
+            type: "log",
+            item_count: 1,
+            content_type: "application/vnd.sentry.items.log+json"
+          },
+          { items: [event_payload] }
+        )
+      else
+        envelope.add_item(
+          { type: item_type, content_type: "application/json" },
+          event_payload
+        )
+      end
 
       if event.is_a?(TransactionEvent) && event.profile
         envelope.add_item(
@@ -215,3 +223,4 @@ end
 require "sentry/transport/dummy_transport"
 require "sentry/transport/http_transport"
 require "sentry/transport/spotlight_transport"
+require "sentry/transport/debug_transport"

data/lib/sentry/utils/logging_helper.rb

@@ -1,22 +1,29 @@
 # frozen_string_literal: true
 
 module Sentry
+  # @private
   module LoggingHelper
+    # @!visibility private
+    attr_reader :sdk_logger
+
+    # @!visibility private
     def log_error(message, exception, debug: false)
       message = "#{message}: #{exception.message}"
       message += "\n#{exception.backtrace.join("\n")}" if debug
 
-      @logger.error(LOGGER_PROGNAME) do
+      sdk_logger.error(LOGGER_PROGNAME) do
         message
       end
     end
 
+    # @!visibility private
     def log_debug(message)
-      @logger.debug(LOGGER_PROGNAME) { message }
+      sdk_logger.debug(LOGGER_PROGNAME) { message }
     end
 
+    # @!visibility private
     def log_warn(message)
-      @logger.warn(LOGGER_PROGNAME) { message }
+      sdk_logger.warn(LOGGER_PROGNAME) { message }
     end
   end
 end

data/lib/sentry/utils/sample_rand.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Sentry
+  module Utils
+    class SampleRand
+      PRECISION = 1_000_000.0
+      FORMAT_PRECISION = 6
+
+      attr_reader :trace_id
+
+      def self.valid?(value)
+        return false unless value
+        value >= 0.0 && value < 1.0
+      end
+
+      def self.format(value)
+        return unless value
+
+        truncated = (value * PRECISION).floor / PRECISION
+        "%.#{FORMAT_PRECISION}f" % truncated
+      end
+
+      def initialize(trace_id: nil)
+        @trace_id = trace_id
+      end
+
+      def generate_from_trace_id
+        (random_from_trace_id * PRECISION).floor / PRECISION
+      end
+
+      def generate_from_sampling_decision(sampled, sample_rate)
+        if invalid_sample_rate?(sample_rate)
+          fallback_generation
+        else
+          generate_based_on_sampling(sampled, sample_rate)
+        end
+      end
+
+      def generate_from_value(sample_rand_value)
+        parsed_value = parse_value(sample_rand_value)
+
+        if self.class.valid?(parsed_value)
+          parsed_value
+        else
+          fallback_generation
+        end
+      end
+
+      private
+
+      def random_from_trace_id
+        if @trace_id
+          Random.new(@trace_id[0, 16].to_i(16))
+        else
+          Random.new
+        end.rand(1.0)
+      end
+
+      def invalid_sample_rate?(sample_rate)
+        sample_rate.nil? || sample_rate <= 0.0 || sample_rate > 1.0
+      end
+
+      def fallback_generation
+        if @trace_id
+          (random_from_trace_id * PRECISION).floor / PRECISION
+        else
+          format_random(Random.rand(1.0))
+        end
+      end
+
+      def generate_based_on_sampling(sampled, sample_rate)
+        random = random_from_trace_id
+
+        result = if sampled
+          random * sample_rate
+        elsif sample_rate == 1.0
+          random
+        else
+          sample_rate + random * (1.0 - sample_rate)
+        end
+
+        format_random(result)
+      end
+
+      def format_random(value)
+        truncated = (value * PRECISION).floor / PRECISION
+        ("%.#{FORMAT_PRECISION}f" % truncated).to_f
+      end
+
+      def parse_value(sample_rand_value)
+        Float(sample_rand_value)
+      rescue ArgumentError
+        nil
+      end
+    end
+  end
+end

data/lib/sentry/utils/uuid.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Sentry
+  module Utils
+    DELIMITER = "-"
+
+    def self.uuid
+      SecureRandom.uuid.delete(DELIMITER)
+    end
+  end
+end

data/lib/sentry/vernier/profiler.rb

@@ -3,6 +3,7 @@
 require "securerandom"
 require_relative "../profiler/helpers"
 require_relative "output"
+require "sentry/utils/uuid"
 
 module Sentry
   module Vernier
@@ -12,7 +13,7 @@ module Sentry
       attr_reader :started, :event_id, :result
 
       def initialize(configuration)
-        @event_id = SecureRandom.uuid.delete("-")
+        @event_id = Utils.uuid
 
         @started = false
         @sampled = nil
@@ -103,7 +104,7 @@ module Sentry
       private
 
       def log(message)
-        Sentry.logger.debug(LOGGER_PROGNAME) { "[Profiler::Vernier] #{message}" }
+        Sentry.sdk_logger.debug(LOGGER_PROGNAME) { "[Profiler::Vernier] #{message}" }
       end
 
       def record_lost_event(reason)

data/lib/sentry/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Sentry
-  VERSION = "5.23.0"
+  VERSION = "5.27.0"
 end