Structured event subscribers

actionmailer/CHANGELOG.md

@@ -1,3 +1,11 @@
+*   Add structured events for Action Mailer:
+    - `action_mailer.delivery_error`
+    - `action_mailer.delivered`
+    - `action_mailer.delivery_skipped`
+    - `action_mailer.processed`
+
+    *Gannon McGibbon*
+
 ## Rails 8.1.0.beta1 (September 04, 2025) ##
 
 *   Add `deliver_all_later` to enqueue multiple emails at once.

actionmailer/lib/action_mailer/base.rb

@@ -7,6 +7,7 @@
 require "active_support/core_ext/module/anonymous"
 
 require "action_mailer/log_subscriber"
+require "action_mailer/structured_event_subscriber"
 require "action_mailer/rescuable"
 
 module ActionMailer

actionmailer/lib/action_mailer/structured_event_subscriber.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "active_support/structured_event_subscriber"
+
+module ActionMailer
+  class StructuredEventSubscriber < ActiveSupport::StructuredEventSubscriber # :nodoc:
+    # An email was delivered.
+    def deliver(event)
+      if (exception = event.payload[:exception_object])
+        emit_debug_event("action_mailer.delivery_error",
+          message_id: event.payload[:message_id],
+          exception_class: exception.class.name,
+          exception_message:  exception.message,
+          mail: event.payload[:mail],
+        )
+      elsif event.payload[:perform_deliveries]
+        emit_debug_event("action_mailer.delivered",
+          message_id: event.payload[:message_id],
+          duration: event.duration.round(1),
+          mail: event.payload[:mail],
+        )
+      else
+        emit_debug_event("action_mailer.delivery_skipped",
+          message_id: event.payload[:message_id],
+          mail: event.payload[:mail],
+        )
+      end
+    end
+    debug_only :deliver
+
+    # An email was generated.
+    def process(event)
+      emit_debug_event("action_mailer.processed",
+        mailer: event.payload[:mailer],
+        action: event.payload[:action],
+        duration: event.duration.round(1),
+      )
+    end
+    debug_only :process
+  end
+end
+
+ActionMailer::StructuredEventSubscriber.attach_to :action_mailer

actionmailer/test/structured_event_subscriber_test.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "abstract_unit"
+require "active_support/testing/event_reporter_assertions"
+require "mailers/base_mailer"
+require "action_mailer/structured_event_subscriber"
+
+module ActionMailer
+  class StructuredEventSubscriberTest < ActionMailer::TestCase
+    include ActiveSupport::Testing::EventReporterAssertions
+
+    class BogusDelivery
+      def initialize(*)
+      end
+
+      def deliver!(mail)
+        raise "failed"
+      end
+    end
+
+    def run(*)
+      ActiveSupport.event_reporter.with_debug do
+        super
+      end
+    end
+
+    def test_deliver_is_notified
+      event = assert_event_reported("action_mailer.delivered", payload: { message_id: "123@abc", mail: /.*/ }) do
+        BaseMailer.welcome(message_id: "123@abc").deliver_now
+      end
+
+      assert event[:payload][:duration] > 0
+    ensure
+      BaseMailer.deliveries.clear
+    end
+
+    def test_deliver_message_when_perform_deliveries_is_false
+      assert_event_reported("action_mailer.delivery_skipped", payload: { message_id: "123@abc", mail: /.*/ }) do
+        BaseMailer.welcome_without_deliveries(message_id: "123@abc").deliver_now
+      end
+    ensure
+      BaseMailer.deliveries.clear
+    end
+
+    def test_deliver_message_when_exception_happened
+      previous_delivery_method = BaseMailer.delivery_method
+      BaseMailer.delivery_method = BogusDelivery
+      payload = { message_id: "123@abc", mail: /.*/, exception_class: "RuntimeError", exception_message: "failed" }
+
+      assert_event_reported("action_mailer.delivery_error", payload:) do
+        assert_raises(RuntimeError) { BaseMailer.welcome(message_id: "123@abc").deliver_now }
+      end
+    ensure
+      BaseMailer.delivery_method = previous_delivery_method
+    end
+  end
+end

actionpack/CHANGELOG.md

@@ -1,3 +1,17 @@
+*   Add structured events for Action Pack and Action Dispatch:
+    - `action_dispatch.redirect`
+    - `action_controller.request_started`
+    - `action_controller.request_completed`
+    - `action_controller.callback_halted`
+    - `action_controller.rescue_from_handled`
+    - `action_controller.file_sent`
+    - `action_controller.redirected`
+    - `action_controller.data_sent`
+    - `action_controller.unpermitted_parameters`
+    - `action_controller.fragment_cache`
+
+    *Adrianna Chang*
+
 *   URL helpers for engines mounted at the application root handle `SCRIPT_NAME` correctly.
 
     Fixed an issue where `SCRIPT_NAME` is not applied to paths generated for routes in an engine

actionpack/lib/action_controller/api.rb

@@ -5,6 +5,7 @@
 require "action_view"
 require "action_controller"
 require "action_controller/log_subscriber"
+require "action_controller/structured_event_subscriber"
 
 module ActionController
   # # Action Controller API

actionpack/lib/action_controller/base.rb

@@ -4,6 +4,7 @@
 
 require "action_view"
 require "action_controller/log_subscriber"
+require "action_controller/structured_event_subscriber"
 require "action_controller/metal/params_wrapper"
 
 module ActionController

actionpack/lib/action_controller/structured_event_subscriber.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module ActionController
+  class StructuredEventSubscriber < ActiveSupport::StructuredEventSubscriber # :nodoc:
+    INTERNAL_PARAMS = %w(controller action format _method only_path)
+
+    def start_processing(event)
+      payload = event.payload
+      params = {}
+      payload[:params].each_pair do |k, v|
+        params[k] = v unless INTERNAL_PARAMS.include?(k)
+      end
+      format = payload[:format]
+      format = format.to_s.upcase if format.is_a?(Symbol)
+      format = "*/*" if format.nil?
+
+      emit_event("action_controller.request_started",
+        controller: payload[:controller],
+        action: payload[:action],
+        format:,
+        params:,
+      )
+    end
+
+    def process_action(event)
+      payload = event.payload
+      status = payload[:status]
+
+      if status.nil? && (exception_class_name = payload[:exception]&.first)
+        status = ActionDispatch::ExceptionWrapper.status_code_for_exception(exception_class_name)
+      end
+
+      emit_event("action_controller.request_completed", {
+        controller: payload[:controller],
+        action: payload[:action],
+        status: status,
+        duration_ms: event.duration.round(2),
+        gc_time_ms: event.gc_time.round(1),
+      }.compact)
+    end
+
+    def halted_callback(event)
+      emit_event("action_controller.callback_halted", filter: event.payload[:filter])
+    end
+
+    def rescue_from_callback(event)
+      exception = event.payload[:exception]
+      emit_event("action_controller.rescue_from_handled",
+        exception_class: exception.class.name,
+        exception_message: exception.message,
+        exception_backtrace: exception.backtrace&.first&.delete_prefix("#{Rails.root}/")
+      )
+    end
+
+    def send_file(event)
+      emit_event("action_controller.file_sent", path: event.payload[:path], duration_ms: event.duration.round(1))
+    end
+
+    def redirect_to(event)
+      emit_event("action_controller.redirected", location: event.payload[:location])
+    end
+
+    def send_data(event)
+      emit_event("action_controller.data_sent", filename: event.payload[:filename], duration_ms: event.duration.round(1))
+    end
+
+    def unpermitted_parameters(event)
+      unpermitted_keys = event.payload[:keys]
+      context = event.payload[:context]
+
+      params = {}
+      context[:params].each_pair do |k, v|
+        params[k] = v unless INTERNAL_PARAMS.include?(k)
+      end
+
+      emit_debug_event("action_controller.unpermitted_parameters",
+        controller: context[:controller],
+        action: context[:action],
+        unpermitted_keys:,
+        params:
+      )
+    end
+    debug_only :unpermitted_parameters
+
+    %w(write_fragment read_fragment exist_fragment? expire_fragment).each do |method|
+      class_eval <<-METHOD, __FILE__, __LINE__ + 1
+        # frozen_string_literal: true
+        def #{method}(event)
+          return unless ActionController::Base.enable_fragment_cache_logging
+
+          key = ActiveSupport::Cache.expand_cache_key(event.payload[:key] || event.payload[:path])
+
+          emit_event("action_controller.fragment_cache",
+            method: "#{method}",
+            key: key,
+            duration_ms: event.duration.round(1)
+          )
+        end
+      METHOD
+    end
+  end
+end
+
+ActionController::StructuredEventSubscriber.attach_to :action_controller

actionpack/lib/action_dispatch/railtie.rb

@@ -4,6 +4,7 @@
 
 require "action_dispatch"
 require "action_dispatch/log_subscriber"
+require "action_dispatch/structured_event_subscriber"
 require "active_support/messages/rotation_configuration"
 
 module ActionDispatch

actionpack/lib/action_dispatch/structured_event_subscriber.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module ActionDispatch
+  class StructuredEventSubscriber < ActiveSupport::StructuredEventSubscriber # :nodoc:
+    def redirect(event)
+      payload = event.payload
+      status = payload[:status]
+
+      emit_event("action_dispatch.redirect", {
+        location: payload[:location],
+        status: status,
+        status_name: Rack::Utils::HTTP_STATUS_CODES[status],
+        duration_ms: event.duration.round(2)
+      })
+    end
+  end
+end
+
+ActionDispatch::StructuredEventSubscriber.attach_to :action_dispatch