Add default encoders for JSON and MessagePack

Add JSON and MessagePack encoders to ActiveSupport::EventReporter.
This allows applications to serialize events to common formats without
needing to implement their own serialization logic in subscribers.

Author: adrianna-chang-shopify

activesupport/CHANGELOG.md

@@ -22,13 +22,15 @@
     Rails.event.set_context(request_id: "abc123", shop_id: 456)
     ```
 
-    Events are emitted to subscribers. Applications register subscribers
-    to control how events are serialized and emitted.
+    Events are emitted to subscribers. Applications register subscribers to
+    control how events are serialized and emitted. Rails provides several default
+    encoders that can be used to serialize events to common formats:
 
     ```ruby
     class MySubscriber
       def emit(event)
-        # Serialize event and export to logging platform
+        encoded_event = ActiveSupport::EventReporter.encoder(:json).encode(event)
+        StructuredLogExporter.export(encoded_event)
       end
     end
 

activesupport/lib/active_support/event_reporter.rb

@@ -1,6 +1,8 @@
 # typed: true
 # frozen_string_literal: true
 
+require_relative "event_reporter/encoders"
+
 module ActiveSupport
   class TagStack # :nodoc:
     EMPTY_TAGS = {}.freeze
@@ -94,38 +96,37 @@ def clear
   #   #  }
   #
   # These objects should represent schematized events and be serializable.
-  # There are no restrictions on what interface these objects should implement, or how they should be
-  # serialized. Subscribers are expected to know how to serialize their events.
   #
-  # For example, here is an event class:
+  # ==== Default Encoders
   #
-  #   class UserCreatedEvent
-  #     def initialize(id:, name:)
-  #       @id = id
-  #       @name = name
-  #     end
+  # Rails provides default encoders for common serialization formats. Event objects and tags MUST
+  # implement +to_h+ to be serialized.
   #
-  #     def to_h
-  #       {
-  #         id: @id,
-  #         name: @name,
-  #       }
+  #   class JSONLogSubscriber
+  #     def emit(event)
+  #       # event = { name: "UserCreatedEvent", payload: { UserCreatedEvent: #<UserCreatedEvent:0x111> } }
+  #       json_data = ActiveSupport::EventReporter.encoder(:json).encode(event)
+  #       # => {
+  #       #      "name": "UserCreatedEvent",
+  #       #      "payload": {
+  #       #        "id": 123,
+  #       #        "name": "John Doe"
+  #       #      }
+  #       #    }
+  #       Rails.logger.info(json_data)
   #     end
   #   end
   #
-  # And a subscriber implementation that uses this event class:
-  #
-  #   class EventReporterSubscriber
+  #   class MessagePackSubscriber
   #     def emit(event)
-  #       name = event[:name]
-  #       event_payload = event[:payload].to_h
-  #       # => { id: 123, name: "John Doe" }
-  #       encoded_data = LogEncoder.encode(name, event_payload)
-  #       ExportService.export(encoded_data)
+  #       msgpack_data = ActiveSupport::EventReporter.encoder(:msgpack).encode(event)
+  #       BatchExporter.export(msgpack_data)
   #     end
   #   end
   #
-  # You can also use the +debug+ method to report an event that will only be reported if the
+  # ==== Debug Events
+  #
+  # You can use the +debug+ method to report an event that will only be reported if the
   # event reporter is in debug mode:
   #
   #   Rails.event.debug("my_debug_event", { foo: "bar" })
@@ -195,6 +196,31 @@ class EventReporter
 
     class << self
       attr_accessor :context_store # :nodoc:
+
+      # Lookup an encoder by name or symbol
+      #
+      #   ActiveSupport::EventReporter.encoder(:json)
+      #   # => ActiveSupport::EventReporter::Encoders::JSON
+      #
+      #   ActiveSupport::EventReporter.encoder("msgpack")
+      #   # => ActiveSupport::EventReporter::Encoders::MessagePack
+      #
+      # ==== Arguments
+      #
+      # * +format+ - The encoder format as a symbol or string
+      #
+      # ==== Raises
+      #
+      # * +KeyError+ - If the encoder format is not found
+      def encoder(format)
+        encoders = {
+          json: Encoders::JSON,
+          msgpack: Encoders::MessagePack
+        }
+        encoders.fetch(format.to_sym) do
+          raise KeyError, "Unknown encoder format: #{format.inspect}. Available formats: #{encoders.keys.join(', ')}"
+        end
+      end
     end
 
     self.context_store = EventContext

activesupport/lib/active_support/event_reporter/encoders.rb

@@ -0,0 +1,89 @@
+# typed: true
+# frozen_string_literal: true
+
+module ActiveSupport
+  class EventReporter
+    # = Event Encoders
+    #
+    # Default encoders for serializing structured events. These encoders can be used
+    # by subscribers to convert event data into various formats.
+    #
+    # Example usage in a subscriber:
+    #
+    #   class LogSubscriber
+    #     def emit(event)
+    #       encoded_data = ActiveSupport::EventReporter::Encoders::JSON.encode(event)
+    #       Rails.logger.info(encoded_data)
+    #     end
+    #   end
+    #
+    module Encoders
+      # Base encoder class that other encoders can inherit from
+      class Base
+        # Encodes an event hash into a serialized format
+        #
+        # @param event [Hash] The event hash containing name, payload, tags, context, timestamp, and source_location
+        # @return [String] The encoded event data
+        def self.encode(event)
+          raise NotImplementedError, "Subclasses must implement #encode"
+        end
+      end
+
+      # JSON encoder for serializing events to JSON format.
+      #
+      #   event = { name: "user_created", payload: { id: 123 }, tags: { api: true } }
+      #   ActiveSupport::EventReporter::Encoders::JSON.encode(event)
+      #   # => {
+      #   #      "name": "user_created",
+      #   #      "payload": {
+      #   #        "id": 123
+      #   #      },
+      #   #      "tags": {
+      #   #        "api": true
+      #   #      },
+      #   #      "context": {}
+      #   #    }
+      #
+      # Schematized events and tags MUST respond to #to_h to be serialized.
+      #
+      #   event = { name: "UserCreatedEvent", payload: #<UserCreatedEvent:0x111>, tags: { "GraphqlTag": #<GraphqlTag:0x111> } }
+      #   ActiveSupport::EventReporter::Encoders::JSON.encode(event)
+      #   # => {
+      #   #      "name": "UserCreatedEvent",
+      #   #      "payload": {
+      #   #        "id": 123
+      #   #      },
+      #   #      "tags": {
+      #   #        "GraphqlTag": {
+      #   #          "operation_name": "user_created",
+      #   #          "operation_type": "mutation"
+      #   #        }
+      #   #      },
+      #   #      "context": {}
+      #   #    }
+
+      class JSON < Base
+        def self.encode(event)
+          event[:payload] = event[:payload].to_h
+          event[:tags] = event[:tags].transform_values do |value|
+            value.respond_to?(:to_h) ? value.to_h : value
+          end
+          ::JSON.dump(event)
+        end
+      end
+
+      class MessagePack < Base
+        def self.encode(event)
+          require "msgpack"
+          event[:payload] = event[:payload].to_h
+          event[:tags] = event[:tags].transform_values do |value|
+            value.respond_to?(:to_h) ? value.to_h : value
+          end
+          ::MessagePack.pack(event)
+        rescue LoadError
+          raise LoadError, "msgpack gem is required for MessagePack encoding. Add 'gem \"msgpack\"' to your Gemfile."
+        end
+      end
+    end
+  end
+end

activesupport/test/event_reporter_test.rb

@@ -3,6 +3,7 @@
 
 require_relative "abstract_unit"
 require "active_support/event_reporter/test_helper"
+require "json"
 
 module ActiveSupport
   class EventReporterTest < ActiveSupport::TestCase
@@ -534,4 +535,130 @@ class ContextStoreTest < ActiveSupport::TestCase
       end
     end
   end
+
+  class EncodersTest < ActiveSupport::TestCase
+    TestEvent = Class.new do
+      class << self
+        def name
+          "TestEvent"
+        end
+      end
+
+      def initialize(data)
+        @data = data
+      end
+
+      def to_h
+        {
+          data: @data
+        }
+      end
+    end
+
+    HttpRequestTag = Class.new do
+      class << self
+        def name
+          "HttpRequestTag"
+        end
+      end
+
+      def initialize(http_method, http_status)
+        @http_method = http_method
+        @http_status = http_status
+      end
+
+      def to_h
+        {
+          http_method: @http_method,
+          http_status: @http_status
+        }
+      end
+    end
+
+    setup do
+      @event = {
+        name: "test_event",
+        payload: { id: 123, message: "hello" },
+        tags: { section: "admin" },
+        context: { user_id: 456 },
+        timestamp: 1738964843208679035,
+        source_location: { filepath: "/path/to/file.rb", lineno: 42, label: "test_method" }
+      }
+    end
+
+    test "looking up encoder by symbol" do
+      assert_equal EventReporter::Encoders::JSON, EventReporter.encoder(:json)
+      assert_equal EventReporter::Encoders::MessagePack, EventReporter.encoder(:msgpack)
+    end
+
+    test "looking up encoder by string" do
+      assert_equal EventReporter::Encoders::JSON, EventReporter.encoder("json")
+      assert_equal EventReporter::Encoders::MessagePack, EventReporter.encoder("msgpack")
+    end
+
+    test "looking up nonexistant encoder raises KeyError" do
+      error = assert_raises(KeyError) do
+        EventReporter.encoder(:unknown)
+      end
+      assert_equal "Unknown encoder format: :unknown. Available formats: json, msgpack", error.message
+    end
+
+    test "Base encoder raises NotImplementedError" do
+      assert_raises(NotImplementedError) do
+        EventReporter::Encoders::Base.encode(@event)
+      end
+    end
+
+    test "JSON encoder encodes event to JSON" do
+      json_string = EventReporter::Encoders::JSON.encode(@event)
+      parsed = ::JSON.parse(json_string)
+
+      assert_equal "test_event", parsed["name"]
+      assert_equal({ "id" => 123, "message" => "hello" }, parsed["payload"])
+      assert_equal({ "section" => "admin" }, parsed["tags"])
+      assert_equal({ "user_id" => 456 }, parsed["context"])
+      assert_equal 1738964843208679035, parsed["timestamp"]
+      assert_equal({ "filepath" => "/path/to/file.rb", "lineno" => 42, "label" => "test_method" }, parsed["source_location"])
+    end
+
+    test "JSON encoder serializes event objects and object tags as hashes" do
+      @event[:payload] = TestEvent.new("value")
+      @event[:tags] = { "HttpRequestTag": HttpRequestTag.new("GET", 200) }
+      json_string = EventReporter::Encoders::JSON.encode(@event)
+      parsed = ::JSON.parse(json_string)
+
+      assert_equal "value", parsed["payload"]["data"]
+      assert_equal "GET", parsed["tags"]["HttpRequestTag"]["http_method"]
+      assert_equal 200, parsed["tags"]["HttpRequestTag"]["http_status"]
+    end
+
+    test "MessagePack encoder encodes event to MessagePack" do
+      begin
+        require "msgpack"
+      rescue LoadError
+        skip "msgpack gem not available"
+      end
+
+      msgpack_data = EventReporter::Encoders::MessagePack.encode(@event)
+      parsed = ::MessagePack.unpack(msgpack_data)
+
+      assert_equal "test_event", parsed["name"]
+      assert_equal({ "id" => 123, "message" => "hello" }, parsed["payload"])
+      assert_equal({ "section" => "admin" }, parsed["tags"])
+      assert_equal({ "user_id" => 456 }, parsed["context"])
+      assert_equal 1738964843208679035, parsed["timestamp"]
+      assert_equal({ "filepath" => "/path/to/file.rb", "lineno" => 42, "label" => "test_method" }, parsed["source_location"])
+    end
+
+    test "MessagePack encoder serializes event objects and object tags as hashes" do
+      @event[:payload] = TestEvent.new("value")
+      @event[:tags] = { "HttpRequestTag": HttpRequestTag.new("GET", 200) }
+      msgpack_data = EventReporter::Encoders::MessagePack.encode(@event)
+      parsed = ::MessagePack.unpack(msgpack_data)
+
+      assert_equal "value", parsed["payload"]["data"]
+      assert_equal "GET", parsed["tags"]["HttpRequestTag"]["http_method"]
+      assert_equal 200, parsed["tags"]["HttpRequestTag"]["http_status"]
+    end
+  end
 end