メインコンテンツまでスキップ

Laravel Pulse

はじめに​

Laravel Pulse は、アプリケーションのパフォーマンスや使用状況に関する一目でわかる洞察を提供します。Pulseを使用すると、遅いジョブやエンドポイントなどのボトルネックを特定したり、最もアクティブなユーザーを見つけたりすることができます。

個々のイベントの詳細なデバッグには、Laravel Telescope をご覧ください。

インストール​

警告

Pulseの第一パーティのストレージ実装は現在、MySQL、MariaDB、またはPostgreSQLデータベースが必要です。異なるデータベースエンジンを使用している場合は、Pulseデータ用に別個のMySQL、MariaDB、またはPostgreSQLデータベースが必要です。

Composerパッケージマネージャを使用してPulseをインストールできます：

composer require laravel/pulse

次に、vendor:publish Artisanコマンドを使用してPulseの設定とマイグレーションファイルを公開する必要があります：

php artisan vendor:publish --provider="Laravel\Pulse\PulseServiceProvider"

最後に、Pulseのデータを保存するために必要なテーブルを作成するためにmigrateコマンドを実行する必要があります：

php artisan migrate

Pulseのデータベースマイグレーションが完了したら、/pulse ルート経由でPulseダッシュボードにアクセスできます。

注記

アプリケーションの主要データベースにPulseデータを保存したくない場合は、専用のデータベース接続を指定 することができます。

設定​

Pulseの多くの設定オプションは環境変数を使用して制御できます。利用可能なオプションを確認したり、新しいレコーダーを登録したり、高度なオプションを構成したりするには、config/pulse.php 設定ファイルを公開する必要があります：

php artisan vendor:publish --tag=pulse-config

ダッシュボード​

認証​

Pulseダッシュボードは /pulse ルート経由でアクセスできます。デフォルトでは、このダッシュボードには local 環境でのみアクセスできますので、本番環境での認証を構成するには、'viewPulse' 認証ゲートをカスタマイズする必要があります。これは、アプリケーションの app/Providers/AppServiceProvider.php ファイル内で行うことができます：

use App\Models\User;
use Illuminate\Support\Facades\Gate;

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Gate::define('viewPulse', function (User $user) {
        return $user->isAdmin();
    });

    // ...
}

カスタマイズ​

Pulseダッシュボードのカードとレイアウトは、ダッシュボードビューを公開することで構成できます。ダッシュボードビューは resources/views/vendor/pulse/dashboard.blade.php に公開されます：

php artisan vendor:publish --tag=pulse-dashboard

ダッシュボードは Livewire で動作し、JavaScriptアセットを再構築する必要なく、カードとレイアウトをカスタマイズできます。

このファイルでは、<x-pulse> コンポーネントがダッシュボードをレンダリングし、カードのためのグリッドレイアウトを提供します。ダッシュボードを画面全体に広げたい場合は、コンポーネントに full-width プロパティを指定できます：

<x-pulse full-width>
    ...
</x-pulse>

デフォルトでは、<x-pulse> コンポーネントは12列のグリッドを作成しますが、cols プロパティを使用してこれをカスタマイズできます：

<x-pulse cols="16">
    ...
</x-pulse>

各カードは、スペースと配置を制御するための cols および rows プロパティを受け入れます：

<livewire:pulse.usage cols="4" rows="2" />

ほとんどのカードは、スクロールせずにフルカードを表示するための expand プロパティも受け入れます：

<livewire:pulse.slow-queries expand />

ユーザーの解決​

ユーザーに関する情報を表示するカード（例：アプリケーション使用状況カード）では、PulseはユーザーのIDのみを記録します。ダッシュボードをレンダリングする際、Pulseはデフォルトの Authenticatable モデルから name と email フィールドを解決し、Gravatarウェブサービスを使用してアバターを表示します。

アプリケーションの App\Providers\AppServiceProvider クラス内で Pulse::user メソッドを呼び出すことで、フィールドやアバターをカスタマイズすることができます。

user メソッドは、name、extra、avatar 情報を含む配列を返すべき Authenticatable モデルを受け取るクロージャを受け入れます:

use Laravel\Pulse\Facades\Pulse;

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Pulse::user(fn ($user) => [
        'name' => $user->name,
        'extra' => $user->email,
        'avatar' => $user->avatar_url,
    ]);

    // ...
}
注記

認証されたユーザーの取得方法を完全にカスタマイズするには、Laravel\Pulse\Contracts\ResolvesUsers コントラクトを実装し、Laravel の サービスコンテナ にバインドしてください。

カード​

サーバー​

<livewire:pulse.servers /> カードは、pulse:check コマンドを実行しているすべてのサーバーのシステムリソース使用状況を表示します。システムリソースのレポートに関する詳細は、servers recorder のドキュメントを参照してください。

インフラストラクチャ内のサーバーを置き換える場合、非アクティブなサーバーを一定期間後に Pulse ダッシュボードから削除したい場合があります。これは、ignore-after プロパティを使用して行うことができます。このプロパティは、非アクティブなサーバーを Pulse ダッシュボードから削除する秒数を受け入れます。または、1 hour や 3 days and 1 hour などの相対時間形式の文字列を指定することもできます:

<livewire:pulse.servers ignore-after="3 hours" />

アプリケーションの使用状況​

<livewire:pulse.usage /> カードは、アプリケーションにリクエストを送信し、ジョブをディスパッチし、遅いリクエストを経験している上位 10 ユーザーを表示します。

画面上ですべての使用状況メトリクスを表示したい場合は、カードを複数回含め、type 属性を指定することができます:

<livewire:pulse.usage type="requests" />
<livewire:pulse.usage type="slow_requests" />
<livewire:pulse.usage type="jobs" />

Pulse がユーザー情報を取得して表示する方法をカスタマイズする方法について学ぶには、ユーザーの解決 のドキュメントを参照してください。

注記

アプリケーションが多くのリクエストを受信したり、多くのジョブをディスパッチする場合は、サンプリング を有効にすることを検討してください。詳細については、user requests recorder、user jobs recorder、slow jobs recorder のドキュメントを参照してください。

例外 ​

<livewire:pulse.exceptions /> カードは、アプリケーションで発生している例外の頻度と最近の状況を表示します。デフォルトでは、例外は例外クラスと発生した場所に基づいてグループ化されます。詳細については、例外レコーダー のドキュメントを参照してください。

キュー ​

<livewire:pulse.queues /> カードは、アプリケーションのキューのスループットを表示します。これには、キューに入れられたジョブの数、処理中のジョブ、処理されたジョブ、リリースされたジョブ、失敗したジョブが含まれます。詳細については、キューレコーダー のドキュメントを参照してください。

遅いリクエスト ​

<livewire:pulse.slow-requests /> カードは、設定された閾値を超えるアプリケーションへの着信リクエストを表示します。デフォルトでは、閾値は 1,000ms です。詳細については、遅いリクエストレコーダー のドキュメントを参照してください。

遅いジョブ ​

<livewire:pulse.slow-jobs /> カードは、設定された閾値を超えるアプリケーション内のジョブを表示します。デフォルトでは、閾値は 1,000ms です。詳細については、遅いジョブレコーダー のドキュメントを参照してください。

遅いクエリ ​

<livewire:pulse.slow-queries /> カードは、設定された閾値を超えるアプリケーション内のデータベースクエリを表示します。デフォルトでは、閾値は 1,000ms です。

デフォルトでは、遅いクエリは SQL クエリ（バインディングなし）と発生した場所に基づいてグループ化されますが、SQL クエリのみをグループ化する場合は、場所をキャプチャしないように選択することができます。

非常に大きな SQL クエリによるレンダリングパフォーマンスの問題が発生した場合は、without-highlighting プロパティを追加してハイライトを無効にすることができます：

<livewire:pulse.slow-queries without-highlighting />

詳細については、遅いクエリレコーダー のドキュメントを参照してください。

遅い送信リクエスト ​

<livewire:pulse.slow-outgoing-requests /> カードは、デフォルトで 1,000ms を超える Laravel の HTTP クライアント を使用して行われた送信リクエストを表示します。

デフォルトでは、エントリは完全なURLでグループ化されます。ただし、正規表現を使用して出力リクエストを正規化またはグループ化することができます。詳細については、遅い出力リクエストレコーダーのドキュメントを参照してください。

キャッシュ​

<livewire:pulse.cache /> カードは、アプリケーションのキャッシュヒットとミスの統計を表示します。グローバルおよび個々のキーに対して。

デフォルトでは、エントリはキーでグループ化されます。ただし、類似のキーを正規表現を使用して正規化またはグループ化することができます。詳細については、キャッシュインタラクションレコーダーのドキュメントを参照してください。

エントリのキャプチャ​

ほとんどのPulseレコーダーは、Laravelによってディスパッチされるフレームワークイベントに基づいてエントリを自動的にキャプチャします。ただし、サーバーレコーダーや一部のサードパーティーカードは定期的に情報をポーリングする必要があります。これらのカードを使用するには、すべての個々のアプリケーションサーバーで pulse:check デーモンを実行する必要があります：

php artisan pulse:check
注記

pulse:check プロセスをバックグラウンドで永続的に実行するためには、コマンドが停止しないようにするために Supervisor などのプロセスモニターを使用する必要があります。

pulse:check コマンドは長寿命のプロセスであるため、コードベースの変更を再起動せずに見逃すことはできません。アプリケーションの展開プロセス中に pulse:restart コマンドを呼び出すことで、コマンドを優雅に再起動する必要があります：

php artisan pulse:restart
注記

Pulse は再起動シグナルを保存するために cache を使用するため、この機能を使用する前にアプリケーションに適切に構成されたキャッシュドライバがあることを確認する必要があります。

レコーダー​

レコーダーは、アプリケーションからエントリをキャプチャして Pulse データベースに記録する責任があります。レコーダーは、Pulse構成ファイルの recorders セクションに登録および構成されます。

キャッシュインタラクション​

CacheInteractions レコーダーは、アプリケーション内で発生する cache ヒットとミスに関する情報を収集し、Cache カードに表示します。

サンプリング および無視されるキーパターンを任意で調整できます。

また、類似したキーを単一のエントリとしてグループ化するようにキーグルーピングを構成することもできます。たとえば、同じタイプの情報をキャッシュするキーから一意の ID を削除したい場合があります。グループは、キーの一部を "検索して置換" するための正規表現を使用して構成されます。構成ファイルには例が含まれています:

Recorders\CacheInteractions::class => [
    // ...
    'groups' => [
        // '/:\d+/' => ':*',
    ],
],

最初に一致するパターンが使用されます。パターンが一致しない場合、キーはそのままキャプチャされます。

例外​

Exceptions レコーダーは、アプリケーション内で発生する報告可能な例外に関する情報を収集し、Exceptions カードに表示します。

サンプリング および無視される例外パターンを任意で調整できます。また、例外の発生元をキャプチャするかどうかを構成することもできます。キャプチャされた場所は Pulse ダッシュボードに表示され、例外の発生元を特定するのに役立ちます。ただし、同じ例外が複数の場所で発生する場合は、ユニークな場所ごとに複数回表示されます。

キュー​

Queues レコーダーは、アプリケーションのキューに関する情報を収集し、Queues カードに表示します。

サンプリング および無視されるジョブパターンを任意で調整できます。

遅いジョブ​

SlowJobs レコーダーは、アプリケーション内で発生する遅いジョブに関する情報を収集し、Slow Jobs カードに表示します。

遅いジョブのしきい値、サンプリング、および無視されるジョブパターンを任意で調整できます。

他のジョブよりも時間がかかると予想されるジョブがいくつかあるかもしれません。その場合、ジョブごとにしきい値を構成できます:

Recorders\SlowJobs::class => [
    // ...
    'threshold' => [
        '#^App\\Jobs\\GenerateYearlyReports$#' => 5000,
        'default' => env('PULSE_SLOW_JOBS_THRESHOLD', 1000),
    ],
],

もしジョブのクラス名に一致する正規表現パターンがない場合、'default' 値が使用されます。

遅い送信リクエスト​

SlowOutgoingRequests レコーダーは、LaravelのHTTPクライアントを使用して行われた設定された閾値を超える出力HTTPリクエストに関する情報を収集し、遅い送信リクエスト カードに表示します。

遅い送信リクエストの閾値、サンプル率、無視されるURLパターンを任意で調整できます。

他のリクエストよりも時間がかかると予想される送信リクエストがいくつかあるかもしれません。その場合、リクエストごとの閾値を設定できます:

Recorders\SlowOutgoingRequests::class => [
    // ...
    'threshold' => [
        '#backup.zip$#' => 5000,
        'default' => env('PULSE_SLOW_OUTGOING_REQUESTS_THRESHOLD', 1000),
    ],
],

もしリクエストのURLに一致する正規表現パターンがない場合、'default' 値が使用されます。

同様のURLが1つのエントリとしてグループ化されるようにURLグループ化を構成することもできます。たとえば、URLパスから一意のIDを削除したり、ドメインのみでグループ化したりすることができます。グループは、URLの一部を「検索して置換」するための正規表現を使用して構成されます。いくつかの例が構成ファイルに含まれています:

Recorders\SlowOutgoingRequests::class => [
    // ...
    'groups' => [
        // '#^https://api\.github\.com/repos/.*$#' => 'api.github.com/repos/*',
        // '#^https?://([^/]*).*$#' => '\1',
        // '#/\d+#' => '/*',
    ],
],

一致する最初のパターンが使用されます。パターンが一致しない場合、URLはそのままキャプチャされます。

遅いクエリ​

SlowQueries レコーダーは、設定された閾値を超えるアプリケーション内のデータベースクエリを収集し、遅いクエリ カードに表示します。

遅いクエリの閾値、サンプル率、無視されるクエリパターンを任意で調整できます。また、クエリの場所をキャプチャするかどうかを構成することもできます。キャプチャされた場所はPulseダッシュボードに表示され、クエリの起源を特定するのに役立ちます。ただし、同じクエリが複数の場所で実行される場合、ユニークな場所ごとに複数回表示されます。

Recorders\SlowQueries::class => [
    // ...
    'threshold' => [
        '#^insert into `yearly_reports`#' => 5000,
        'default' => env('PULSE_SLOW_QUERIES_THRESHOLD', 1000),
    ],
],

クエリのSQLに一致する正規表現パターンがない場合、'default' 値が使用されます。

遅いリクエスト​

Requests レコーダーは、アプリケーションに対して行われたリクエストに関する情報を収集し、遅いリクエスト および アプリケーションの使用状況 カードに表示します。

遅いルートの閾値、サンプル率、および無視されるパスをオプションで調整できます。

一部のリクエストは他よりも時間がかかると予想される場合があります。その場合、リクエストごとの閾値を設定できます:

Recorders\SlowRequests::class => [
    // ...
    'threshold' => [
        '#^/admin/#' => 5000,
        'default' => env('PULSE_SLOW_REQUESTS_THRESHOLD', 1000),
    ],
],

リクエストのURLに一致する正規表現パターンがない場合、'default' 値が使用されます。

サーバー​

Servers レコーダーは、アプリケーションを動かすサーバーのCPU、メモリ、およびストレージ使用状況に関する情報を収集し、サーバー カードに表示します。このレコーダーには、モニタリングしたい各サーバーで pulse:check コマンド を実行する必要があります。

各報告サーバーには固有の名前が必要です。デフォルトでは、Pulse は PHP の gethostname 関数が返す値を使用します。これをカスタマイズしたい場合は、PULSE_SERVER_NAME 環境変数を設定できます:

PULSE_SERVER_NAME=load-balancer

Pulse の設定ファイルでは、監視されるディレクトリをカスタマイズすることもできます。

ユーザージョブ​

UserJobs レコーダーは、アプリケーションでジョブをディスパッチするユーザーに関する情報を収集し、アプリケーションの使用状況 カードに表示します。

サンプル率 および無視されるジョブパターンをオプションで調整できます。

ユーザーリクエスト​

UserRequests レコーダーは、アプリケーションにリクエストを行うユーザーに関する情報を収集し、アプリケーションの使用状況 カードに表示します。

サンプル率 および無視されるジョブパターンをオプションで調整できます。

フィルタリング​

私たちが見てきたように、多くのレコーダーは、設定を介して、リクエストのURLなどの値に基づいて着信エントリを「無視」する機能を提供しています。しかし、認証されたユーザに基づいてレコードをフィルタリングすることが役立つ場合もあります。これらのレコードをフィルタリングするには、Pulseのfilterメソッドにクロージャを渡すことができます。通常、filterメソッドは、アプリケーションのAppServiceProviderのbootメソッド内で呼び出すべきです：

use Illuminate\Support\Facades\Auth;
use Laravel\Pulse\Entry;
use Laravel\Pulse\Facades\Pulse;
use Laravel\Pulse\Value;

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Pulse::filter(function (Entry|Value $entry) {
        return Auth::user()->isNotAdmin();
    });

    // ...
}

パフォーマンス​

Pulseは、追加のインフラストラクチャを必要とせずに既存のアプリケーションに組み込むよう設計されています。ただし、高トラフィックのアプリケーションでは、Pulseがアプリケーションのパフォーマンスに与える影響を取り除く方法がいくつかあります。

別のデータベースを使用する​

高トラフィックのアプリケーションでは、Pulse用に専用のデータベース接続を使用して、アプリケーションのデータベースに影響を与えないようにすることができます。

Pulseが使用するデータベース接続をカスタマイズするには、PULSE_DB_CONNECTION環境変数を設定します。

PULSE_DB_CONNECTION=pulse

Redis Ingest​

警告

Redis IngestにはRedis 6.2以上と、アプリケーションの構成されたRedisクライアントドライバとしてphpredisまたはpredisが必要です。

デフォルトでは、PulseはHTTPレスポンスがクライアントに送信された後、またはジョブが処理された後にエントリを直接構成されたデータベース接続に保存します。ただし、PulseのRedis Ingestドライバを使用して、エントリをRedisストリームに送信することもできます。これは、PULSE_INGEST_DRIVER環境変数を設定することで有効にできます：

PULSE_INGEST_DRIVER=redis

PulseはデフォルトであなたのデフォルトのRedis接続を使用しますが、PULSE_REDIS_CONNECTION環境変数を介してこれをカスタマイズすることができます：

PULSE_REDIS_CONNECTION=pulse

Redis Ingestを使用する場合は、pulse:workコマンドを実行してストリームを監視し、RedisからエントリをPulseのデータベーステーブルに移動する必要があります。

php artisan pulse:work
注記

pulse:workプロセスを常にバックグラウンドで実行するためには、Pulseワーカーが停止しないようにするためにSupervisorなどのプロセス監視ツールを使用する必要があります。

pulse:workコマンドは長時間実行されるプロセスであるため、コードベースの変更を反映させるには再起動する必要があります。アプリケーションのデプロイプロセス中にpulse:restartコマンドを呼び出すことで、コマンドを優雅に再起動する必要があります。

php artisan pulse:restart
注記

Pulseはcacheを使用して再起動シグナルを保存するため、この機能を使用する前にアプリケーションに適切に構成されたキャッシュドライバがあることを確認する必要があります。

サンプリング​

デフォルトでは、Pulseはアプリケーションで発生するすべての関連イベントをキャプチャします。高トラフィックのアプリケーションでは、特に長い時間帯には、ダッシュボードで数百万のデータベース行を集計する必要があります。

代わりに、特定のPulseデータレコーダーで「サンプリング」を有効にすることができます。たとえば、User Requestsレコーダーのサンプルレートを0.1に設定すると、アプリケーションへのリクエストの約10%のみが記録されます。ダッシュボードでは、値がスケーリングされ、~で接頭辞が付けられ、それが近似値であることを示します。

一般的に、特定のメトリクスに対してエントリが多いほど、サンプルレートを安全に低く設定できますが、精度をあまり犠牲にすることなく。

トリミング​

Pulseは、ダッシュボードウィンドウの外にあるエントリが自動的にトリムされます。トリミングは、Pulseの構成ファイルでカスタマイズ可能な抽選システムを使用してデータを取り込む際に発生します。

Pulse例外の処理​

Pulseデータのキャプチャ中に接続できないなどの例外が発生した場合、Pulseはアプリケーションに影響を与えないように静かに失敗します。

これらの例外の処理方法をカスタマイズしたい場合は、handleExceptionsUsingメソッドにクロージャを提供することができます。

use Laravel\Pulse\Facades\Pulse;
use Illuminate\Support\Facades\Log;

Pulse::handleExceptionsUsing(function ($e) {
    Log::debug('An exception happened in Pulse', [
        'message' => $e->getMessage(),
        'stack' => $e->getTraceAsString(),
    ]);
});

カスタムカード​

Pulseでは、アプリケーション固有のニーズに関連するデータを表示するためのカスタムカードを作成できます。PulseはLivewireを使用しているため、最初のカスタムカードを作成する前にLivewireのドキュメントを確認することがお勧めです。

カードコンポーネント​

Laravel Pulseでカスタムカードを作成するには、基本となるCard Livewireコンポーネントを拡張し、対応するビューを定義することから始めます:

namespace App\Livewire\Pulse;

use Laravel\Pulse\Livewire\Card;
use Livewire\Attributes\Lazy;

#[Lazy]
class TopSellers extends Card
{
    public function render()
    {
        return view('livewire.pulse.top-sellers');
    }
}

Livewireの遅延読み込み機能を使用する場合、Cardコンポーネントは、コンポーネントに渡されたcolsおよびrows属性を尊重するプレースホルダを自動的に提供します。

Pulseカードの対応するビューを作成する際には、一貫した外観と感触を提供するためにPulseのBladeコンポーネントを活用することができます:

<x-pulse::card :cols="$cols" :rows="$rows" :class="$class" wire:poll.5s="">
    <x-pulse::card-header name="Top Sellers">
        <x-slot:icon>
            ...
        </x-slot:icon>
    </x-pulse::card-header>

    <x-pulse::scroll :expand="$expand">
        ...
    </x-pulse::scroll>
</x-pulse::card>

$cols、$rows、$class、$expand変数は、それぞれのBladeコンポーネントに渡されるべきであり、ダッシュボードビューからカードのレイアウトをカスタマイズできます。また、カードが自動的に更新されるようにするには、ビューにwire:poll.5s=""属性を含めることもできます。

Livewireコンポーネントとテンプレートを定義したら、カードをダッシュボードビューに含めることができます:

<x-pulse>
    ...

    <livewire:pulse.top-sellers cols="4" />
</x-pulse>
注記

カードがパッケージに含まれている場合、Livewire::componentメソッドを使用してLivewireにコンポーネントを登録する必要があります。

スタイリング​

Pulseに含まれているクラスやコンポーネント以外に、カードに追加のスタイリングが必要な場合、カスタムCSSを含めるためのいくつかのオプションがあります。

Laravel Vite 統合​

カスタムカードがアプリケーションのコードベース内にあり、LaravelのVite統合を使用している場合、vite.config.jsファイルを更新して、カード用の専用CSSエントリーポイントを含めることができます。

laravel({
    input: [
        'resources/css/pulse/top-sellers.css',
        // ...
    ],
}),

ダッシュボードビューで@viteブレードディレクティブを使用して、カードのCSSエントリーポイントを指定できます：

<x-pulse>
    @vite('resources/css/pulse/top-sellers.css')

    ...
</x-pulse>

CSSファイル​

パッケージ内に含まれるパルスカードを含む他のユースケースでは、Livewireコンポーネントにcssメソッドを定義して、CSSファイルへのファイルパスを返すように指示することで、パルスに追加のスタイルシートを読み込むようにできます：

class TopSellers extends Card
{
    // ...

    protected function css()
    {
        return __DIR__.'/../../dist/top-sellers.css';
    }
}

このカードがダッシュボードに含まれている場合、パルスはこのファイルの内容を<style>タグ内に自動的に含めるため、publicディレクトリに公開する必要はありません。

Tailwind CSS​

Tailwind CSSを使用する場合、PulseのTailwindクラスとの競合を避けるために、専用のTailwind構成ファイルを作成する必要があります：

export default {
    darkMode: 'class',
    important: '#top-sellers',
    content: [
        './resources/views/livewire/pulse/top-sellers.blade.php',
    ],
    corePlugins: {
        preflight: false,
    },
};

CSSエントリーポイントで構成ファイルを指定できます：

@config "../../tailwind.top-sellers.config.js";
@tailwind base;
@tailwind components;
@tailwind utilities;

Tailwindのimportantセレクタ戦略に渡されるセレクタと一致するidまたはclass属性をカードのビューに含める必要があります：

<x-pulse::card id="top-sellers" :cols="$cols" :rows="$rows" class="$class">
    ...
</x-pulse::card>

データの取得と集約​

カスタムカードはどこからでもデータを取得して表示できますが、パルスの強力で効率的なデータ記録および集約システムを活用することができます。

エントリの取得​

Pulse::recordメソッドを使用して"エントリ"を記録することができます：

use Laravel\Pulse\Facades\Pulse;

Pulse::record('user_sale', $user->id, $sale->amount)
    ->sum()
    ->count();

recordメソッドに提供される最初の引数は、記録しているエントリのtypeであり、2番目の引数は集約されたデータがどのようにグループ化されるかを決定するkeyです。ほとんどの集約メソッドでは、集約するvalueも指定する必要があります。上記の例では、集約される値は$sale->amountです。その後、sumなどの1つ以上の集約メソッドを呼び出すことで、パルスが事前に集約された値を後で効率的に取得できるようになります。

利用可能な集計方法は次のとおりです：

  • avg
  • count
  • max
  • min
  • sum
注記

認証されたユーザーIDをキャプチャするカードパッケージを構築する際は、アプリケーションに行われたユーザーリゾルバのカスタマイズを尊重する Pulse::resolveAuthenticatedUserId() メソッドを使用する必要があります。

集計データの取得​

Pulseの Card Livewireコンポーネントを拡張する際に、ダッシュボードで表示されている期間の集計データを取得するために aggregate メソッドを使用できます：

class TopSellers extends Card
{
    public function render()
    {
        return view('livewire.pulse.top-sellers', [
            'topSellers' => $this->aggregate('user_sale', ['sum', 'count']);
        ]);
    }
}

aggregate メソッドは PHP の stdClass オブジェクトのコレクションを返します。各オブジェクトには、以前にキャプチャされた key プロパティと、リクエストされた各集計のキーが含まれます：

@foreach ($topSellers as $seller)
    {{ $seller->key }}
    {{ $seller->sum }}
    {{ $seller->count }}
@endforeach

Pulseは主に事前に集計されたバケツからデータを取得します。したがって、指定された集計は、Pulse::record メソッドを使用して事前にキャプチャする必要があります。最も古いバケツは通常期間の一部外にあるため、Pulseは最も古いエントリを集計してギャップを埋め、各ポーリングリクエストで期間全体を集計する必要がなく、正確な値を提供します。

aggregateTotal メソッドを使用して、特定のタイプの合計値を取得することもできます。たとえば、次のメソッドは、ユーザーごとにグループ化する代わりに、すべてのユーザーの売上合計を取得します。

$total = $this->aggregateTotal('user_sale', 'sum');

ユーザーの表示​

キーとしてユーザーIDを記録する集計を扱う際に、Pulse::resolveUsers メソッドを使用してキーをユーザーレコードに解決できます：

$aggregates = $this->aggregate('user_sale', ['sum', 'count']);

$users = Pulse::resolveUsers($aggregates->pluck('key'));

return view('livewire.pulse.top-sellers', [
    'sellers' => $aggregates->map(fn ($aggregate) => (object) [
        'user' => $users->find($aggregate->key),
        'sum' => $aggregate->sum,
        'count' => $aggregate->count,
    ])
]);

find メソッドは、name、extra、avatar キーを含むオブジェクトを返し、これらを直接 <x-pulse::user-card> Bladeコンポーネントに渡すことができます：

<x-pulse::user-card :user="{{ $seller->user }}" :stats="{{ $seller->sum }}" />

カスタムレコーダー​

パッケージの作者は、ユーザーがデータのキャプチャを設定できるようにするために、レコーダークラスを提供することができます。

アプリケーションのconfig/pulse.php設定ファイルのrecordersセクションにレコーダーが登録されます：

[
    // ...
    'recorders' => [
        Acme\Recorders\Deployments::class => [
            // ...
        ],

        // ...
    ],
]

レコーダーは$listenプロパティを指定することでイベントをリッスンすることができます。Pulseは自動的にリスナーを登録し、レコーダーのrecordメソッドを呼び出します：

<?php

namespace Acme\Recorders;

use Acme\Events\Deployment;
use Illuminate\Support\Facades\Config;
use Laravel\Pulse\Facades\Pulse;

class Deployments
{
    /**
     * The events to listen for.
     *
     * @var array<int, class-string>
     */
    public array $listen = [
        Deployment::class,
    ];

    /**
     * Record the deployment.
     */
    public function record(Deployment $event): void
    {
        $config = Config::get('pulse.recorders.'.static::class);

        Pulse::record(
            // ...
        );
    }
}