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

@@ -4,6 +4,9 @@ module Sentry
   module TestHelper
     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 +49,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
+      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,72 @@
+# 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
+
+    alias_method :__getobj__, :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

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+RSpec.describe Sentry do
+  let(:client) { Sentry.get_current_client }
+  let(:transport) { Sentry.get_current_client.transport }
+  let(:error) { StandardError.new("test error") }
+
+  before do
+    perform_basic_setup
+
+    setup_sentry_test do |config|
+      config.dsn = dsn
+      config.transport.transport_class = Sentry::DebugTransport
+      config.debug = true
+    end
+  end
+
+  after do
+    teardown_sentry_test
+  end
+
+  context "with local DSN for testing" do
+    let(:dsn) { Sentry::TestHelper::DUMMY_DSN }
+
+    describe ".capture_exception with debug transport" do
+      it "logs envelope data and stores an event internally" do
+        Sentry.capture_exception(error)
+
+        expect(transport.events.count).to be(1)
+        expect(transport.backend.events.count).to be(1)
+        expect(transport.backend.envelopes.count).to be(1)
+
+        event = transport.logged_envelopes.last
+        item = event["items"].first
+        payload = item["payload"]
+
+        expect(payload["exception"]["values"].first["value"]).to include("test error")
+      end
+    end
+  end
+
+  context "with a real DSN for testing" do
+    let(:dsn) { Sentry::TestHelper::REAL_DSN }
+
+    describe ".capture_exception with debug transport" do
+      it "sends an event and logs envelope" do
+        stub_request(:post, "https://getsentry.io/project/api/42/envelope/")
+          .to_return(status: 200, body: "", headers: {})
+
+        Sentry.capture_exception(error)
+
+        expect(transport.logged_envelopes.count).to be(1)
+
+        event = transport.logged_envelopes.last
+        item = event["items"].first
+        payload = item["payload"]
+
+        expect(payload["exception"]["values"].first["value"]).to include("test error")
+      end
+    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