この記事は Pulse 1.11.0 のソースコードを基に作成しています。例の
ReportGenerated イベントは説明用の架空のクラスです。実際のパッケージでは自分のイベントに置き換えてください。処理の流れ
レコーダーはイベントを受け取ると、Pulse のバッファに記録を溜めます。バッファは取り込みのタイミングでまとめて保存されます。レコーダーを作る
レコーダーはlisten プロパティで購読するイベントを指定し、record() メソッドで処理を書きます。ここでは、パッケージが発行する ReportGenerated イベントを記録する例を示します。このイベントは $type と $durationMs を持つものとします。
Ignores と Sampling の各トレイトは、後述する ignore と sample_rate の設定を読み取ります。
アプリでレコーダーを登録する
レコーダーは、アプリのconfig/pulse.php の recorders に登録します。キーにはレコーダーのクラス名を指定し、値で有効化や設定を指定します。
PulseServiceProvider は pulse.enabled が有効なときに pulse.recorders を読み込み、レコーダーを登録します。enabled を false にしたレコーダーは登録されません。パッケージ側でこの設定を自動で書き換える方法は取らず、導入手順として設定例を案内するのが安全です。
集計の種類
Pulse::record() は Entry を返します。count()、min()、max()、sum()、avg() を続けて書くと、対応する集計が pulse_aggregates に保存されます。
min()、max()、sum()、avg() は value を使って計算します。count() だけなら value は不要です。
イベントが大量に発生する場合は、onlyBuckets() を付けると pulse_entries の行数を抑えられます。
文字列の値を保存する
数値の集計ではなく、直近の状態などの文字列を保存したい場合はPulse::set() を使います。値は pulse_values テーブルに保存されます。
value は string 型で渡す必要があります。
重い処理を遅延させる
Pulse::lazy() に渡したクロージャは、その場では実行されず、Pulse が取り込むタイミングで実行されます。記録に時間がかかる処理を、リクエストの応答後に回したい場合に使います。
ユーザーを記録する
認証済みユーザーの識別子が必要な場合はPulse::resolveAuthenticatedUserId() を使います。未認証のときは null が返ります。
除外、サンプリング、フィルター
記録を減らす方法は、次の4つを使い分けます。ignore設定:レコーダーがshouldIgnore()に渡した値が、正規表現の 1 つに一致したときに記録しません。上の例では$event->typeが/^debug_/に一致したときに除外されます。sample_rate設定:shouldSample()が判定し、1は全件、0.1は約 10% の記録を意味します。Pulse::ignore():コールバックの中での記録を無効にし、コールバックの戻り値を返します。Pulse::filter():保存前のEntryまたはValueを受け取り、trueを返したものだけを保存します。
例外の扱い
Pulse は、レコーダーの処理と取り込みをrescue() で囲みます。そのため、レコーダー内の例外はアプリケーションに伝播しません。handleExceptionsUsing() を設定していない場合、例外は何もせず捨てられます。例外を報告したい場合は、アプリ側で設定します。
テスト
レコーダーのテストでは、イベントを発行してからPulse::ingest() を呼び、保存された行を確認する方法が考えられます。次の例は Pulse のソースから導いた想定で、実際のテストでは未検証です。テスト環境で pulse.enabled が有効になっていることを確認してください。
キーの設計
key は集計の単位になります。ユーザー ID や URL のように値が無数に増える情報をそのまま使うと、データ量が増えて集計が読みにくくなります。key には、イベントの種類や処理名のように数が限られた値を使ってください。