sentry-ruby 5.23.0 → 5.24.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '09ca0c97390e688d58572ffe3ae022523a1003a48ccea319857b302b3e1ebb95'
-  data.tar.gz: 28f154fb38f21c50090dc8ae3c2bc7b335f288a298e97d934a24db1b8e7ac372
+  metadata.gz: 724630875bf8195cd594f3e761794886520b8eb95c13bf9a82642cdaf6f3ea94
+  data.tar.gz: c086418c80e60b60d1e099701fdb6b9ae1a9136bd464213dd9ff9cc17c582b75
 SHA512:
-  metadata.gz: 5f170fe27327a1753f4a6f2d62b5a694f30c91f1f86c4e2caa837d70467298ea2af261475a2da1045e3513257f3a9be4bb66a0c2e0dba271e43a1478ecd42c0b
-  data.tar.gz: 32a7f13e8eee4f7c8958dfd1a083aecf7ee306fec695703c5dbeff810e4ae5ebd84a1435e7edaef8a61d94eaf64910442422d2142007d77c5be31080ad32f244
+  metadata.gz: f8db6e3259785a16378f1a2f43f4dbb6e82be7f7eed84ba8f6a7ab8f1dc0f8ae4989a1d9fad5022361d756e0d8fd80d3cf16b6444933f10380e112e54afeaec1
+  data.tar.gz: 86ad04ab139eb703950d206a1a2a029f42da4fdf43896a342fa961ec8f7cd607de27270b49ec4ba7a635e2d34018387990e1a56d26287af39bf2708aee004a23

data/lib/sentry/background_worker.rb

@@ -9,8 +9,7 @@ module Sentry
     include LoggingHelper
 
     attr_reader :max_queue, :number_of_threads
-    # @deprecated Use Sentry.logger to retrieve the current logger instead.
-    attr_reader :logger
+
     attr_accessor :shutdown_timeout
 
     DEFAULT_MAX_QUEUE = 30
@@ -19,7 +18,7 @@ module Sentry
       @shutdown_timeout = 1
       @number_of_threads = configuration.background_worker_threads
       @max_queue = configuration.background_worker_max_queue
-      @logger = configuration.logger
+      @sdk_logger = configuration.sdk_logger
       @debug = configuration.debug
       @shutdown_callback = nil
 

data/lib/sentry/backpressure_monitor.rb

@@ -6,7 +6,7 @@ module Sentry
     MAX_DOWNSAMPLE_FACTOR = 10
 
     def initialize(configuration, client, interval: DEFAULT_INTERVAL)
-      super(configuration.logger, interval)
+      super(configuration.sdk_logger, interval)
       @client = client
 
       @healthy = true

data/lib/sentry/breadcrumb.rb

@@ -2,6 +2,7 @@
 
 module Sentry
   class Breadcrumb
+    MAX_NESTING = 10
     DATA_SERIALIZATION_ERROR_MESSAGE = "[data were removed due to serialization issues]"
 
     # @return [String, nil]
@@ -47,7 +48,7 @@ module Sentry
     # @param message [String]
     # @return [void]
     def message=(message)
-      @message = message ? message.byteslice(0..Event::MAX_MESSAGE_SIZE_IN_BYTES) : ""
+      @message = message && Utils::EncodingHelper.valid_utf_8?(message) ? message.byteslice(0..Event::MAX_MESSAGE_SIZE_IN_BYTES) : ""
     end
 
     # @param level [String]
@@ -60,16 +61,16 @@ module Sentry
 
     def serialized_data
       begin
-        ::JSON.parse(::JSON.generate(@data))
+        ::JSON.parse(::JSON.generate(@data, max_nesting: MAX_NESTING))
       rescue Exception => e
-        Sentry.logger.debug(LOGGER_PROGNAME) do
+        Sentry.sdk_logger.debug(LOGGER_PROGNAME) do
           <<~MSG
 can't serialize breadcrumb data because of error: #{e}
 data: #{@data}
           MSG
         end
 
-        DATA_SERIALIZATION_ERROR_MESSAGE
+        { error: DATA_SERIALIZATION_ERROR_MESSAGE }
       end
     end
   end

data/lib/sentry/check_in_event.rb

@@ -2,6 +2,7 @@
 
 require "securerandom"
 require "sentry/cron/monitor_config"
+require "sentry/utils/uuid"
 
 module Sentry
   class CheckInEvent < Event
@@ -43,7 +44,7 @@ module Sentry
       self.status = status
       self.duration = duration
       self.monitor_config = monitor_config
-      self.check_in_id = check_in_id || SecureRandom.uuid.delete("-")
+      self.check_in_id = check_in_id || Utils.uuid
     end
 
     # @return [Hash]

data/lib/sentry/client.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require "sentry/transport"
+require "sentry/log_event"
+require "sentry/log_event_buffer"
 
 module Sentry
   class Client
@@ -14,16 +16,16 @@ module Sentry
     # @return [SpotlightTransport, nil]
     attr_reader :spotlight_transport
 
+    # @!visibility private
+    attr_reader :log_event_buffer
+
     # @!macro configuration
     attr_reader :configuration
 
-    # @deprecated Use Sentry.logger to retrieve the current logger instead.
-    attr_reader :logger
-
     # @param configuration [Configuration]
     def initialize(configuration)
       @configuration = configuration
-      @logger = configuration.logger
+      @sdk_logger = configuration.sdk_logger
 
       if transport_class = configuration.transport.transport_class
         @transport = transport_class.new(configuration)
@@ -38,6 +40,8 @@ module Sentry
       end
 
       @spotlight_transport = SpotlightTransport.new(configuration) if configuration.spotlight
+
+      @log_event_buffer = LogEventBuffer.new(configuration, self).start
     end
 
     # Applies the given scope's data to the event and sends it to Sentry.
@@ -88,6 +92,15 @@ module Sentry
       nil
     end
 
+    # Buffer a log event to be sent later with other logs in a single envelope
+    # @param event [LogEvent] the log event to be buffered
+    # @return [LogEvent]
+    def buffer_log_event(event, scope)
+      return unless event.is_a?(LogEvent)
+      @log_event_buffer.add_event(scope.apply_to_event(event))
+      event
+    end
+
     # Capture an envelope directly.
     # @param envelope [Envelope] the envelope to be captured.
     # @return [void]
@@ -100,6 +113,7 @@ module Sentry
     def flush
       transport.flush if configuration.sending_to_dsn_allowed?
       spotlight_transport.flush if spotlight_transport
+      @log_event_buffer.flush
     end
 
     # Initializes an Event object with the given exception. Returns `nil` if the exception's class is excluded from reporting.
@@ -167,6 +181,27 @@ module Sentry
       )
     end
 
+    # Initializes a LogEvent object with the given message and options
+    #
+    # @param message [String] the log message
+    # @param level [Symbol] the log level (:trace, :debug, :info, :warn, :error, :fatal)
+    # @param options [Hash] additional options
+    # @option options [Array] :parameters Array of values to replace template tokens in the message
+    #
+    # @return [LogEvent] the created log event
+    def event_from_log(message, level:, **options)
+      return unless configuration.sending_allowed?
+
+      attributes = options.reject { |k, _| k == :level || k == :severity }
+
+      LogEvent.new(
+        level: level,
+        body: message,
+        timestamp: Time.now.to_f,
+        attributes: attributes
+      )
+    end
+
     # Initializes an Event object with the given Transaction object.
     # @param transaction [Transaction] the transaction to be recorded.
     # @return [TransactionEvent]

data/lib/sentry/configuration.rb

@@ -12,6 +12,8 @@ require "sentry/cron/configuration"
 require "sentry/metrics/configuration"
 require "sentry/linecache"
 require "sentry/interfaces/stacktrace_builder"
+require "sentry/logger"
+require "sentry/log_event_buffer"
 
 module Sentry
   class Configuration
@@ -183,7 +185,19 @@ module Sentry
     # Logger used by Sentry. In Rails, this is the Rails logger, otherwise
     # Sentry provides its own Sentry::Logger.
     # @return [Logger]
-    attr_accessor :logger
+    attr_accessor :sdk_logger
+
+    # @deprecated Use {#sdk_logger=} instead.
+    def logger=(logger)
+      warn "[sentry] `config.logger=` is deprecated. Please use `config.sdk_logger=` instead."
+      self.sdk_logger = logger
+    end
+
+    # @deprecated Use {#sdk_logger} instead.
+    def logger
+      warn "[sentry] `config.logger` is deprecated. Please use `config.sdk_logger` instead."
+      self.sdk_logger
+    end
 
     # Project directory root for in_app detection. Could be Rails root, etc.
     # Set automatically for Rails.
@@ -262,6 +276,10 @@ module Sentry
     # @return [Proc]
     attr_accessor :traces_sampler
 
+    # Enable Structured Logging
+    # @return [Boolean]
+    attr_accessor :enable_logs
+
     # 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.
@@ -307,6 +325,10 @@ module Sentry
     # @return [Array<Symbol>]
     attr_accessor :enabled_patches
 
+    # Maximum number of log events to buffer before sending
+    # @return [Integer]
+    attr_accessor :max_log_events
+
     # these are not config options
     # @!visibility private
     attr_reader :errors, :gem_specs
@@ -419,7 +441,7 @@ module Sentry
       self.excluded_exceptions = IGNORE_DEFAULT + PUMA_IGNORE_DEFAULT
       self.inspect_exception_causes_for_exclusion = true
       self.linecache = ::Sentry::LineCache.new
-      self.logger = ::Sentry::Logger.new(STDOUT)
+      self.sdk_logger = ::Sentry::Logger.new(STDOUT)
       self.project_root = Dir.pwd
       self.propagate_traces = true
 
@@ -446,6 +468,7 @@ module Sentry
       self.rack_env_whitelist = RACK_ENV_WHITELIST_DEFAULT
       self.traces_sampler = nil
       self.enable_tracing = nil
+      self.enable_logs = false
 
       self.profiler_class = Sentry::Profiler
 
@@ -455,6 +478,8 @@ module Sentry
       @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
     end
 
     def validate

data/lib/sentry/envelope/item.rb

@@ -15,7 +15,7 @@ module Sentry
     # rate limits and client reports use the data_category rather than envelope item type
     def self.data_category(type)
       case type
-      when "session", "attachment", "transaction", "profile", "span" then type
+      when "session", "attachment", "transaction", "profile", "span", "log" then type
       when "sessions" then "session"
       when "check_in" then "monitor"
       when "statsd", "metric_meta" then "metric_bucket"

data/lib/sentry/event.rb

@@ -7,6 +7,7 @@ require "sentry/backtrace"
 require "sentry/utils/real_ip"
 require "sentry/utils/request_id"
 require "sentry/utils/custom_inspection"
+require "sentry/utils/uuid"
 
 module Sentry
   # This is an abstract class that defines the shared attributes of an event.
@@ -50,7 +51,7 @@ module Sentry
     # @param message [String, nil]
     def initialize(configuration:, integration_meta: nil, message: nil)
       # Set some simple default values
-      @event_id      = SecureRandom.uuid.delete("-")
+      @event_id      = Utils.uuid
       @timestamp     = Sentry.utc_now.iso8601
       @platform      = :ruby
       @type          = self.class::TYPE

data/lib/sentry/hub.rb

@@ -216,6 +216,16 @@ module Sentry
       event.check_in_id
     end
 
+    def capture_log_event(message, **options)
+      return unless current_client
+
+      event = current_client.event_from_log(message, **options)
+
+      return unless event
+
+      current_client.buffer_log_event(event, current_scope)
+    end
+
     def capture_event(event, **options, &block)
       check_argument_type!(event, Sentry::Event)
 

data/lib/sentry/interfaces/request.rb

@@ -99,7 +99,7 @@ module Sentry
           # Rails adds objects to the Rack env that can sometimes raise exceptions
           # when `to_s` is called.
           # See: https://github.com/rails/rails/blob/master/actionpack/lib/action_dispatch/middleware/remote_ip.rb#L134
-          Sentry.logger.warn(LOGGER_PROGNAME) { "Error raised while formatting headers: #{e.message}" }
+          Sentry.sdk_logger.warn(LOGGER_PROGNAME) { "Error raised while formatting headers: #{e.message}" }
           next
         end
       end

data/lib/sentry/log_event.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module Sentry
+  # Event type that represents a log entry with its attributes
+  #
+  # @see https://develop.sentry.dev/sdk/telemetry/logs/#log-envelope-item-payload
+  class LogEvent < Event
+    TYPE = "log"
+
+    DEFAULT_PARAMETERS = [].freeze
+    DEFAULT_ATTRIBUTES = {}.freeze
+    DEFAULT_CONTEXT = {}.freeze
+
+    SERIALIZEABLE_ATTRIBUTES = %i[
+      level
+      body
+      timestamp
+      trace_id
+      attributes
+    ]
+
+    SENTRY_ATTRIBUTES = {
+      "sentry.trace.parent_span_id" => :parent_span_id,
+      "sentry.environment" => :environment,
+      "sentry.release" => :release,
+      "sentry.address" => :server_name,
+      "sentry.sdk.name" => :sdk_name,
+      "sentry.sdk.version" => :sdk_version,
+      "sentry.message.template" => :template
+    }
+
+    LEVELS = %i[trace debug info warn error fatal].freeze
+
+    attr_accessor :level, :body, :template, :attributes
+
+    def initialize(configuration: Sentry.configuration, **options)
+      super(configuration: configuration)
+
+      @type = TYPE
+      @level = options.fetch(:level)
+      @body = options[:body]
+      @template = @body if is_template?
+      @attributes = options[:attributes] || DEFAULT_ATTRIBUTES
+      @contexts = DEFAULT_CONTEXT
+    end
+
+    def to_hash
+      SERIALIZEABLE_ATTRIBUTES.each_with_object({}) do |name, memo|
+        memo[name] = serialize(name)
+      end
+    end
+
+    private
+
+    def serialize(name)
+      serializer = :"serialize_#{name}"
+
+      if respond_to?(serializer, true)
+        __send__(serializer)
+      else
+        public_send(name)
+      end
+    end
+
+    def serialize_level
+      level.to_s
+    end
+
+    def serialize_sdk_name
+      Sentry.sdk_meta["name"]
+    end
+
+    def serialize_sdk_version
+      Sentry.sdk_meta["version"]
+    end
+
+    def serialize_timestamp
+      Time.parse(timestamp).to_f
+    end
+
+    def serialize_trace_id
+      contexts.dig(:trace, :trace_id)
+    end
+
+    def serialize_parent_span_id
+      contexts.dig(:trace, :parent_span_id)
+    end
+
+    def serialize_body
+      if parameters.empty?
+        body
+      elsif parameters.is_a?(Hash)
+        body % parameters
+      else
+        sprintf(body, *parameters)
+      end
+    end
+
+    def serialize_attributes
+      hash = attributes.each_with_object({}) do |(key, value), memo|
+        memo[key] = attribute_hash(value)
+      end
+
+      SENTRY_ATTRIBUTES.each do |key, name|
+        if (value = serialize(name))
+          hash[key] = attribute_hash(value)
+        end
+      end
+
+      hash
+    end
+
+    def attribute_hash(value)
+      { value: value, type: value_type(value) }
+    end
+
+    def value_type(value)
+      case value
+      when Integer
+        "integer"
+      when TrueClass, FalseClass
+        "boolean"
+      when Float
+        "double"
+      else
+        "string"
+      end
+    end
+
+    def parameters
+      @parameters ||= begin
+        return DEFAULT_PARAMETERS unless template
+
+        parameters = template_tokens.empty? ?
+          attributes.fetch(:parameters, DEFAULT_PARAMETERS) : attributes.slice(*template_tokens)
+
+        if parameters.is_a?(Hash)
+          parameters.each do |key, value|
+            attributes["sentry.message.parameter.#{key}"] = value
+          end
+        else
+          parameters.each_with_index do |param, index|
+            attributes["sentry.message.parameter.#{index}"] = param
+          end
+        end
+      end
+    end
+
+    TOKEN_REGEXP = /%\{(\w+)\}/
+
+    def template_tokens
+      @template_tokens ||= body.scan(TOKEN_REGEXP).flatten.map(&:to_sym)
+    end
+
+    def is_template?
+      body.include?("%s") || TOKEN_REGEXP.match?(body)
+    end
+  end
+end

data/lib/sentry/log_event_buffer.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "sentry/threaded_periodic_worker"
+
+module Sentry
+  # LogEventBuffer buffers log events and sends them to Sentry in a single envelope.
+  #
+  # This is used internally by the `Sentry::Client`.
+  #
+  # @!visibility private
+  class LogEventBuffer < ThreadedPeriodicWorker
+    FLUSH_INTERVAL = 5 # seconds
+    DEFAULT_MAX_EVENTS = 100
+
+    # @!visibility private
+    attr_reader :pending_events
+
+    def initialize(configuration, client)
+      super(configuration.sdk_logger, FLUSH_INTERVAL)
+
+      @client = client
+      @pending_events = []
+      @max_events = configuration.max_log_events || DEFAULT_MAX_EVENTS
+      @dsn = configuration.dsn
+      @sdk = Sentry.sdk_meta
+      @mutex = Mutex.new
+
+      log_debug("[Logging] Initialized buffer with max_events=#{@max_events}, flush_interval=#{FLUSH_INTERVAL}s")
+    end
+
+    def start
+      ensure_thread
+      self
+    end
+
+    def flush
+      @mutex.synchronize do
+        return if empty?
+
+        log_debug("[LogEventBuffer] flushing #{size} log events")
+
+        send_events
+      end
+
+      log_debug("[LogEventBuffer] flushed #{size} log events")
+
+      self
+    end
+    alias_method :run, :flush
+
+    def add_event(event)
+      raise ArgumentError, "expected a LogEvent, got #{event.class}" unless event.is_a?(LogEvent)
+
+      @mutex.synchronize do
+        @pending_events << event
+        send_events if size >= @max_events
+      end
+
+      self
+    end
+
+    def empty?
+      @pending_events.empty?
+    end
+
+    def size
+      @pending_events.size
+    end
+
+    private
+
+    def send_events
+      @client.send_envelope(to_envelope)
+      @pending_events.clear
+    end
+
+    def to_envelope
+      envelope = Envelope.new(
+        event_id: SecureRandom.uuid.delete("-"),
+        sent_at: Sentry.utc_now.iso8601,
+        dsn: @dsn,
+        sdk: @sdk
+      )
+
+      envelope.add_item(
+        {
+          type: "log",
+          item_count: size,
+          content_type: "application/vnd.sentry.items.log+json"
+        },
+        { items: @pending_events.map(&:to_hash) }
+      )
+
+      envelope
+    end
+  end
+end

data/lib/sentry/metrics/aggregator.rb

@@ -34,7 +34,7 @@ module Sentry
       attr_reader :client, :thread, :buckets, :flush_shift, :code_locations
 
       def initialize(configuration, client)
-        super(configuration.logger, FLUSH_INTERVAL)
+        super(configuration.sdk_logger, FLUSH_INTERVAL)
         @client = client
         @before_emit = configuration.metrics.before_emit
         @enable_code_locations = configuration.metrics.enable_code_locations

data/lib/sentry/profiler.rb

@@ -2,6 +2,7 @@
 
 require "securerandom"
 require_relative "profiler/helpers"
+require "sentry/utils/uuid"
 
 module Sentry
   class Profiler
@@ -17,7 +18,7 @@ module Sentry
     attr_reader :sampled, :started, :event_id
 
     def initialize(configuration)
-      @event_id = SecureRandom.uuid.delete("-")
+      @event_id = Utils.uuid
       @started = false
       @sampled = nil
 
@@ -192,7 +193,7 @@ module Sentry
     private
 
     def log(message)
-      Sentry.logger.debug(LOGGER_PROGNAME) { "[Profiler] #{message}" }
+      Sentry.sdk_logger.debug(LOGGER_PROGNAME) { "[Profiler] #{message}" }
     end
 
     def record_lost_event(reason)

data/lib/sentry/propagation_context.rb

@@ -2,6 +2,7 @@
 
 require "securerandom"
 require "sentry/baggage"
+require "sentry/utils/uuid"
 
 module Sentry
   class PropagationContext
@@ -66,8 +67,8 @@ module Sentry
         end
       end
 
-      @trace_id ||= SecureRandom.uuid.delete("-")
-      @span_id = SecureRandom.uuid.delete("-").slice(0, 16)
+      @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.
@@ -124,8 +125,7 @@ module Sentry
         "trace_id" => trace_id,
         "environment" => configuration.environment,
         "release" => configuration.release,
-        "public_key" => configuration.dsn&.public_key,
-        "user_segment" => @scope.user && @scope.user["segment"]
+        "public_key" => configuration.dsn&.public_key
       }
 
       items.compact!

data/lib/sentry/scope.rb

@@ -54,7 +54,7 @@ module Sentry
         event.transaction = transaction_name if transaction_name
         event.transaction_info = { source: transaction_source } if transaction_source
         event.fingerprint = fingerprint
-        event.level = level
+        event.level = level unless event.is_a?(LogEvent)
         event.breadcrumbs = breadcrumbs
         event.rack_env = rack_env if rack_env
         event.attachments = attachments

data/lib/sentry/session_flusher.rb

@@ -5,7 +5,7 @@ module Sentry
     FLUSH_INTERVAL = 60
 
     def initialize(configuration, client)
-      super(configuration.logger, FLUSH_INTERVAL)
+      super(configuration.sdk_logger, FLUSH_INTERVAL)
       @client = client
       @pending_aggregates = {}
       @release = configuration.release

data/lib/sentry/span.rb

@@ -2,6 +2,7 @@
 
 require "securerandom"
 require "sentry/metrics/local_aggregator"
+require "sentry/utils/uuid"
 
 module Sentry
   class Span
@@ -127,8 +128,8 @@ module Sentry
       timestamp: nil,
       origin: nil
     )
-      @trace_id = trace_id || SecureRandom.uuid.delete("-")
-      @span_id = span_id || SecureRandom.uuid.delete("-").slice(0, 16)
+      @trace_id = trace_id || Utils.uuid
+      @span_id = span_id || Utils.uuid.slice(0, 16)
       @parent_span_id = parent_span_id
       @sampled = sampled
       @start_timestamp = start_timestamp || Sentry.utc_now.to_f

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

@@ -72,6 +72,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

@@ -45,9 +45,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
@@ -78,7 +75,7 @@ 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
@@ -342,9 +339,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.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(

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/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.24.0"
 end

data/lib/sentry-ruby.rb

@@ -11,7 +11,7 @@ require "sentry/utils/argument_checking_helper"
 require "sentry/utils/encoding_helper"
 require "sentry/utils/logging_helper"
 require "sentry/configuration"
-require "sentry/logger"
+require "sentry/structured_logger"
 require "sentry/event"
 require "sentry/error_event"
 require "sentry/transaction_event"
@@ -54,6 +54,7 @@ module Sentry
 
   GLOBALS = %i[
     main_hub
+    logger
     session_flusher
     backpressure_monitor
     metrics_aggregator
@@ -138,7 +139,7 @@ module Sentry
     # @param version [String] version of the integration
     def register_integration(name, version)
       if initialized?
-        logger.warn(LOGGER_PROGNAME) do
+        sdk_logger.warn(LOGGER_PROGNAME) do
           <<~MSG
             Integration '#{name}' is loaded after the SDK is initialized, which can cause unexpected behavior.  Please make sure all integrations are loaded before SDK initialization.
           MSG
@@ -238,6 +239,7 @@ module Sentry
     def init(&block)
       config = Configuration.new
       yield(config) if block_given?
+
       config.detect_release
       apply_patches(config)
       config.validate
@@ -489,6 +491,25 @@ module Sentry
       get_current_hub.capture_check_in(slug, status, **options)
     end
 
+    # Captures a log event and sends it to Sentry via the currently active hub.
+    # This is the underlying method used by the StructuredLogger class.
+    #
+    # @param message [String] the log message
+    # @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 [Hash] Additional attributes to include with the log
+    #
+    # @example Direct usage (prefer using Sentry.logger instead)
+    #   Sentry.capture_log("User logged in", level: :info, user_id: 123)
+    #
+    # @see https://develop.sentry.dev/sdk/telemetry/logs/ Sentry SDK Telemetry Logs Protocol
+    # @return [LogEvent, nil] The created log event or nil if logging is disabled
+    def capture_log(message, **options)
+      return unless initialized?
+      get_current_hub.capture_log_event(message, **options)
+    end
+
     # Takes or initializes a new Sentry::Transaction and makes a sampling decision for it.
     #
     # @return [Transaction, nil]
@@ -593,6 +614,43 @@ module Sentry
       get_current_hub.continue_trace(env, **options)
     end
 
+    # Returns the structured logger instance that implements Sentry's SDK telemetry logs protocol.
+    #
+    # This logger is only available when logs are enabled in the configuration.
+    #
+    # @example Enable logs in configuration
+    #   Sentry.init do |config|
+    #     config.dsn = "YOUR_DSN"
+    #     config.enable_logs = true
+    #   end
+    #
+    # @example Basic usage
+    #   Sentry.logger.info("User logged in successfully", user_id: 123)
+    #   Sentry.logger.error("Failed to process payment",
+    #     transaction_id: "tx_123",
+    #     error_code: "PAYMENT_FAILED"
+    #   )
+    #
+    # @see https://develop.sentry.dev/sdk/telemetry/logs/ Sentry SDK Telemetry Logs Protocol
+    #
+    # @return [StructuredLogger, nil] The structured logger instance or nil if logs are disabled
+    def logger
+      @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
+          # @see https://develop.sentry.dev/sdk/telemetry/logs/
+          StructuredLogger.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."
+          STR
+
+          configuration.sdk_logger
+        end
+    end
+
     ##### Helpers #####
 
     # @!visibility private
@@ -604,8 +662,8 @@ module Sentry
     end
 
     # @!visibility private
-    def logger
-      configuration.logger
+    def sdk_logger
+      configuration.sdk_logger
     end
 
     # @!visibility private

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: sentry-ruby
 version: !ruby/object:Gem::Version
-  version: 5.23.0
+  version: 5.24.0
 platform: ruby
 authors:
 - Sentry Team
 bindir: bin
 cert_chain: []
-date: 2025-03-11 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -48,8 +48,8 @@ email: accounts@sentry.io
 executables: []
 extensions: []
 extra_rdoc_files:
-- README.md
 - LICENSE.txt
+- README.md
 files:
 - ".gitignore"
 - ".rspec"
@@ -101,6 +101,8 @@ files:
 - lib/sentry/interfaces/stacktrace_builder.rb
 - lib/sentry/interfaces/threads.rb
 - lib/sentry/linecache.rb
+- lib/sentry/log_event.rb
+- lib/sentry/log_event_buffer.rb
 - lib/sentry/logger.rb
 - lib/sentry/metrics.rb
 - lib/sentry/metrics/aggregator.rb
@@ -127,6 +129,7 @@ files:
 - lib/sentry/session.rb
 - lib/sentry/session_flusher.rb
 - lib/sentry/span.rb
+- lib/sentry/structured_logger.rb
 - lib/sentry/test_helper.rb
 - lib/sentry/threaded_periodic_worker.rb
 - lib/sentry/transaction.rb
@@ -145,20 +148,21 @@ files:
 - lib/sentry/utils/logging_helper.rb
 - lib/sentry/utils/real_ip.rb
 - lib/sentry/utils/request_id.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.23.0/sentry-ruby
+homepage: https://github.com/getsentry/sentry-ruby/tree/5.24.0/sentry-ruby
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/getsentry/sentry-ruby/tree/5.23.0/sentry-ruby
-  source_code_uri: https://github.com/getsentry/sentry-ruby/tree/5.23.0/sentry-ruby
-  changelog_uri: https://github.com/getsentry/sentry-ruby/blob/5.23.0/CHANGELOG.md
+  homepage_uri: https://github.com/getsentry/sentry-ruby/tree/5.24.0/sentry-ruby
+  source_code_uri: https://github.com/getsentry/sentry-ruby/tree/5.24.0/sentry-ruby
+  changelog_uri: https://github.com/getsentry/sentry-ruby/blob/5.24.0/CHANGELOG.md
   bug_tracker_uri: https://github.com/getsentry/sentry-ruby/issues
-  documentation_uri: http://www.rubydoc.info/gems/sentry-ruby/5.23.0
+  documentation_uri: http://www.rubydoc.info/gems/sentry-ruby/5.24.0
 rdoc_options: []
 require_paths:
 - lib
@@ -173,7 +177,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 3.6.7
 specification_version: 4
 summary: A gem that provides a client interface for the Sentry error logger
 test_files: []