Репортёр событий 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" }
#  }

API notify принимает либо имя события и хеш с полезной нагрузкой, либо объект события. Имена преобразуются в строки.

Объекты событий

Если API notify передан объект события, он будет передан подписчикам без изменений, а имя класса объекта будет использовано в качестве имени события.

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

Подписки с фильтрацией

Для подписчиков можно настроить необязательный proc-фильтр, чтобы они получали только часть событий:

# 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 },
#  }

Безопасность

При передаче событий полезные нагрузки на основе Hash автоматически фильтруются для удаления конфиденциальных данных согласно настройке Rails.application.filter_parameters.

Если вместо этого передан объект события, подписчикам потребуется самостоятельно фильтровать конфиденциальные данные, например с помощью ActiveSupport::ParameterFilter.