Active Support 事件报告器¶ ↑

ActiveSupport::EventReporter 提供了一个接口，用于向订阅者报告结构化事件。

要报告一个事件，可以使用 notify 方法

Rails.event.notify("user_created", { id: 123 })
# Emits event:
#  {
#    name: "user_created",
#    payload: { id: 123 },
#    timestamp: 1738964843208679035,
#    source_location: { filepath: "path/to/file.rb", lineno: 123, label: "UserService#create" }
#  }

notify API 可以接收事件名称和负载哈希，或者一个事件对象。名称会被强制转换为字符串。

事件对象¶ ↑

如果将事件对象传递给 notify API，它将按原样传递给订阅者，并且对象的类名将用作事件名称。

class UserCreatedEvent
  def initialize(id:, name:)
    @id = id
    @name = name
  end

  def serialize
    {
      id: @id,
      name: @name
    }
  end
end

Rails.event.notify(UserCreatedEvent.new(id: 123, name: "John Doe"))
# Emits event:
#  {
#    name: "UserCreatedEvent",
#    payload: #<UserCreatedEvent:0x111>,
#    timestamp: 1738964843208679035,
#    source_location: { filepath: "path/to/file.rb", lineno: 123, label: "UserService#create" }
#  }

事件是任何代表模式化事件的 Ruby 对象。虽然负载哈希允许任意的、隐式结构的​​数据，但事件对象旨在强制执行特定的模式。

订阅者负责序列化事件对象。

订阅者¶ ↑

订阅者必须实现 emit 方法，该方法将使用事件哈希进行调用。

事件哈希具有以下键

name: String (The name of the event)
payload: Hash, Object (The payload of the event, or the event object itself)
tags: Hash (The tags of the event)
context: Hash (The context of the event)
timestamp: Float (The timestamp of the event, in nanoseconds)
source_location: Hash (The source location of the event, containing the filepath, lineno, and label)

订阅者负责在将事件发送到目标目的地（例如流媒体平台、日志设备或警报服务）之前，将事件编码为所需的格式。

class JSONEventSubscriber
  def emit(event)
    json_data = JSON.generate(event)
    LogExporter.export(json_data)
  end
end

class LogSubscriber
  def emit(event)
    payload = event[:payload].map { |key, value| "#{key}=#{value}" }.join(" ")
    source_location = event[:source_location]
    log = "[#{event[:name]}] #{payload} at #{source_location[:filepath]}:#{source_location[:lineno]}"
    Rails.logger.info(log)
  end
end

请注意，事件对象将按原样传递给订阅者，并且可能需要在编码之前进行序列化

class UserCreatedEvent
  def initialize(id:, name:)
    @id = id
    @name = name
  end

  def serialize
    {
      id: @id,
      name: @name
    }
  end
end

class LogSubscriber
  def emit(event)
    payload = event[:payload]
    json_data = JSON.generate(payload.serialize)
    LogExporter.export(json_data)
  end
end

过滤订阅¶ ↑

可以通过可选的过滤器过程配置订阅者，以便只接收一部分事件

# Only receive events with names starting with "user."
Rails.event.subscribe(user_subscriber) { |event| event[:name].start_with?("user.") }

# Only receive events with specific payload types
Rails.event.subscribe(audit_subscriber) { |event| event[:payload].is_a?(AuditEvent) }

调试事件¶ ↑

您可以使用 debug 方法报告一个事件，该事件仅在事件报告器处于调试模式时才会报告

Rails.event.debug("my_debug_event", { foo: "bar" })

标签¶ ↑

要为事件添加额外的上下文，与事件负载分开，可以通过 tagged 方法添加标签

Rails.event.tagged("graphql") do
  Rails.event.notify("user_created", { id: 123 })
end

# Emits event:
#  {
#    name: "user_created",
#    payload: { id: 123 },
#    tags: { graphql: true },
#    context: {},
#    timestamp: 1738964843208679035,
#    source_location: { filepath: "path/to/file.rb", lineno: 123, label: "UserService#create" }
#  }

上下文存储¶ ↑

您可能希望将元数据附加到报告器发出的每个事件。虽然标签为一系列事件提供了特定域的上下文，但上下文作用域限定为作业/请求，并应用于与执行上下文相关的元数据。可以通过 set_context 方法设置上下文

Rails.event.set_context(request_id: "abcd123", user_agent: "TestAgent")
Rails.event.notify("user_created", { id: 123 })

# Emits event:
#  {
#    name: "user_created",
#    payload: { id: 123 },
#    tags: {},
#    context: { request_id: "abcd123", user_agent: TestAgent" },
#    timestamp: 1738964843208679035,
#    source_location: { filepath: "path/to/file.rb", lineno: 123, label: "UserService#create" }
#  }

每次请求之前和之后都会自动重置上下文。

可以通过 config.active_support.event_reporter_context_store 配置自定义上下文存储。

# config/application.rb
config.active_support.event_reporter_context_store = CustomContextStore

class CustomContextStore
  class << self
    def context
      # Return the context.
    end

    def set_context(context_hash)
      # Append context_hash to the existing context store.
    end

    def clear
      # Delete the stored context.
    end
  end
end

事件报告器对所有负载数据、标签和上下文存储条目使用符号键进行标准化。 String 键会自动转换为符号以保持一致性。

Rails.event.notify("user.created", { "id" => 123 })
# Emits event:
#  {
#    name: "user.created",
#    payload: { id: 123 },
#  }

安全¶ ↑

报告事件时，基于哈希的负载会自动过滤以根据 Rails.application.filter_parameters 删除敏感数据。

如果提供的是 事件对象，订阅者将需要自己过滤敏感数据，例如使用 ActiveSupport::ParameterFilter。