Active Supportが提供するInstrumentation APIを使ってフックを開発すると、他の開発者がそこにフックできるようになります。フックの多くは、Railsフレームワーク向けです。このAPIをアプリケーションで実装すると、アプリケーション（またはRubyコード片）内部でイベントが発生したときに通知を受け取れるよう他の開発者が設定できます。
たとえばActive Recordには、データベースへのSQLクエリが発行されるたびに呼び出されるフックが用意されていますこのフックをサブスクライブ（購読）すると、特定のアクションでのクエリ実行数を追跡できます。他に、コントローラのアクション実行中に呼び出されるフックもあります。このフックは、たとえば特定のアクション実行に要する時間の測定に利用できます。
もちろん、アプリケーション内に独自のイベントを作成し、後で自分でサブスクライブして測定することもできます。
Ruby on Railsでは、フレームワーク内の主なイベント向けのフックが多数提供されています詳しくは次をご覧ください。
{
key: 'posts/1-dashboard-view'
}
{
key: 'posts/1-dashboard-view'
}
{
key: 'posts/1-dashboard-view'
}
{
key: 'posts/1-dashboard-view'
}
| キー |
値 |
: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"
}
| キー |
値 |
: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
}
ActionController自身は、ペイロードに情報を持ちません。オプションは、すべてペイロード経由で渡されます。
| キー |
値 |
:status |
HTTP レスポンス コード |
:location |
リダイレクト先URL |
{
status: 302,
location: "http://localhost:3000/posts/new"
}
| キー |
値 |
:filter |
アクションを停止させたフィルタ |
{
filter: ":halting_filter"
}
| キー |
値 |
:identifier |
テンプレートへの完全なパス |
:layout |
該当のレイアウト |
{
identifier: "/Users/adam/projects/notifications/app/views/posts/index.html.erb",
layout: "layouts/application"
}
| キー |
値 |
:identifier |
テンプレートへの完全なパス |
{
identifier: "/Users/adam/projects/notifications/app/views/posts/_form.html.erb"
}
| キー |
値 |
:sql |
SQL文 |
:name |
操作の名前 |
:connection_id |
self.object_id |
:binds |
パラメータの割り当て（バインド） |
{
sql: "SELECT \"posts\".* FROM \"posts\" ",
name: "Post Load",
connection_id: 70307250813140,
binds: []
}
| Key |
Value |
:record_count |
レコードのインスタンス数 |
:class_name |
レコードのクラス |
{
record_count: 1,
class_name: "User"
}
| キー |
値 |
: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", "ddh@rails.com"],
from: ["me@rails.com"],
date: Sat, 10 Mar 2012 14:18:09 +0100,
mail: "..." #（長いので省略）
}
| キー |
値 |
: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", "ddh@rails.com"],
from: ["me@rails.com"],
date: Sat, 10 Mar 2012 14:18:09 +0100,
mail: "..." #（長いので省略）
}
| キー |
値 |
:key |
ストアで使われるキー |
:hit |
ヒットしたかどうか |
:super_operation |
読み出しで#fetchが指定されている場合に:fetch を追加 |
このイベントは、#fetchをブロック付きで使用した場合にのみ使われます。
fetchに渡されたオプションは、ストアへの書き込み時にペイロードとマージされます。
{
key: 'name-of-complicated-computation'
}
このイベントは、#fetchをブロック付きで使用した場合にのみ使われます。
fetchに渡されたオプションは、ペイロードとマージされます。
{
key: 'name-of-complicated-computation'
}
キャッシュストアが独自のキーを追加することがあります。
{
key: 'name-of-complicated-computation'
}
{
key: 'name-of-complicated-computation'
}
{
key: 'name-of-complicated-computation'
}
| キー |
値 |
:adapter |
ジョブを処理するQueueAdapterオブジェクト |
:job |
Jobオブジェクト |
| キー |
値 |
:adapter |
ジョブを処理するQueueAdapterオブジェクト |
:job |
Jobオブジェクト |
| キー |
値 |
:adapter |
ジョブを処理するQueueAdapterオブジェクト |
:job |
Jobオブジェクト |
| キー |
値 |
:adapter |
ジョブを処理するQueueAdapterオブジェクト |
:job |
Jobオブジェクト |
| キー |
値 |
:initializer |
config/initializersから読み込まれたイニシャライザへのパス |
| キー |
値 |
:message |
非推奨機能の警告メッセージ |
:callstack |
非推奨警告の発生元 |
イベントは簡単にサブスクライブできます。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となります。
目次