Add DebugStructuredLogger

Author: solnic

sentry-rails/spec/spec_helper.rb

@@ -54,6 +54,8 @@
     expect(Sentry::Rails::Tracing.subscribed_tracing_events).to be_empty
     Sentry::Rails::Tracing.remove_active_support_notifications_patch
 
+    Sentry::TestHelper.clear_sentry_events
+
     if defined?(Sentry::Rails::ActiveJobExtensions)
       Sentry::Rails::ActiveJobExtensions::SentryReporter.detach_event_handlers
     end

sentry-ruby/lib/sentry-ruby.rb

@@ -13,6 +13,7 @@
 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"
@@ -639,9 +640,10 @@ 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
+          # Use configured structured logger class or default to StructuredLogger
           # @see https://develop.sentry.dev/sdk/telemetry/logs/
-          StructuredLogger.new(configuration)
+          logger_class = configuration.structured_logger_class || StructuredLogger
+          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.

sentry-ruby/lib/sentry/configuration.rb

@@ -201,6 +201,18 @@ def capture_exception_frame_locals=(value)
     # @return [String, nil]
     attr_accessor :sdk_debug_transport_log_file
 
+    # File path for DebugStructuredLogger to log events to. If not set, defaults to a temporary file.
+    # This is useful for debugging and testing structured logging.
+    # @return [String, nil]
+    attr_accessor :sdk_debug_structured_logger_log_file
+
+    # The class to use as a structured logger.
+    # If this option is not set, it will return `nil`, and Sentry will use
+    # `Sentry::StructuredLogger` by default when logs are enabled.
+    #
+    # @return [Class, nil]
+    attr_reader :structured_logger_class
+
     # @deprecated Use {#sdk_logger=} instead.
     def logger=(logger)
       warn "[sentry] `config.logger=` is deprecated. Please use `config.sdk_logger=` instead."
@@ -612,6 +624,14 @@ def profiler_class=(profiler_class)
       @profiler_class = profiler_class
     end
 
+    def structured_logger_class=(klass)
+      unless klass.is_a?(Class)
+        raise Sentry::Error.new("config.structured_logger_class must be a class. got: #{klass.class}")
+      end
+
+      @structured_logger_class = klass
+    end
+
     def sending_allowed?
       spotlight || sending_to_dsn_allowed?
     end

sentry-ruby/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)
+      @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
+      return [] unless File.exist?(log_file)
+
+      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(configuration)
+      log_file = Pathname(configuration.sdk_debug_structured_logger_log_file || DEFAULT_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

sentry-ruby/lib/sentry/test_helper.rb

@@ -2,6 +2,8 @@
 
 module Sentry
   module TestHelper
+    module_function
+
     DUMMY_DSN = "http://12345:[email protected]/sentry/42"
 
     # Not really real, but it will be resolved as a non-local for testing needs
@@ -49,10 +51,7 @@ def setup_sentry_test(&block)
     def teardown_sentry_test
       return unless Sentry.initialized?
 
-      transport = Sentry.get_current_client&.transport
-      if transport.is_a?(Sentry::DebugTransport)
-        transport.clear
-      end
+      clear_sentry_events
 
       # pop testing layer created by `setup_sentry_test`
       # but keep the base layer to avoid nil-pointer errors
@@ -63,6 +62,14 @@ def teardown_sentry_test
       Sentry::Scope.global_event_processors.clear
     end
 
+    def clear_sentry_events
+      return unless Sentry.initialized?
+
+      [Sentry.get_current_client.transport, Sentry.logger].each do |obj|
+        obj.clear if obj.respond_to?(:clear)
+      end
+    end
+
     # @return [Transport]
     def sentry_transport
       Sentry.get_current_client.transport

sentry-ruby/spec/sentry/debug_structured_logger_spec.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+RSpec.describe Sentry::DebugStructuredLogger do
+  let(:configuration) do
+    config = Sentry::Configuration.new
+    config.enable_logs = true
+    config.dsn = Sentry::TestHelper::DUMMY_DSN
+    config
+  end
+
+  let(:debug_logger) { described_class.new(configuration) }
+
+  before do
+    debug_logger.clear
+  end
+
+  after do
+    debug_logger.clear
+  end
+
+  describe "#initialize" do
+    it "creates a debug logger with structured logger backend" do
+      expect(debug_logger.backend).to be_a(Sentry::StructuredLogger)
+    end
+
+    it "creates a log file" do
+      expect(debug_logger.log_file).to be_a(Pathname)
+    end
+
+    context "when logs are disabled" do
+      let(:configuration) do
+        config = Sentry::Configuration.new
+        config.enable_logs = false
+        config.dsn = Sentry::TestHelper::DUMMY_DSN
+        config
+      end
+
+      it "creates a no-op logger backend" do
+        expect(debug_logger.backend).to be_a(Sentry::DebugStructuredLogger::NoOpLogger)
+      end
+    end
+  end
+
+  describe "logging methods" do
+    %i[trace debug info warn error fatal].each do |level|
+      describe "##{level}" do
+        it "captures log events to file" do
+          debug_logger.public_send(level, "Test #{level} message", test_attr: "value")
+
+          logged_events = debug_logger.logged_events
+          expect(logged_events).not_to be_empty
+
+          log_event = logged_events.last
+          expect(log_event["level"]).to eq(level.to_s)
+          expect(log_event["message"]).to eq("Test #{level} message")
+          expect(log_event["attributes"]["test_attr"]).to eq("value")
+          expect(log_event["timestamp"]).to be_a(String)
+        end
+
+        it "handles parameters correctly" do
+          debug_logger.public_send(level, "Test message", ["param1", "param2"], extra_attr: "extra")
+
+          logged_events = debug_logger.logged_events
+          log_event = logged_events.last
+
+          expect(log_event["parameters"]).to eq(["param1", "param2"])
+          expect(log_event["attributes"]["extra_attr"]).to eq("extra")
+        end
+      end
+    end
+  end
+
+  describe "#log" do
+    it "captures log events with specified level" do
+      debug_logger.log(:info, "Test log message", parameters: [], custom_attr: "custom_value")
+
+      logged_events = debug_logger.logged_events
+      expect(logged_events).not_to be_empty
+
+      log_event = logged_events.last
+      expect(log_event["level"]).to eq("info")
+      expect(log_event["message"]).to eq("Test log message")
+      expect(log_event["attributes"]["custom_attr"]).to eq("custom_value")
+    end
+  end
+
+  describe "#logged_events" do
+    it "returns empty array when no events logged" do
+      expect(debug_logger.logged_events).to eq([])
+    end
+
+    it "returns all logged events" do
+      debug_logger.info("First message")
+      debug_logger.warn("Second message")
+      debug_logger.error("Third message")
+
+      logged_events = debug_logger.logged_events
+      expect(logged_events.length).to eq(3)
+
+      expect(logged_events[0]["message"]).to eq("First message")
+      expect(logged_events[1]["message"]).to eq("Second message")
+      expect(logged_events[2]["message"]).to eq("Third message")
+    end
+  end
+
+  describe "#clear" do
+    it "clears logged events" do
+      debug_logger.info("Test message")
+      expect(debug_logger.logged_events).not_to be_empty
+
+      debug_logger.clear
+      expect(debug_logger.logged_events).to be_empty
+    end
+  end
+
+  describe "JSON serialization" do
+    it "handles complex data types" do
+      debug_logger.info("Complex data",
+        string: "text",
+        number: 42,
+        boolean: true,
+        array: [1, 2, 3],
+        hash: { nested: "value" }
+      )
+
+      logged_events = debug_logger.logged_events
+      log_event = logged_events.last
+
+      expect(log_event["attributes"]["string"]).to eq("text")
+      expect(log_event["attributes"]["number"]).to eq(42)
+      expect(log_event["attributes"]["boolean"]).to eq(true)
+      expect(log_event["attributes"]["array"]).to eq([1, 2, 3])
+      expect(log_event["attributes"]["hash"]).to eq({ "nested" => "value" })
+    end
+  end
+end

spec/support/test_helper.rb

@@ -39,6 +39,14 @@ def logged_envelopes
       Sentry.get_current_client.transport.logged_envelopes
     end
 
+    def logged_structured_events
+      if Sentry.logger.is_a?(Sentry::DebugStructuredLogger)
+        Sentry.logger.logged_events
+      else
+        []
+      end
+    end
+
     # TODO: move this to a shared helper for all gems
     def perform_basic_setup
       Sentry.init do |config|