sentry-ruby 5.26.0 → 5.28.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eb03eb536d1060c3a097a1ff3726ae71c8ffbd0012580d75c491665e054ac7c1
-  data.tar.gz: 65df577369b281f3e1d1d9335e78786a800947c2014b35608d88c863458f24ca
+  metadata.gz: 0a048bcf517a994eb2577cc8f9630e7771f0dbe9a80cff9a93e1d4d68186db49
+  data.tar.gz: 97d7489043a301a9fdfed0d9ca31d38156c5082a0a2e43e83592d86e9eba939d
 SHA512:
-  metadata.gz: b4e398e02a8fe619afc8982760c290a168785c4557dca30767fbeb039032d7907135e84d0598a5ac90b7b1cfb8413ceda83ebe4647702ba5c10c613ff0543574
-  data.tar.gz: 285a3e0f650a41bcb6cc4539f48c7efcb9bc3442f31c76f301089c4672e6d9c790f407dd9d53db4e216df4eacd9be019b5bc46e453437fa1614aa48555541c9a
+  metadata.gz: 17466b57a83b0292b367b43dcf7c22128ae93822ab7481f3afb3459c52842c917c57d3b2274a3e377fcfd089ab10efa1e12bdd7401a991018387fb026e5fe014
+  data.tar.gz: cbea0779676929f05597e84da1e4cd7cc25fa0a6d383c8d08e6e26112e9bbe90403d14fdebaa8164a18d5db894ec286d22e5611da217a7bd5efb9279119ace33

data/Gemfile

@@ -3,7 +3,7 @@
 source "https://rubygems.org"
 git_source(:github) { |name| "https://github.com/#{name}.git" }
 
-eval_gemfile "../Gemfile"
+eval_gemfile "../Gemfile.dev"
 
 gem "sentry-ruby", path: "./"
 
@@ -11,8 +11,6 @@ rack_version = ENV["RACK_VERSION"]
 rack_version = "3.0.0" if rack_version.nil?
 gem "rack", "~> #{Gem::Version.new(rack_version)}" unless rack_version == "0"
 
-gem "ostruct" if RUBY_VERSION >= "3.4"
-
 redis_rb_version = ENV.fetch("REDIS_RB_VERSION", "5.0")
 gem "redis", "~> #{redis_rb_version}"
 

data/lib/sentry/client.rb

@@ -195,9 +195,10 @@ module Sentry
     def event_from_log(message, level:, **options)
       return unless configuration.sending_allowed?
 
-      attributes = options.reject { |k, _| k == :level || k == :severity }
+      attributes = options.reject { |k, _| k == :level || k == :severity || k == :origin }
+      origin = options[:origin]
 
-      LogEvent.new(level: level, body: message, attributes: attributes)
+      LogEvent.new(level: level, body: message, attributes: attributes, origin: origin)
     end
 
     # Initializes an Event object with the given Transaction object.

data/lib/sentry/configuration.rb

@@ -13,6 +13,7 @@ require "sentry/metrics/configuration"
 require "sentry/linecache"
 require "sentry/interfaces/stacktrace_builder"
 require "sentry/logger"
+require "sentry/structured_logger"
 require "sentry/log_event_buffer"
 
 module Sentry
@@ -196,6 +197,11 @@ module Sentry
     # @return [Logger]
     attr_accessor :sdk_logger
 
+    # File path for DebugTransport to log events to. If not set, defaults to a temporary file.
+    # This is useful for debugging and testing purposes.
+    # @return [String, nil]
+    attr_accessor :sdk_debug_transport_log_file
+
     # @deprecated Use {#sdk_logger=} instead.
     def logger=(logger)
       warn "[sentry] `config.logger=` is deprecated. Please use `config.sdk_logger=` instead."
@@ -289,6 +295,10 @@ module Sentry
     # @return [Boolean]
     attr_accessor :enable_logs
 
+    # Structured logging configuration.
+    # @return [StructuredLoggingConfiguration]
+    attr_reader :structured_logging
+
     # Easier way to use performance tracing
     # If set to true, will set traces_sample_rate to 1.0
     # @deprecated It will be removed in the next major release.
@@ -390,7 +400,23 @@ module Sentry
 
       # allow extensions to add their hooks to the Configuration class
       def add_post_initialization_callback(&block)
-        post_initialization_callbacks << block
+        callbacks[:initialize][:after] << block
+      end
+
+      def before(event, &block)
+        callbacks[event.to_sym][:before] << block
+      end
+
+      def after(event, &block)
+        callbacks[event.to_sym][:after] << block
+      end
+
+      # @!visibility private
+      def callbacks
+        @callbacks ||= {
+          initialize: { before: [], after: [] },
+          configured: { before: [], after: [] }
+        }
       end
 
       def validations
@@ -434,6 +460,8 @@ module Sentry
     validate :profiles_sample_rate, optional: true, type: :numeric
 
     def initialize
+      run_callbacks(:before, :initialize)
+
       self.app_dirs_pattern = APP_DIRS_PATTERN
       self.debug = Sentry::Utils::EnvHelper.env_to_bool(ENV["SENTRY_DEBUG"])
       self.background_worker_threads = (processor_count / 2.0).ceil
@@ -484,12 +512,17 @@ module Sentry
 
       @transport = Transport::Configuration.new
       @cron = Cron::Configuration.new
-      @metrics = Metrics::Configuration.new
+      @metrics = Metrics::Configuration.new(self.sdk_logger)
+      @structured_logging = StructuredLoggingConfiguration.new
       @gem_specs = Hash[Gem::Specification.map { |spec| [spec.name, spec.version.to_s] }] if Gem::Specification.respond_to?(:map)
 
-      run_post_initialization_callbacks
-
       self.max_log_events = LogEventBuffer::DEFAULT_MAX_EVENTS
+
+      run_callbacks(:after, :initialize)
+
+      yield(self) if block_given?
+
+      run_callbacks(:after, :configured)
     end
 
     def validate
@@ -773,8 +806,8 @@ module Sentry
       File.directory?("/etc/heroku") && !ENV["CI"]
     end
 
-    def run_post_initialization_callbacks
-      self.class.post_initialization_callbacks.each do |hook|
+    def run_callbacks(hook, event)
+      self.class.callbacks[event][hook].each do |hook|
         instance_eval(&hook)
       end
     end
@@ -784,4 +817,19 @@ module Sentry
       available_processor_count || Concurrent.processor_count
     end
   end
+
+  class StructuredLoggingConfiguration
+    # File path for DebugStructuredLogger to log events to
+    # @return [String, Pathname, nil]
+    attr_accessor :file_path
+
+    # The class to use as a structured logger.
+    # @return [Class]
+    attr_accessor :logger_class
+
+    def initialize
+      @file_path = nil
+      @logger_class = Sentry::StructuredLogger
+    end
+  end
 end

data/lib/sentry/debug_structured_logger.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+require "pathname"
+require "delegate"
+
+module Sentry
+  # DebugStructuredLogger is a logger that captures structured log events to a file for debugging purposes.
+  #
+  # It can optionally also send log events to Sentry via the normal structured logger if logging
+  # is enabled.
+  class DebugStructuredLogger < SimpleDelegator
+    DEFAULT_LOG_FILE_PATH = File.join("log", "sentry_debug_logs.log")
+
+    attr_reader :log_file, :backend
+
+    def initialize(configuration)
+      @log_file = initialize_log_file(
+        configuration.structured_logging.file_path || DEFAULT_LOG_FILE_PATH
+      )
+      @backend = initialize_backend(configuration)
+
+      super(@backend)
+    end
+
+    # Override all log level methods to capture events
+    %i[trace debug info warn error fatal].each do |level|
+      define_method(level) do |message, parameters = [], **attributes|
+        log_event = capture_log_event(level, message, parameters, **attributes)
+        backend.public_send(level, message, parameters, **attributes)
+        log_event
+      end
+    end
+
+    def log(level, message, parameters:, **attributes)
+      log_event = capture_log_event(level, message, parameters, **attributes)
+      backend.log(level, message, parameters: parameters, **attributes)
+      log_event
+    end
+
+    def capture_log_event(level, message, parameters, **attributes)
+      log_event_json = {
+        timestamp: Time.now.utc.iso8601,
+        level: level.to_s,
+        message: message,
+        parameters: parameters,
+        attributes: attributes
+      }
+
+      File.open(log_file, "a") { |file| file << JSON.dump(log_event_json) << "\n" }
+      log_event_json
+    end
+
+    def logged_events
+      File.readlines(log_file).map do |line|
+        JSON.parse(line)
+      end
+    end
+
+    def clear
+      File.write(log_file, "")
+      if backend.respond_to?(:config)
+        backend.config.sdk_logger.debug("DebugStructuredLogger: Cleared events from #{log_file}")
+      end
+    end
+
+    private
+
+    def initialize_backend(configuration)
+      if configuration.enable_logs
+        StructuredLogger.new(configuration)
+      else
+        # Create a no-op logger if logging is disabled
+        NoOpLogger.new
+      end
+    end
+
+    def initialize_log_file(log_file_path)
+      log_file = Pathname(log_file_path)
+
+      FileUtils.mkdir_p(log_file.dirname) unless log_file.dirname.exist?
+
+      log_file
+    end
+
+    # No-op logger for when structured logging is disabled
+    class NoOpLogger
+      %i[trace debug info warn error fatal log].each do |method|
+        define_method(method) { |*args, **kwargs| nil }
+      end
+    end
+  end
+end

data/lib/sentry/dsn.rb

@@ -1,11 +1,15 @@
 # frozen_string_literal: true
 
 require "uri"
+require "ipaddr"
+require "resolv"
 
 module Sentry
   class DSN
     PORT_MAP = { "http" => 80, "https" => 443 }.freeze
     REQUIRED_ATTRIBUTES = %w[host path public_key project_id].freeze
+    LOCALHOST_NAMES = %w[localhost 127.0.0.1 ::1 [::1]].freeze
+    LOCALHOST_PATTERN = /\.local(host|domain)?$/i
 
     attr_reader :scheme, :secret_key, :port, *REQUIRED_ATTRIBUTES
 
@@ -49,5 +53,33 @@ module Sentry
     def envelope_endpoint
       "#{path}/api/#{project_id}/envelope/"
     end
+
+    def local?
+      @local ||= (localhost? || private_ip? || resolved_ips_private?)
+    end
+
+    def localhost?
+      LOCALHOST_NAMES.include?(host.downcase) || LOCALHOST_PATTERN.match?(host)
+    end
+
+    def private_ip?
+      @private_ip ||= begin
+        begin
+          IPAddr.new(host).private?
+        rescue IPAddr::InvalidAddressError
+          false
+        end
+      end
+    end
+
+    def resolved_ips_private?
+      @resolved_ips_private ||= begin
+        begin
+          Resolv.getaddresses(host).any? { |ip| IPAddr.new(ip).private? }
+        rescue Resolv::ResolvError, IPAddr::InvalidAddressError
+          false
+        end
+      end
+    end
   end
 end

data/lib/sentry/graphql.rb

@@ -4,6 +4,6 @@ Sentry.register_patch(:graphql) do |config|
   if defined?(::GraphQL::Schema) && defined?(::GraphQL::Tracing::SentryTrace) && ::GraphQL::Schema.respond_to?(:trace_with)
     ::GraphQL::Schema.trace_with(::GraphQL::Tracing::SentryTrace, set_transaction_name: true)
   else
-    config.logger.warn(Sentry::LOGGER_PROGNAME) { "You tried to enable the GraphQL integration but no GraphQL gem was detected. Make sure you have the `graphql` gem (>= 2.2.6) in your Gemfile." }
+    config.sdk_logger.warn(Sentry::LOGGER_PROGNAME) { "You tried to enable the GraphQL integration but no GraphQL gem was detected. Make sure you have the `graphql` gem (>= 2.2.6) in your Gemfile." }
   end
 end

data/lib/sentry/hub.rb

@@ -120,7 +120,8 @@ module Sentry
 
       sampling_context = {
         transaction_context: transaction.to_hash,
-        parent_sampled: transaction.parent_sampled
+        parent_sampled: transaction.parent_sampled,
+        parent_sample_rate: transaction.parent_sample_rate
       }
 
       sampling_context.merge!(custom_sampling_context)
@@ -357,6 +358,7 @@ module Sentry
         parent_span_id: propagation_context.parent_span_id,
         parent_sampled: propagation_context.parent_sampled,
         baggage: propagation_context.baggage,
+        sample_rand: propagation_context.sample_rand,
         **options
       )
     end

data/lib/sentry/log_event.rb

@@ -29,9 +29,12 @@ module Sentry
       "sentry.address" => :server_name,
       "sentry.sdk.name" => :sdk_name,
       "sentry.sdk.version" => :sdk_version,
-      "sentry.message.template" => :template
+      "sentry.message.template" => :template,
+      "sentry.origin" => :origin
     }
 
+    PARAMETER_PREFIX = "sentry.message.parameter"
+
     USER_ATTRIBUTES = {
       "user.id" => :user_id,
       "user.name" => :user_username,
@@ -40,9 +43,9 @@ module Sentry
 
     LEVELS = %i[trace debug info warn error fatal].freeze
 
-    attr_accessor :level, :body, :template, :attributes, :user
+    attr_accessor :level, :body, :template, :attributes, :user, :origin
 
-    attr_reader :configuration, *SERIALIZEABLE_ATTRIBUTES
+    attr_reader :configuration, *(SERIALIZEABLE_ATTRIBUTES - %i[level body attributes])
 
     SERIALIZERS = %i[
       attributes
@@ -51,6 +54,7 @@ module Sentry
       parent_span_id
       sdk_name
       sdk_version
+      template
       timestamp
       trace_id
       user_id
@@ -79,6 +83,7 @@ module Sentry
       @template = @body if is_template?
       @attributes = options[:attributes] || DEFAULT_ATTRIBUTES
       @user = options[:user] || {}
+      @origin = options[:origin]
       @contexts = {}
     end
 
@@ -146,6 +151,10 @@ module Sentry
       user[:email]
     end
 
+    def serialize_template
+      template if has_parameters?
+    end
+
     def serialize_attributes
       hash = {}
 
@@ -185,11 +194,11 @@ module Sentry
 
         if parameters.is_a?(Hash)
           parameters.each do |key, value|
-            attributes["sentry.message.parameter.#{key}"] = value
+            attributes["#{PARAMETER_PREFIX}.#{key}"] = value
           end
         else
           parameters.each_with_index do |param, index|
-            attributes["sentry.message.parameter.#{index}"] = param
+            attributes["#{PARAMETER_PREFIX}.#{index}"] = param
           end
         end
       end
@@ -202,5 +211,9 @@ module Sentry
     def is_template?
       body.include?("%s") || TOKEN_REGEXP.match?(body)
     end
+
+    def has_parameters?
+      attributes.keys.any? { |key| key.start_with?(PARAMETER_PREFIX) }
+    end
   end
 end

data/lib/sentry/metrics/configuration.rb

@@ -4,12 +4,13 @@ module Sentry
   module Metrics
     class Configuration
       include ArgumentCheckingHelper
+      include LoggingHelper
 
       # Enable metrics usage.
       # Starts a new {Sentry::Metrics::Aggregator} instance to aggregate metrics
       # and a thread to aggregate flush every 5 seconds.
       # @return [Boolean]
-      attr_accessor :enabled
+      attr_reader :enabled
 
       # Enable code location reporting.
       # Will be sent once per day.
@@ -32,11 +33,20 @@ module Sentry
       # @return [Proc, nil]
       attr_reader :before_emit
 
-      def initialize
+      def initialize(sdk_logger)
+        @sdk_logger = sdk_logger
         @enabled = false
         @enable_code_locations = true
       end
 
+      def enabled=(value)
+        log_warn <<~MSG
+          `config.metrics` is now deprecated and will be removed in the next major.
+        MSG
+
+        @enabled = value
+      end
+
       def before_emit=(value)
         check_callable!("metrics.before_emit", value)
 

data/lib/sentry/metrics.rb

@@ -19,22 +19,28 @@ module Sentry
 
     class << self
       def increment(key, value = 1.0, unit: "none", tags: {}, timestamp: nil)
+        log_deprecation
         Sentry.metrics_aggregator&.add(:c, key, value, unit: unit, tags: tags, timestamp: timestamp)
       end
 
       def distribution(key, value, unit: "none", tags: {}, timestamp: nil)
+        log_deprecation
         Sentry.metrics_aggregator&.add(:d, key, value, unit: unit, tags: tags, timestamp: timestamp)
       end
 
       def set(key, value, unit: "none", tags: {}, timestamp: nil)
+        log_deprecation
         Sentry.metrics_aggregator&.add(:s, key, value, unit: unit, tags: tags, timestamp: timestamp)
       end
 
       def gauge(key, value, unit: "none", tags: {}, timestamp: nil)
+        log_deprecation
         Sentry.metrics_aggregator&.add(:g, key, value, unit: unit, tags: tags, timestamp: timestamp)
       end
 
       def timing(key, unit: "second", tags: {}, timestamp: nil, &block)
+        log_deprecation
+
         return unless block_given?
         return yield unless DURATION_UNITS.include?(unit)
 
@@ -51,6 +57,12 @@ module Sentry
         Sentry.metrics_aggregator&.add(:d, key, value, unit: unit, tags: tags, timestamp: timestamp)
         result
       end
+
+      def log_deprecation
+        Sentry.sdk_logger.warn(LOGGER_PROGNAME) do
+          "`Sentry::Metrics` is now deprecated and will be removed in the next major."
+        end
+      end
     end
   end
 end

data/lib/sentry/propagation_context.rb

@@ -3,15 +3,14 @@
 require "securerandom"
 require "sentry/baggage"
 require "sentry/utils/uuid"
+require "sentry/utils/sample_rand"
 
 module Sentry
   class PropagationContext
     SENTRY_TRACE_REGEXP = Regexp.new(
-      "^[ \t]*" +  # whitespace
-      "([0-9a-f]{32})?" +  # trace_id
+      "\\A([0-9a-f]{32})?" + # trace_id
       "-?([0-9a-f]{16})?" +  # span_id
-      "-?([01])?" +  # sampled
-      "[ \t]*$"  # whitespace
+      "-?([01])?\\z"         # sampled
     )
 
     # An uuid that can be used to identify a trace.
@@ -33,6 +32,53 @@ module Sentry
     # Please use the #get_baggage method for interfacing outside this class.
     # @return [Baggage, nil]
     attr_reader :baggage
+    # The propagated random value used for sampling decisions.
+    # @return [Float, nil]
+    attr_reader :sample_rand
+
+    # 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)
+      value = sentry_trace.to_s.strip
+      return if value.empty?
+
+      match = SENTRY_TRACE_REGEXP.match(value)
+      return 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
+
+    def self.extract_sample_rand_from_baggage(baggage, trace_id = nil)
+      return unless baggage&.items
+
+      sample_rand_str = baggage.items["sample_rand"]
+      return unless sample_rand_str
+
+      generator = Utils::SampleRand.new(trace_id: trace_id)
+      generator.generate_from_value(sample_rand_str)
+    end
+
+    def self.generate_sample_rand(baggage, trace_id, parent_sampled)
+      generator = Utils::SampleRand.new(trace_id: trace_id)
+
+      if baggage&.items && !parent_sampled.nil?
+        sample_rate_str = baggage.items["sample_rate"]
+        sample_rate = sample_rate_str&.to_f
+
+        if sample_rate && !parent_sampled.nil?
+          generator.generate_from_sampling_decision(parent_sampled, sample_rate)
+        else
+          generator.generate_from_trace_id
+        end
+      else
+        generator.generate_from_trace_id
+      end
+    end
 
     def initialize(scope, env = nil)
       @scope = scope
@@ -40,6 +86,7 @@ module Sentry
       @parent_sampled = nil
       @baggage = nil
       @incoming_trace = false
+      @sample_rand = nil
 
       if env
         sentry_trace_header = env["HTTP_SENTRY_TRACE"] || env[SENTRY_TRACE_HEADER_NAME]
@@ -61,6 +108,8 @@ module Sentry
                 Baggage.new({})
               end
 
+            @sample_rand = self.class.extract_sample_rand_from_baggage(@baggage, @trace_id)
+
             @baggage.freeze!
             @incoming_trace = true
           end
@@ -69,20 +118,7 @@ module Sentry
 
       @trace_id ||= Utils.uuid
       @span_id = Utils.uuid.slice(0, 16)
-    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]
+      @sample_rand ||= self.class.generate_sample_rand(@baggage, @trace_id, @parent_sampled)
     end
 
     # Returns the trace context that can be used to embed in an Event.
@@ -123,6 +159,7 @@ module Sentry
 
       items = {
         "trace_id" => trace_id,
+        "sample_rand" => Utils::SampleRand.format(@sample_rand),
         "environment" => configuration.environment,
         "release" => configuration.release,
         "public_key" => configuration.dsn&.public_key

data/lib/sentry/std_lib_logger.rb

@@ -12,11 +12,16 @@ module Sentry
       4 => :fatal
     }.freeze
 
+    ORIGIN = "auto.logger.ruby.std_logger"
+
     def add(severity, message = nil, progname = nil, &block)
       result = super
 
       return unless Sentry.initialized? && Sentry.get_current_hub
 
+      # Only process logs that meet or exceed the logger's level
+      return result if severity < level
+
       # exclude sentry SDK logs -- to prevent recursive log action,
       # do not process internal logs again
       if message.nil? && progname != Sentry::Logger::PROGNAME
@@ -32,7 +37,7 @@ module Sentry
         message = message.to_s.strip
 
         if !message.nil? && message != Sentry::Logger::PROGNAME && method = SEVERITY_MAP[severity]
-          Sentry.logger.send(method, message)
+          Sentry.logger.send(method, message, origin: ORIGIN)
         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

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
@@ -57,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)
@@ -82,12 +88,18 @@ module Sentry
       @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.
@@ -123,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
@@ -139,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
@@ -153,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
@@ -225,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
@@ -331,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,

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

@@ -223,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/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/version.rb

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

data/lib/sentry-ruby.rb

@@ -10,8 +10,10 @@ require "sentry/core_ext/object/deep_dup"
 require "sentry/utils/argument_checking_helper"
 require "sentry/utils/encoding_helper"
 require "sentry/utils/logging_helper"
+require "sentry/utils/sample_rand"
 require "sentry/configuration"
 require "sentry/structured_logger"
+require "sentry/debug_structured_logger"
 require "sentry/event"
 require "sentry/error_event"
 require "sentry/transaction_event"
@@ -237,8 +239,7 @@ module Sentry
     # @yieldparam config [Configuration]
     # @return [void]
     def init(&block)
-      config = Configuration.new
-      yield(config) if block_given?
+      config = Configuration.new(&block)
 
       config.detect_release
       apply_patches(config)
@@ -498,6 +499,7 @@ module Sentry
     # @param [Hash] options Extra log event options
     # @option options [Symbol] level The log level (:trace, :debug, :info, :warn, :error, :fatal)
     # @option options [Integer] severity The severity number according to the Sentry Logs Protocol
+    # @option options [String] origin The origin of the log event (e.g., "auto.db.rails", "manual")
     # @option options [Hash] Additional attributes to include with the log
     #
     # @example Direct usage (prefer using Sentry.logger instead)
@@ -638,13 +640,15 @@ module Sentry
       @logger ||=
         if configuration.enable_logs
           # Initialize the public-facing Structured Logger if logs are enabled
-          # This creates a StructuredLogger instance that implements Sentry's SDK telemetry logs protocol
+          # Use configured structured logger class or default to StructuredLogger
           # @see https://develop.sentry.dev/sdk/telemetry/logs/
-          StructuredLogger.new(configuration)
+          configuration.structured_logging.logger_class.new(configuration)
         else
           warn <<~STR
             [sentry] `Sentry.logger` will no longer be used as internal SDK logger when `enable_logs` feature is turned on.
                     Use Sentry.configuration.sdk_logger for SDK-specific logging needs."
+
+                    Caller: #{caller.first}
           STR
 
           configuration.sdk_logger

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sentry-ruby
 version: !ruby/object:Gem::Version
-  version: 5.26.0
+  version: 5.28.0
 platform: ruby
 authors:
 - Sentry Team
@@ -80,6 +80,7 @@ files:
 - lib/sentry/cron/monitor_check_ins.rb
 - lib/sentry/cron/monitor_config.rb
 - lib/sentry/cron/monitor_schedule.rb
+- lib/sentry/debug_structured_logger.rb
 - lib/sentry/dsn.rb
 - lib/sentry/envelope.rb
 - lib/sentry/envelope/item.rb
@@ -137,6 +138,7 @@ files:
 - lib/sentry/transaction_event.rb
 - lib/sentry/transport.rb
 - lib/sentry/transport/configuration.rb
+- lib/sentry/transport/debug_transport.rb
 - lib/sentry/transport/dummy_transport.rb
 - lib/sentry/transport/http_transport.rb
 - lib/sentry/transport/spotlight_transport.rb
@@ -149,21 +151,22 @@ files:
 - lib/sentry/utils/logging_helper.rb
 - lib/sentry/utils/real_ip.rb
 - lib/sentry/utils/request_id.rb
+- lib/sentry/utils/sample_rand.rb
 - lib/sentry/utils/uuid.rb
 - lib/sentry/vernier/output.rb
 - lib/sentry/vernier/profiler.rb
 - lib/sentry/version.rb
 - sentry-ruby-core.gemspec
 - sentry-ruby.gemspec
-homepage: https://github.com/getsentry/sentry-ruby/tree/5.26.0/sentry-ruby
+homepage: https://github.com/getsentry/sentry-ruby/tree/5.28.0/sentry-ruby
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/getsentry/sentry-ruby/tree/5.26.0/sentry-ruby
-  source_code_uri: https://github.com/getsentry/sentry-ruby/tree/5.26.0/sentry-ruby
-  changelog_uri: https://github.com/getsentry/sentry-ruby/blob/5.26.0/CHANGELOG.md
+  homepage_uri: https://github.com/getsentry/sentry-ruby/tree/5.28.0/sentry-ruby
+  source_code_uri: https://github.com/getsentry/sentry-ruby/tree/5.28.0/sentry-ruby
+  changelog_uri: https://github.com/getsentry/sentry-ruby/blob/5.28.0/CHANGELOG.md
   bug_tracker_uri: https://github.com/getsentry/sentry-ruby/issues
-  documentation_uri: http://www.rubydoc.info/gems/sentry-ruby/5.26.0
+  documentation_uri: http://www.rubydoc.info/gems/sentry-ruby/5.28.0
 rdoc_options: []
 require_paths:
 - lib
@@ -178,7 +181,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 3.6.9
 specification_version: 4
 summary: A gem that provides a client interface for the Sentry error logger
 test_files: []