Инструментарий Active Support

Active Support — часть ядра Rails, которая предоставляет расширение языка Ruby, утилиты и другие возможности. Она включает инструментарий API, который может использоваться внутри приложения, для отслеживания определенных действий, которые возникают как в коде Ruby, так и внутри приложения Rails и самого фреймворка. Однако, она не ограничена Rails. При необходимости ее можно независимо использовать в других скриптах Ruby если вы желаете.

В этом руководстве вы научитесь использовать инструменты Active Support API для отслеживания событий внутри Rails или другого Ruby-кода.

После прочтения данного руководства вы будете знать:

  • Какой инструментарий предоставляется.
  • Как добавить подписчика к хуку.
  • Какие есть хуки внутри фреймворка Rails для инструментария.
  • Как создать произвольную реализацию инструментария.

1. Введение в инструментарий

Инструментарий API, предоставленный Active Support, позволяет разработчикам создавать хуки, которыми могут пользоваться другие разработчики. Некоторые из них присутствуют в фреймворке Rails, как показано ниже. С этим API, разработчики могут быть оповещены при возникновении определенного события в их приложении или другом коде Ruby.

Например, есть хук внутри Active Record который вызывается каждый раз когда Active Record использует запрос SQL к базе данных. На этот хук можно подписаться и использовать его для отслеживания количества запросов в течении определенного экшна. Есть другой хук, оборачивающий экшны контроллеров. Он может быть использован, например, для отслеживания, как долго выполнялся определенный экшн.

Вы даже можете создать свои собственные события внутри приложения, на которые вы потом сможете подписаться.

2. Подписка на события

Подписаться на событие просто. Используйте ActiveSupport::Notifications.subscribe с блоком, чтобы слушать любое уведомление.

Блок получает следующие аргументы:

  • Имя события
  • Время начала
  • Время окончания
  • Уникальный ID для инструментария, запустившего это событие
  • Полезная нагрузка (описывается в следующих разделах)
ActiveSupport::Notifications.subscribe "process_action.action_controller" do |name, started, finished, unique_id, data|
  # ваш собственный код
  Rails.logger.info "#{name} Received! (started: #{started}, finished: #{finished})" # process_action.action_controller Received (started: 2019-05-05 13:43:57 -0800, finished: 2019-05-05 13:43:58 -0800)
end

Если вы беспокоитесь об аккуратности started и finished для вычисления точного прошедшего времени, используйте ActiveSupport::Notifications.monotonic_subscribe. Преданный блок получает те же аргументы, что и предыдущий, но started и finished получит значения более аккуратного монотонного времени вместо секундного дискретного времени.

ActiveSupport::Notifications.monotonic_subscribe "process_action.action_controller" do |name, started, finished, unique_id, data|
  # ваш собственный код
  Rails.logger.info "#{name} Received! (started: #{started}, finished: #{finished})" # process_action.action_controller Received (started: 1560978.425334, finished: 1560979.429234)
end

Определение всех этих аргументов блока каждый раз может быть утомительно. Можно легко создать `ActiveSupport::Notifications::Event` из блока аргументов, например:

```ruby
ActiveSupport::Notifications.subscribe "process_action.action_controller" do |*args|
  event = ActiveSupport::Notifications::Event.new *args

  event.name      # => "process_action.action_controller"
  event.duration  # => 10 (in milliseconds)
  event.payload   # => {:extra=>information}

  Rails.logger.info "#{event} Received!"
end

В основном вас будет интересовать сама информация. Ниже приведен краткий вариант, как можно получить информацию.

ActiveSupport::Notifications.subscribe "process_action.action_controller" do |*args|
  data = args.extract_options!
  data # { extra: :information }
end

Вы можете также подписаться на события, соответствующие регулярному выражению. Это позволит вам подписаться на несколько событий за раз. Вот как можно подписаться на все события ActionController.

ActiveSupport::Notifications.subscribe /action_controller/ do |*args|
  # Проверка всех событий ActionController
end

3. Хуки фреймворка Rails

Внутри фреймворка Ruby on Rails присутствует множество хуков для обычных событий. Они описываются ниже.

4. Action Controller

4.1. write_fragment.action_controller

Ключ Значение
:key Полный ключ
{
  key: 'posts/1-dashboard-view'
}

4.2. read_fragment.action_controller

Ключ Значение
:key Полный ключ
{
  key: 'posts/1-dashboard-view'
}

4.3. expire_fragment.action_controller

Ключ Значение
:key Полный ключ
{
  key: 'posts/1-dashboard-view'
}

4.4. exist_fragment?.action_controller

Ключ Значение
:key Полный ключ
{
  key: 'posts/1-dashboard-view'
}

4.5. write_page.action_controller

Ключ Значение
:path Полный путь
{
  path: '/users/1'
}

4.6. expire_page.action_controller

Ключ Значение
:path Полный путь
{
  path: '/users/1'
}

4.7. start_processing.action_controller

Ключ Значение
:controller Имя контроллера
:action Экшн
:params Хэш параметров запроса без фильтрации параметров
:headers Заголовки запроса
:format html/js/json/xml и.т.д.
:method Метод HTTP-запроса
:path Путь запроса
{
  controller: "PostsController",
  action: "new",
  params: { "action" => "new", "controller" => "posts" },
  headers: #<ActionDispatch::Http::Headers:0x0055a67a519b88>,
  format: :html,
  method: "GET",
  path: "/posts/new"
}

4.8. process_action.action_controller

Ключ Значение
:controller Имя контроллера
:action Экшн
:params Хэш параметров запроса без фильтрации параметров
:headers Заголовки запроса
:format html/js/json/xml и.т.д.
:method Метод HTTP-запроса
:path Путь запроса
:request ActionDispatch::Request
:status Код статуса HTTP
:location Заголовок запроса Location
:view_runtime Количество времени, потраченного во вьюхе
:db_runtime Время, потраченное на выполнение запросов к БД в мс
{
  controller: "PostsController",
  action: "index",
  params: {"action" => "index", "controller" => "posts"},
  headers: #<ActionDispatch::Http::Headers:0x0055a67a519b88>,
  format: :html,
  method: "GET",
  path: "/posts",
  request: #<ActionDispatch::Request:0x00007ff1cb9bd7b8>,
  status: 200,
  view_runtime: 46.848,
  db_runtime: 0.157
}

4.9. send_file.action_controller

Ключ Значение
:path Полный путь к файлу

Дополнительные ключи могут быть добавлены при вызове.

4.10. send_data.action_controller

ActionController не добавляет какой-либо конкретной информации при загрузке. Все опции передаются через полезную нагрузку (payload).

4.11. redirect_to.action_controller

Ключ Значение
:status Код HTTP ответа
:location URL для переадресации
:request ActionDispatch::Request
{
  status: 302,
  location: "http://localhost:3000/posts/new",
  request: #<ActionDispatch::Request:0x00007ff1cb9bd7b8>
}

4.12. halted_callback.action_controller

Ключ Значение
:filter Фильтр, прервавший экшн
{
  filter: ":halting_filter"
}

4.13. unpermitted_parameters.action_controller

Ключ Значение
:keys Неразрешенные ключи

5. Action Dispatch

5.1. process_middleware.action_dispatch

Key Value
:middleware Имя промежуточной программы

6. Action View

6.1. render_template.action_view

Ключ Значение
:identifier Полный путь до шаблона
:layout Применяемый макет
{
  identifier: "/Users/adam/projects/notifications/app/views/posts/index.html.erb",
  layout: "layouts/application"
}

6.2. render_partial.action_view

Ключ Значение
:identifier Полный путь до шаблона
{
  identifier: "/Users/adam/projects/notifications/app/views/posts/_form.html.erb",
}

6.3. render_collection.action_view

Ключ Значение
:identifier Полный путь к шаблону
:count Размер коллекции
:cache_hits Количество партиалов, извлеченных из кэша

:cache_hits включается, только если коллекция рендерится с cached: true.

{
  identifier: "/Users/adam/projects/notifications/app/views/posts/_post.html.erb",
  count: 3,
  cache_hits: 0
}

7. Active Record

7.1. sql.active_record

Ключ Значение
:sql Выражение SQL
:name Имя операции
:connection Объект соединения
:binds Связанные параметры
:type_casted_binds Приведенные связанные параметры
:statement_name Имя выражения SQL
:cached true если использованы кэшированные запросы

Адаптеры будут добавлять свои собственные данные.

{
  sql: "SELECT \"posts\".* FROM \"posts\" ",
  name: "Post Load",
  connection: #<ActiveRecord::ConnectionAdapters::SQLite3Adapter:0x00007f9f7a838850>,
  binds: [#<ActiveModel::Attribute::WithCastValue:0x00007fe19d15dc00>],
  type_casted_binds: [11],
  statement_name: nil
}

7.2. instantiation.active_record

Key Value
:record_count Количество записей
:class_name Класс записи
{
  record_count: 1,
  class_name: "User"
}

8. Action Mailer

8.1. deliver.action_mailer

Ключ Значение
:mailer Имя класса рассыльщика
:message_id ID сообщения, создается Mail гемом
:subject Тема сообщения
:to Адресат(ы) сообщения
:from Отправитель сообщения
:bcc BCC адреса сообщения
:cc CC адреса сообщения
:date Дата сообщения
:mail Кодированная форма сообщения
:perform_deliveries Была ли вызвана доставка этого сообщения или нет
{
  mailer: "Notification",
  message_id: "4f5b5491f1774_181b23fc3d4434d38138e5@mba.local.mail",
  subject: "Rails Guides",
  to: ["users@rails.com", "dhh@rails.com"],
  from: ["me@rails.com"],
  date: Sat, 10 Mar 2012 14:18:09 +0100,
  mail: "...", # опущено для краткости
  perform_deliveries: true
}

8.2. process.action_mailer

Ключ Значение
:mailer Имя класса рассыльщика
:action Экшн
:args Аргументы
{
  mailer: "Notification",
  action: "welcome_email",
  args: []
}

9. Active Support

9.1. cache_read.active_support

Ключ Значение
:key Ключ, используемый при хранении
:hit Если это чтение успешно
:super_operation :fetch добавляется когда чтение используется с #fetch

9.2. cache_generate.active_support

Это событие используется только когда #fetch вызывается с блоком.

Ключ Значение
:key Ключ, используемый при хранении

Опции, переданные в вызов, будут объединены с полезной нагрузкой при записи в хранилище.

{
  key: 'name-of-complicated-computation'
}

9.3. cache_fetch_hit.active_support

Это событие используется только когда #fetch вызывается с блоком.

Ключ Значение
:key Ключ, используемый при хранении

Опции, переданные в вызов, будут объединены с полезной нагрузкой.

{
  key: 'name-of-complicated-computation'
}

9.4. cache_write.active_support

Ключ Значение
:key Ключ, используемый при хранении

Кэш хранилище может добавить свой собственный ключ.

{
  key: 'name-of-complicated-computation'
}

9.5. cache_delete.active_support

Ключ Значение
:key Ключ, используемый при хранении
{
  key: 'name-of-complicated-computation'
}

9.6. cache_exist?.active_support

Ключ Значение
:key Ключ, используемый при хранении
{
  key: 'name-of-complicated-computation'
}

10. Active Job

10.1. enqueue_at.active_job

Ключ Значение
:adapter Объект QueueAdapter, обрабатывающий задание
:job Объект задания

10.2. enqueue.active_job

Ключ Значение
:adapter Объект QueueAdapter, обрабатывающий задание
:job Объект задания

10.3. enqueue_retry.active_job

Ключ Значение
:job Объект задания
:adapter Объект QueueAdapter, обрабатывающий задание
:error Ошибка, вызвавшая повтор
:wait Задержка повтора

10.4. perform_start.active_job

Ключ Значение
:adapter Объект QueueAdapter, обрабатывающий задание
:job Объект задания

10.5. perform.active_job

Ключ Значение
:adapter Объект QueueAdapter, обрабатывающий задание
:job Объект задания

10.6. retry_stopped.active_job

Ключ Значение
:adapter Объект QueueAdapter, обрабатывающий задание
:job Объект задания
:error Ошибка, вызвавшая повтор

10.7. discard.active_job

Ключ Значение
:adapter Объект QueueAdapter, обрабатывающий задание
:job Объект задания
:error Ошибка, вызвавшая отказ

11. Action Cable

11.1. perform_action.action_cable

Ключ Значение
:channel_class Имя класса канала
:action Экшн
:data Данные хэша

11.2. transmit.action_cable

Ключ Значение
:channel_class Имя класса канала
:data Данные хэша
:via С помощью

11.3. transmit_subscription_confirmation.action_cable

Ключ Значение
:channel_class Имя класса канала

11.4. transmit_subscription_rejection.action_cable

Ключ Значение
:channel_class Имя класса канала

11.5. broadcast.action_cable

Ключ Значение
:broadcasting Имя трансляции
:message Сообщение хэша
:coder Кодировщик

12. Active Storage

12.1. service_upload.active_storage

Ключ Значение
:key Токен безопасности
:service Имя сервиса
:checksum Контрольная сумма для обеспечения целостности

12.2. service_streaming_download.active_storage

Ключ Значение
:key Токен безопасности
:service Имя сервиса

12.3. service_download.active_storage

Ключ Значение
:key Токен безопасности
:service Имя сервиса

12.4. service_download_chunk.active_storage

Ключ Значение
:key Токен безопасности
:service Имя сервиса
:range Диапазон битов к прочтению

12.5. service_delete.active_storage

Ключ Значение
:key Токен безопасности
:service Имя сервиса

12.6. service_delete_prefixed.active_storage

Ключ Значение
:prefix Префикс ключа
:service Имя сервиса

12.7. service_exist.active_storage

Ключ Значение
:key Токен безопасности
:service Имя сервиса
:exist Существует или же нет файл или blob

12.8. service_url.active_storage

Ключ Значение
:key Токен безопасности
:service Имя сервиса
:url Сгенерированный URL

12.9. service_update_metadata.active_storage

Ключ Значение
:key Токен безопасности
:service Имя сервиса
:content_type Поле HTTP Content-Type
:disposition Поле HTTP Content-Disposition

Пока что единственный сервис ActiveStorage, предоставляющий этот хук, это GCS.

12.10. preview.active_storage

Ключ Значение
:key Токен безопасности

13. Railties

13.1. load_config_initializer.railties

Ключ Значение
:initializer Путь к загруженному инициализатору из config/initializers

14. Rails

14.1. deprecation.rails

Ключ Значение
:message Предупреждение устаревания
:callstack Откуда предупреждение пришло

15. Исключения

Если происходит исключение во время любого инструментария, полезная нагрузка будет включать информацию о нем.

Ключ Значение
:exception Массив из двух элементов. Имя класса исключение и сообщение
:exception_object Объект исключения

16. Создание пользовательского события

Добавить свои события очень просто. ActiveSupport::Notifications будет делать всю тяжелую работу за вас. Просто вызовите instrument с name, payload и блоком. Уведомление будет отправлено после возвращения блока. ActiveSupport сгенерирует время старта и окончания и добавит уникальный ID инструментария. Все данные переданные в вызов instrument будут выполнены в полезной нагрузке.

Пример:

ActiveSupport::Notifications.instrument "my.custom.event", this: :data do
  # Создание ваших пользовательских настроек тут
end

Теперь можно слушать это событие:

ActiveSupport::Notifications.subscribe "my.custom.event" do |name, started, finished, unique_id, data|
  puts data.inspect # {:this=>:data}
end

Также есть вариант вызова инструментария без передачи блока. Это позволяет использовать инфраструктуру инструментария для других применений (обмен сообщениями).

ActiveSupport::Notifications.instrument "my.custom.event", this: :data

ActiveSupport::Notifications.subscribe "my.custom.event" do |name, started, finished, unique_id, data|
  puts data.inspect # {:this=>:data}
end

Вы должны следовать соглашениям Rails при создании своих событий. Формат: event.library. Если ваше приложение отправляет Tweets, вы должны назвать событие tweet.twitter.