Active Support の Instrumentation 機能

1 Instrumentationについて

Active Supportが提供するInstrumentation APIを使ってフックを開発すると、他の開発者がそこにフックできるようになります。フックの多くは、Railsフレームワーク向けです。このAPIをアプリケーションで実装すると、アプリケーション（またはRubyコード片）内部でイベントが発生したときに通知を受け取れるよう他の開発者が設定できます。

たとえばActive Recordには、データベースへのSQLクエリが発行されるたびに呼び出されるフックが用意されていますこのフックをサブスクライブ（購読）すると、特定のアクションでのクエリ実行数を追跡できます。他に、コントローラのアクション実行中に呼び出されるフックもあります。このフックは、たとえば特定のアクション実行に要する時間の測定に利用できます。

もちろん、アプリケーション内に独自のイベントを作成し、後で自分でサブスクライブして測定することもできます。

2 Railsフレームワーク用フック

Ruby on Railsでは、フレームワーク内の主なイベント向けのフックが多数提供されています詳しくは次をご覧ください。

3 Action Controller

3.1 write_fragment.action_controller

キー	値
`:key`	完全なキー

{
  key: 'posts/1-dashboard-view'
}

3.2 read_fragment.action_controller

キー	値
`:key`	完全なキー

{
  key: 'posts/1-dashboard-view'
}

3.3 expire_fragment.action_controller

Key	Value
`:key`	完全なキー

{
  key: 'posts/1-dashboard-view'
}

3.4 exist_fragment?.action_controller

キー	値
`:key`	完全なキー

{
  key: 'posts/1-dashboard-view'
}

3.5 write_page.action_controller

キー	値
`:path`	完全なパス

{
  path: '/users/1'
}

3.6 expire_page.action_controller

キー	値
`:path`	完全なパス

{
  path: '/users/1'
}

3.7 start_processing.action_controller

キー	値
`:controller`	コントローラ名
`:action`	アクション
`:params`	リクエストパラメータのハッシュ（フィルタされたパラメータは含まない）
`:headers`	リクエストヘッダー
`:format`	html/js/json/xml など
`:method`	HTTP リクエストメソッド（verb）
`:path`	リクエストパス

{
  controller: "PostsController",
  action: "new",
  params: { "action" => "new", "controller" => "posts" },
  headers: #<ActionDispatch::Http::Headers:0x0055a67a519b88>,
  format: :html,
  method: "GET",
  path: "/posts/new"
}

3.8 process_action.action_controller

キー	値
`:controller`	コントローラ名
`:action`	アクション
`:params`	リクエストパラメータのハッシュ（フィルタされたパラメータは含まない）
`:headers`	リクエストヘッダー
`:format`	html/js/json/xml など
`:method`	HTTP リクエストメソッド（verb）
`:path`	リクエストパス
`:status`	HTTP ステータスコード
`:view_runtime`	ビューでかかった合計時間（ms）
`:db_runtime`	データベースへのクエリ実行にかかった時間（ms）

{
  controller: "PostsController",
  action: "index",
  params: {"action" => "index", "controller" => "posts"},
  headers: #<ActionDispatch::Http::Headers:0x0055a67a519b88>,
  format: :html,
  method: "GET",
  path: "/posts",
  status: 200,
  view_runtime: 46.848,
  db_runtime: 0.157
}

3.9 send_file.action_controller

キー	値
`:path`	ファイルへの完全なパス

呼び出し側でキーが追加される可能性があります。

3.10 send_data.action_controller

ActionController自身は、ペイロードに情報を持ちません。オプションは、すべてペイロード経由で渡されます。

3.11 redirect_to.action_controller

キー	値
`:status`	HTTP レスポンスコード
`:location`	リダイレクト先URL

{
  status: 302,
  location: "http://localhost:3000/posts/new"
}

3.12 halted_callback.action_controller

キー	値
`:filter`	アクションを停止させたフィルタ

{
  filter: ":halting_filter"
}

3.13 unpermitted_parameters.action_controller

キー	値
`:keys`	許可されていないキー

4 Action View

4.1 render_template.action_view

キー	値
`:identifier`	テンプレートへの完全なパス
`:layout`	該当のレイアウト

{
  identifier: "/Users/adam/projects/notifications/app/views/posts/index.html.erb",
  layout: "layouts/application"
}

4.2 render_partial.action_view

キー	値
`:identifier`	テンプレートへの完全なパス

{
  identifier: "/Users/adam/projects/notifications/app/views/posts/_form.html.erb"
}

4.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
}

5 Active Record

5.1 sql.active_record

キー	値
`:sql`	SQL文
`:name`	操作の名前
`:connection_id`	`self.object_id`
`:binds`	バインドするパラメータ
`:cached`	キャッシュされたクエリが使われると`true`が追加される

アダプタも独自のデータを追加します。

{
  sql: "SELECT \"posts\".* FROM \"posts\" ",
  name: "Post Load",
  connection_id: 70307250813140,
  binds: []
}

5.2 instantiation.active_record

Key	Value
`:record_count`	レコードのインスタンス数
`:class_name`	レコードのクラス

{
  record_count: 1,
  class_name: "User"
}

6 Action Mailer

6.1 receive.action_mailer

キー	値
`:mailer`	メイラークラス名
`:message_id`	Mail gemが生成したメッセージID
`:subject`	メールの件名
`:to`	メールの宛先
`:from`	メールの差出人
`:bcc`	メールのBCCアドレス
`:cc`	メールのCCアドレス
`:date`	メールの日付
`:mail`	メールのエンコード形式

{
  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: "..." #（長いので省略）
}

6.2 deliver.action_mailer

キー	値
`:mailer`	メイラークラス名
`:message_id`	Mail gemが生成したメッセージID
`:subject`	メールの件名
`:to`	メールの宛先
`:from`	メールの差出人
`:bcc`	メールのBCCアドレス
`:cc`	メールのCCアドレス
`:date`	メールの日付
`:mail`	メールのエンコード形式

{
  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: "..." #（長いので省略）
}

6.3 process.action_mailer

キー	値
`:mailer`	メイラーのクラス名
`:action`	アクション
`:args`	引数

{
  mailer: "Notification",
  action: "welcome_email",
  args: []
}

7 Active Support

7.1 cache_read.active_support

キー	値
`:key`	ストアで使われるキー
`:hit`	ヒットしたかどうか
`:super_operation`	読み出しで`#fetch`が指定されている場合に:fetch を追加

7.2 cache_generate.active_support

このイベントは、#fetchをブロック付きで使用した場合にのみ使われます。

キー	値
`:key`	ストアで使われるキー

fetchに渡されたオプションは、ストアへの書き込み時にペイロードとマージされます。

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

7.3 cache_fetch_hit.active_support

このイベントは、#fetchをブロック付きで使用した場合にのみ使われます。

キー	値
`:key`	ストアで使われるキー

fetchに渡されたオプションは、ペイロードとマージされます。

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

7.4 cache_write.active_support

キー	値
`:key`	ストアで使われるキー

キャッシュストアが独自のキーを追加することがあります。

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

7.5 cache_delete.active_support

キー	値
`:key`	ストアで使われるキー

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

7.6 cache_exist?.active_support

キー	値
`:key`	ストアで使われるキー

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

8 Active Job

8.1 enqueue_at.active_job

キー	値
`:adapter`	ジョブを処理するQueueAdapterオブジェクト
`:job`	Jobオブジェクト

8.2 enqueue.active_job

キー	値
`:adapter`	ジョブを処理するQueueAdapterオブジェクト
`:job`	Jobオブジェクト

8.3 perform_start.active_job

キー	値
`:adapter`	ジョブを処理するQueueAdapterオブジェクト
`:job`	Jobオブジェクト

8.4 perform.active_job

キー	値
`:adapter`	ジョブを処理するQueueAdapterオブジェクト
`:job`	Jobオブジェクト

9 Action Cable

9.1 perform_action.action_cable

キー	値
`:channel_class`	チャンネルのクラス名
`:action`	アクション
`:data`	日付（ハッシュ）

9.2 transmit.action_cable

キー	値
`:channel_class`	チャンネルのクラス名
`:data`	日付（ハッシュ）
`:via`	経由先

9.3 transmit_subscription_confirmation.action_cable

キー	値
`:channel_class`	チャンネルのクラス名

9.4 transmit_subscription_rejection.action_cable

キー	値
`:channel_class`	チャンネルのクラス名

9.5 broadcast.action_cable

キー	値
`:broadcasting`	名前付きブロードキャスト
`:message`	メッセージ（ハッシュ）
`:coder`	コーダー

10 Active Storage

10.1 service_upload.active_storage

キー	値
`:key`	セキュアトークン
`:service`	サービス名
`:checksum`	完全性を担保するチェックサム

10.2 service_streaming_download.active_storage

キー	値
`:key`	セキュアトークン
`:service`	サービス名

10.3 service_download.active_storage

キー	値
`:key`	セキュアトークン
`:service`	サービス名

10.4 service_delete.active_storage

キー	値
`:key`	セキュアトークン
`:service`	サービス名

10.5 service_exist.active_storage

キー	値
`:key`	セキュアトークン
`:service`	サービス名
`:exist`	ファイルかblogが存在するかどうか

10.6 service_url.active_storage

キー	値
`:key`	セキュアトークン
`:service`	サービス名
`:url`	生成されたURL

11 Railties

11.1 load_config_initializer.railties

キー	値
`:initializer`	`config/initializers`から読み込まれたイニシャライザへのパス

12 Rails

12.1 deprecation.rails

キー	値
`:message`	非推奨機能の警告メッセージ
`:callstack`	非推奨警告の発生元

13 イベントのサブスクライブ

イベントは簡単にサブスクライブできます。ActiveSupport::Notifications.subscribeをブロック付きで記述すれば、すべての通知をリッスンできます。

ブロックでは以下の引数を利用できます。

イベントの名前
イベントの開始時刻
イベントの終了時刻
イベントのユニークID
ペイロード（上の節を参照）

ActiveSupport::Notifications.subscribe "process_action.action_controller" do |name, started, finished, unique_id, data|
  # 自分のコードをここに書く
  Rails.logger.info "#{name} Received!"
end

ブロックの引数を毎回定義しなくても済むよう、次のようなブロック付きのActiveSupport::Notifications::Eventを簡単に定義できます。

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

独自のイベントを自由に追加できます。イベント追加は、ActiveSupport::Notificationsですべてまかなえます。name、payload、ブロックを指定してinstrumentを呼び出すだけで追加完了します。通知は、ブロックが戻ってから送信されます。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

独自のイベントを作成するときは、Railsの規則に従ってください。形式は「event.library」を使いますたとえば、アプリケーションがツイートを送信するのであれば、イベント名はtweet.twitterとなります。

支援・協賛

Railsガイドは下記のサポーターから継続的な支援を受けています。

Active Support の Instrumentation 機能

目次