sentry-ruby 5.23.0 → 5.25.0

data/lib/sentry/log_event_buffer.rb

@@ -0,0 +1,75 @@
+# 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
+      @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_logs(@pending_events)
+      @pending_events.clear
+    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

@@ -46,7 +46,7 @@ module Sentry
     # @param hint [Hash] the hint data that'll be passed to event processors.
     # @return [Event]
     def apply_to_event(event, hint = nil)
-      unless event.is_a?(CheckInEvent)
+      unless event.is_a?(CheckInEvent) || event.is_a?(LogEvent)
         event.tags = tags.merge(event.tags)
         event.user = user.merge(event.user)
         event.extra = extra.merge(event.extra)
@@ -60,12 +60,22 @@ module Sentry
         event.attachments = attachments
       end
 
+      if event.is_a?(LogEvent)
+        event.user = user.merge(event.user)
+      end
+
       if span
         event.contexts[:trace] ||= span.get_trace_context
-        event.dynamic_sampling_context ||= span.get_dynamic_sampling_context
+
+        if event.respond_to?(:dynamic_sampling_context)
+          event.dynamic_sampling_context ||= span.get_dynamic_sampling_context
+        end
       else
         event.contexts[:trace] ||= propagation_context.get_trace_context
-        event.dynamic_sampling_context ||= propagation_context.get_dynamic_sampling_context
+
+        if event.respond_to?(:dynamic_sampling_context)
+          event.dynamic_sampling_context ||= propagation_context.get_dynamic_sampling_context
+        end
       end
 
       all_event_processors = self.class.global_event_processors + @event_processors

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
@@ -261,7 +262,7 @@ module Sentry
 
 
     # Sets the span's status.
-    # @param satus [String] status of the span.
+    # @param status [String] status of the span.
     def set_status(status)
       @status = status
     end

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.25.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