Add Sentry::DebugTransport for testing/debugging

Author: solnic

sentry-ruby/lib/sentry/configuration.rb

@@ -196,6 +196,11 @@ def capture_exception_frame_locals=(value)
     # @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."

sentry-ruby/lib/sentry/test_helper.rb

@@ -46,6 +46,11 @@ 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_events
+      end
+
       # 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

sentry-ruby/lib/sentry/transport.rb

@@ -223,3 +223,4 @@ def reject_rate_limited_items(envelope)
 require "sentry/transport/dummy_transport"
 require "sentry/transport/http_transport"
 require "sentry/transport/spotlight_transport"
+require "sentry/transport/debug_transport"

sentry-ruby/lib/sentry/transport/debug_transport.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+
+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 < Transport
+    attr_reader :log_file_path, :http_transport
+
+    def initialize(configuration)
+      super
+
+      @log_file_path = configuration.sdk_debug_transport_log_file || default_log_file_path
+
+      FileUtils.mkdir_p(File.dirname(@log_file_path))
+
+      log_debug("DebugTransport: Initialized with log file: #{@log_file_path}")
+
+      if configuration.dsn && !configuration.dsn.to_s.include?("localhost")
+        @http_transport = Sentry::HTTPTransport.new(configuration)
+        log_debug("DebugTransport: Initialized with HTTP transport for DSN: #{configuration.dsn}")
+      else
+        @http_transport = nil
+        log_debug("DebugTransport: Using local-only mode for DSN: #{configuration.dsn}")
+      end
+    end
+
+    def send_event(event)
+      envelope = envelope_from_event(event)
+      send_envelope(envelope)
+      event
+    end
+
+    def send_envelope(envelope)
+      envelope_data = {
+        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_path, "a") do |file|
+        file << JSON.dump(envelope_data) << "\n"
+      end
+
+      if http_transport
+        http_transport.send_envelope(envelope)
+      end
+    end
+
+    def events
+      return [] unless File.exist?(log_file_path)
+
+      File.readlines(log_file_path).map do |line|
+        JSON.load(line)
+      end
+    end
+
+    def clear
+      File.write(log_file_path, "")
+      log_debug("DebugTransport: Cleared events from #{log_file_path}")
+    end
+
+    private
+
+    def default_log_file_path
+      if defined?(Rails) && Rails.respond_to?(:root) && Rails.root
+        File.join(Rails.root, "log", "sentry_debug_events.log")
+      elsif File.directory?("log")
+        File.join("log", "sentry_debug_events.log")
+      else
+        "/tmp/sentry_debug_events.json"
+      end
+    end
+  end
+end

sentry-ruby/spec/sentry/transport/debug_transport_spec.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'contexts/with_request_mock'
+
+RSpec.describe Sentry do
+  include_context "with request mock"
+
+  let(:client) { Sentry.get_current_client }
+  let(:transport) { Sentry.get_current_client.transport }
+
+  before do
+    perform_basic_setup do |config|
+      config.transport.transport_class = Sentry::DebugTransport
+    end
+  end
+
+  describe ".send_event" do
+    let(:event) { Sentry.get_current_client.event_from_message("test message") }
+
+    it "sends the event and logs to a file" do
+      sentry_stub_request(build_fake_response("200"))
+
+      Sentry.send_event(event)
+
+      expect(transport.events.count).to be(1)
+    end
+  end
+end

sentry-ruby/spec/spec_helper.rb

@@ -79,6 +79,14 @@
   end
 
   config.after(:each) do
+    if Sentry.initialized?
+      transport = Sentry.get_current_client&.transport
+
+      if transport.is_a?(Sentry::DebugTransport)
+        transport.clear
+      end
+    end
+
     reset_sentry_globals!
   end