> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# パッケージのカスタムPulseレコーダー

> Laravel Pulseのレコーダーを使い、パッケージ独自のイベントをダッシュボードに集計する方法を解説します。listenでのイベント購読、Pulse::recordによる集計、ignoreとsample_rateの設定、例外の扱いを説明します。

Laravel Pulse は、リクエスト、クエリ、ジョブなどをダッシュボードに集計します。パッケージが独自の処理を行う場合は、カスタムレコーダーを用意すると、その処理の件数や所要時間を Pulse で監視できます。

この記事では、パッケージが発行するイベントを購読して件数と処理時間を記録するレコーダーを作ります。Pulse の基本的な使い方は [Pulse](https://kawax.biz/jp/pulse.md) を参照してください。

> [!NOTE]
>
> この記事は Pulse 1.11.0 のソースコードを基に作成しています。例の `ReportGenerated` イベントは説明用の架空のクラスです。実際のパッケージでは自分のイベントに置き換えてください。

## 処理の流れ

レコーダーはイベントを受け取ると、Pulse のバッファに記録を溜めます。バッファは取り込みのタイミングでまとめて保存されます。

```mermaid theme={null}
flowchart LR
    A["イベント発火"] --> B["listenで<br>recordを呼び出す"]
    B --> C["Pulse::recordで<br>Entryを作成"]
    C --> D["Pulseのバッファ"]
    D --> E["ingestで保存"]
    E --> F["pulse_entries"]
    E --> G["pulse_aggregates"]
    F --> H["ダッシュボードで表示"]
    G --> H
```

## レコーダーを作る

レコーダーは `listen` プロパティで購読するイベントを指定し、`record()` メソッドで処理を書きます。ここでは、パッケージが発行する `ReportGenerated` イベントを記録する例を示します。このイベントは `$type` と `$durationMs` を持つものとします。

```php theme={null}
<?php

namespace Acme\Reports\Pulse;

use Acme\Reports\Events\ReportGenerated;
use Laravel\Pulse\Facades\Pulse;
use Laravel\Pulse\Recorders\Concerns\Ignores;
use Laravel\Pulse\Recorders\Concerns\Sampling;

class ReportGenerationRecorder
{
    use Ignores, Sampling;

    public array $listen = [
        ReportGenerated::class,
    ];

    public function record(ReportGenerated $event): void
    {
        if ($this->shouldIgnore($event->type) || ! $this->shouldSample()) {
            return;
        }

        Pulse::record(
            type: 'report_generation',
            key: $event->type,
            value: $event->durationMs,
        )->count()->avg()->max();
    }
}
```

`Ignores` と `Sampling` の各トレイトは、後述する `ignore` と `sample_rate` の設定を読み取ります。

## アプリでレコーダーを登録する

レコーダーは、アプリの `config/pulse.php` の `recorders` に登録します。キーにはレコーダーのクラス名を指定し、値で有効化や設定を指定します。

```php theme={null}
'recorders' => [
    // 既存のレコーダーはそのまま残します
    Acme\Reports\Pulse\ReportGenerationRecorder::class => [
        'enabled' => true,
        'sample_rate' => 1,
        'ignore' => ['/^debug_/'],
    ],
],
```

`PulseServiceProvider` は `pulse.enabled` が有効なときに `pulse.recorders` を読み込み、レコーダーを登録します。`enabled` を `false` にしたレコーダーは登録されません。パッケージ側でこの設定を自動で書き換える方法は取らず、導入手順として設定例を案内するのが安全です。

## 集計の種類

`Pulse::record()` は `Entry` を返します。`count()`、`min()`、`max()`、`sum()`、`avg()` を続けて書くと、対応する集計が `pulse_aggregates` に保存されます。

| メソッド | 保存する内容 |
| - | - |
| `count()` | 件数 |
| `min()` | 最小値 |
| `max()` | 最大値 |
| `sum()` | 合計 |
| `avg()` | 平均 |
| `onlyBuckets()` | `pulse_entries` に個別の記録を保存せず、集計の結果だけを保存 |

`min()`、`max()`、`sum()`、`avg()` は `value` を使って計算します。`count()` だけなら `value` は不要です。

イベントが大量に発生する場合は、`onlyBuckets()` を付けると `pulse_entries` の行数を抑えられます。

## 文字列の値を保存する

数値の集計ではなく、直近の状態などの文字列を保存したい場合は `Pulse::set()` を使います。値は `pulse_values` テーブルに保存されます。

```php theme={null}
use Laravel\Pulse\Facades\Pulse;

Pulse::set('report_status', $event->type, $event->status);
```

`value` は `string` 型で渡す必要があります。

## 重い処理を遅延させる

`Pulse::lazy()` に渡したクロージャは、その場では実行されず、Pulse が取り込むタイミングで実行されます。記録に時間がかかる処理を、リクエストの応答後に回したい場合に使います。

```php theme={null}
Pulse::lazy(function () use ($event) {
    Pulse::record('report_size', $event->type, $event->rows)->sum();
});
```

## ユーザーを記録する

認証済みユーザーの識別子が必要な場合は `Pulse::resolveAuthenticatedUserId()` を使います。未認証のときは `null` が返ります。

```php theme={null}
$userId = Pulse::resolveAuthenticatedUserId();
```

## 除外、サンプリング、フィルター

記録を減らす方法は、次の4つを使い分けます。

* `ignore` 設定：レコーダーが `shouldIgnore()` に渡した値が、正規表現の 1 つに一致したときに記録しません。上の例では `$event->type` が `/^debug_/` に一致したときに除外されます。
* `sample_rate` 設定：`shouldSample()` が判定し、`1` は全件、`0.1` は約 10% の記録を意味します。
* `Pulse::ignore()`：コールバックの中での記録を無効にし、コールバックの戻り値を返します。
* `Pulse::filter()`：保存前の `Entry` または `Value` を受け取り、`true` を返したものだけを保存します。

## 例外の扱い

Pulse は、レコーダーの処理と取り込みを `rescue()` で囲みます。そのため、レコーダー内の例外はアプリケーションに伝播しません。`handleExceptionsUsing()` を設定していない場合、例外は何もせず捨てられます。例外を報告したい場合は、アプリ側で設定します。

```php theme={null}
use Laravel\Pulse\Facades\Pulse;

Pulse::handleExceptionsUsing(fn (Throwable $e) => report($e));
```

## テスト

レコーダーのテストでは、イベントを発行してから `Pulse::ingest()` を呼び、保存された行を確認する方法が考えられます。次の例は Pulse のソースから導いた想定で、実際のテストでは未検証です。テスト環境で `pulse.enabled` が有効になっていることを確認してください。

```php theme={null}
use Acme\Reports\Events\ReportGenerated;
use Laravel\Pulse\Facades\Pulse;

it('ReportGeneratedをpulse_entriesに記録する', function () {
    event(new ReportGenerated(type: 'monthly', durationMs: 120));

    Pulse::ingest();

    $this->assertDatabaseHas('pulse_entries', [
        'type' => 'report_generation',
        'key' => 'monthly',
        'value' => 120,
    ]);
});
```

## キーの設計

`key` は集計の単位になります。ユーザー ID や URL のように値が無数に増える情報をそのまま使うと、データ量が増えて集計が読みにくくなります。`key` には、イベントの種類や処理名のように数が限られた値を使ってください。


## Related topics

- [応用トピック](https://kawax.biz/jp/advanced/index.md)
- [パッケージのカスタムUserProvider](https://kawax.biz/jp/advanced/package-user-providers.md)
- [パッケージのカスタムキャッシュストアと契約](https://kawax.biz/jp/advanced/package-cache-drivers.md)
- [パッケージのカスタムセッションドライバー](https://kawax.biz/jp/advanced/package-session-drivers.md)
- [パッケージのカスタム通知チャネルと配信検証](https://kawax.biz/jp/advanced/package-notification-channels.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.