Laravel Pulse

イントロダクション
インストール
- 設定
ダッシュボード
エントリのキャプチャ
- レコーダ
- フィルタリング
パフォーマンス
カスタムカード

イントロダクション

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

個々のイベントを詳細にデバッグするには、Laravel Telescopeをチェックしてください。

インストール

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

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

1composer require laravel/pulse

composer require laravel/pulse

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

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

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

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

1php artisan migrate

php artisan migrate

Pulseのデータベースマイグレーションを実行すると、/pulseルートを介してPulseダッシュボードにアクセスできます。

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

設定

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

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

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

ダッシュボード

認可

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

 1use App\Models\User;
 2use Illuminate\Support\Facades\Gate;
 3 
 4/**
 5 * Bootstrap any application services.
 6 */
 7public function boot(): void
 8{
 9    Gate::define('viewPulse', function (User $user) {
10        return $user->isAdmin();
11    });
12 
13    // ...
14}

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に公開されます。

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

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

ダッシュボードはLivewireを利用しており、JavaScriptアセットを再ビルドすることなくカードとレイアウトをカスタマイズできます。

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

1<x-pulse full-width>
2    ...
3</x-pulse>

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

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

1<x-pulse cols="16">
2    ...
3</x-pulse>

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

各カードは、スペースと位置を制御するためにcolsとrowsプロパティを受け入れます。

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

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

ほとんどのカードは、スクロールする代わりにカード全体を表示するためのexpandプロパティも受け入れます。

1<livewire:pulse.slow-queries expand />

<livewire:pulse.slow-queries expand />

ユーザーの解決

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

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

userメソッドはクロージャを受け取ります。このクロージャは表示されるAuthenticatableモデルを受け取り、ユーザーのname、extra、avatar情報を含む配列を返す必要があります。

 1use Laravel\Pulse\Facades\Pulse;
 2 
 3/**
 4 * Bootstrap any application services.
 5 */
 6public function boot(): void
 7{
 8    Pulse::user(fn ($user) => [
 9        'name' => $user->name,
10        'extra' => $user->email,
11        'avatar' => $user->avatar_url,
12    ]);
13 
14    // ...
15}

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コマンドを実行しているすべてのサーバーのシステムリソース使用状況を表示します。システムリソースのレポートに関する詳細については、サーバーレコーダのドキュメントを参照してください。

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

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

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

アプリケーション利用状況

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

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

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

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

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

アプリケーションが多くのリクエストを受信したり、多くのジョブをディスパッチしたりする場合は、サンプリングを有効にすることをお勧めします。詳細については、ユーザーリクエストレコーダ、ユーザージョブレコーダ、および遅いジョブレコーダのドキュメントを参照してください。

例外

<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プロパティを追加してハイライトを無効にできます。

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

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

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

遅い外部リクエスト

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

デフォルトでは、エントリは完全なURLによってグループ化されます。ただし、正規表現を使用して類似の外部リクエストを正規化またはグループ化したい場合があります。詳細については、遅い外部リクエストレコーダのドキュメントを参照してください。

キャッシュ

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

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

エントリのキャプチャ

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

1php artisan pulse:check

php artisan pulse:check

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

pulse:checkコマンドは長時間実行されるプロセスであるため、再起動しない限りコードベースの変更は反映されません。アプリケーションのデプロイプロセス中にpulse:restartコマンドを呼び出して、コマンドをグレースフルに再起動する必要があります。

1php artisan pulse:restart

php artisan pulse:restart

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

レコーダ

レコーダは、Pulseデータベースに記録されるアプリケーションからのエントリをキャプチャする役割を担います。レコーダは、Pulse設定ファイルのrecordersセクションで登録および設定されます。

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

CacheInteractionsレコーダは、キャッシュカードに表示するために、アプリケーションで発生するキャッシュのヒットとミスに関する情報をキャプチャします。

オプションで、サンプルレートと無視するキーのパターンを調整できます。

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

1Recorders\CacheInteractions::class => [
2    // ...
3    'groups' => [
4        // '/:\d+/' => ':*',
5    ],
6],

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

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

例外

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

オプションで、サンプルレートと無視する例外のパターンを調整できます。また、例外が発生した場所をキャプチャするかどうかを設定することもできます。キャプチャされた場所はPulseダッシュボードに表示され、例外の発生源を特定するのに役立ちます。ただし、同じ例外が複数の場所で発生した場合、それぞれの一意の場所ごとに複数回表示されます。

キュー

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

オプションで、サンプルレートと無視するジョブのパターンを調整できます。

遅いジョブ

SlowJobsレコーダは、遅いジョブカードに表示するために、アプリケーションで発生する遅いジョブに関する情報をキャプチャします。

オプションで、遅いジョブのしきい値、サンプルレート、および無視するジョブのパターンを調整できます。

他のジョブよりも時間がかかると予想されるジョブがあるかもしれません。そのような場合は、ジョブごとのしきい値を設定できます。

1Recorders\SlowJobs::class => [
2    // ...
3    'threshold' => [
4        '#^App\\Jobs\\GenerateYearlyReports$#' => 5000,
5        'default' => env('PULSE_SLOW_JOBS_THRESHOLD', 1000),
6    ],
7],

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

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

遅い外部リクエスト

SlowOutgoingRequestsレコーダは、HTTPクライアントを使用して行われた、設定されたしきい値を超える外部HTTPリクエストに関する情報を遅い外部リクエストカードに表示するためにキャプチャします。

オプションで、遅い外部リクエストのしきい値、サンプルレート、および無視するURLのパターンを調整できます。

他のリクエストよりも時間がかかると予想される外部リクエストがあるかもしれません。そのような場合は、リクエストごとのしきい値を設定できます。

1Recorders\SlowOutgoingRequests::class => [
2    // ...
3    'threshold' => [
4        '#backup.zip$#' => 5000,
5        'default' => env('PULSE_SLOW_OUTGOING_REQUESTS_THRESHOLD', 1000),
6    ],
7],

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

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

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

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

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

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

遅いクエリ

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

オプションで、遅いクエリのしきい値、サンプルレート、および無視するクエリのパターンを調整できます。また、クエリの場所をキャプチャするかどうかも設定できます。キャプチャされた場所はPulseダッシュボードに表示され、クエリの発生源を特定するのに役立ちます。ただし、同じクエリが複数の場所で行われた場合、それぞれの一意の場所ごとに複数回表示されます。

他のクエリよりも時間がかかると予想されるクエリがあるかもしれません。そのような場合は、クエリごとのしきい値を設定できます。

1Recorders\SlowQueries::class => [
2    // ...
3    'threshold' => [
4        '#^insert into `yearly_reports`#' => 5000,
5        'default' => env('PULSE_SLOW_QUERIES_THRESHOLD', 1000),
6    ],
7],

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

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

遅いリクエスト

Requestsレコーダは、遅いリクエストカードおよびアプリケーション利用状況カードに表示するために、アプリケーションへのリクエストに関する情報をキャプチャします。

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

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

1Recorders\SlowRequests::class => [
2    // ...
3    'threshold' => [
4        '#^/admin/#' => 5000,
5        'default' => env('PULSE_SLOW_REQUESTS_THRESHOLD', 1000),
6    ],
7],

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環境変数を設定できます。

1PULSE_SERVER_NAME=load-balancer

PULSE_SERVER_NAME=load-balancer

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

ユーザージョブ

UserJobsレコーダは、アプリケーション利用状況カードに表示するために、アプリケーションでジョブをディスパッチしているユーザーに関する情報をキャプチャします。

オプションで、サンプルレートと無視するジョブのパターンを調整できます。

ユーザーリクエスト

UserRequestsレコーダは、アプリケーション利用状況カードに表示するために、アプリケーションにリクエストを行っているユーザーに関する情報をキャプチャします。

オプションで、サンプルレートと無視するURLのパターンを調整できます。

フィルタリング

これまで見てきたように、多くのレコーダは、設定を介して、リクエストのURLなどの値に基づいて受信エントリを「無視」する機能を提供します。しかし、現在認証されているユーザーなど、他の要因に基づいてレコードを除外すると便利な場合があります。これらのレコードを除外するには、Pulseのfilterメソッドにクロージャを渡すことができます。通常、filterメソッドはアプリケーションのAppServiceProviderのbootメソッド内で呼び出す必要があります。

 1use Illuminate\Support\Facades\Auth;
 2use Laravel\Pulse\Entry;
 3use Laravel\Pulse\Facades\Pulse;
 4use Laravel\Pulse\Value;
 5 
 6/**
 7 * Bootstrap any application services.
 8 */
 9public function boot(): void
10{
11    Pulse::filter(function (Entry|Value $entry) {
12        return Auth::user()->isNotAdmin();
13    });
14 
15    // ...
16}

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環境変数を設定することでカスタマイズできます。

1PULSE_DB_CONNECTION=pulse

PULSE_DB_CONNECTION=pulse

Redisインジェスト

Redisインジェストには、Redis 6.2以降と、アプリケーションで設定されたRedisクライアントドライバとしてphpredisまたはpredisが必要です。

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

1PULSE_INGEST_DRIVER=redis

PULSE_INGEST_DRIVER=redis

PulseはデフォルトでRedis接続を使用しますが、これはPULSE_REDIS_CONNECTION環境変数でカスタマイズできます。

1PULSE_REDIS_CONNECTION=pulse

PULSE_REDIS_CONNECTION=pulse

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

1php artisan pulse:work

php artisan pulse:work

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

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

1php artisan pulse:restart

php artisan pulse:restart

サンプリング

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

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

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

トリミング

Pulseは、保存されたエントリがダッシュボードのウィンドウ外になると自動的にトリミングします。トリミングは、Pulseの設定ファイルでカスタマイズできる抽選システムを使用してデータをインジェストするときに発生します。

Pulse例外の処理

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

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

1use Laravel\Pulse\Facades\Pulse;
2use Illuminate\Support\Facades\Log;
3 
4Pulse::handleExceptionsUsing(function ($e) {
5    Log::debug('An exception happened in Pulse', [
6        'message' => $e->getMessage(),
7        'stack' => $e->getTraceAsString(),
8    ]);
9});

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を使用しているため、最初のカスタムカードを構築する前にそのドキュメントを確認することをお勧めします。

カードコンポーネント

Laravel Pulseでカスタムカードを作成するには、まずベースのCard Livewireコンポーネントを拡張し、対応するビューを定義します。

 1namespace App\Livewire\Pulse;
 2 
 3use Laravel\Pulse\Livewire\Card;
 4use Livewire\Attributes\Lazy;
 5 
 6#[Lazy]
 7class TopSellers extends Card
 8{
 9    public function render()
10    {
11        return view('livewire.pulse.top-sellers');
12    }
13}

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コンポーネントを活用して、一貫したルックアンドフィールを実現できます。

 1<x-pulse::card :cols="$cols" :rows="$rows" :class="$class" wire:poll.5s="">
 2    <x-pulse::card-header name="Top Sellers">
 3        <x-slot:icon>
 4            ...
 5        </x-slot:icon>
 6    </x-pulse::card-header>
 7 
 8    <x-pulse::scroll :expand="$expand">
 9        ...
10    </x-pulse::scroll>
11</x-pulse::card>

<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コンポーネントとテンプレートを定義したら、そのカードをダッシュボードビューに含めることができます。

1<x-pulse>
2    ...
3 
4    <livewire:pulse.top-sellers cols="4" />
5</x-pulse>

<x-pulse>
    ...

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

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

スタイリング

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

Laravel Viteインテグレーション

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

1laravel({
2    input: [
3        'resources/css/pulse/top-sellers.css',
4        // ...
5    ],
6}),

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

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

1<x-pulse>
2    @vite('resources/css/pulse/top-sellers.css')
3 
4    ...
5</x-pulse>

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

    ...
</x-pulse>

CSSファイル

パッケージに含まれるPulseカードなど、他のユースケースでは、LivewireコンポーネントにCSSファイルへのパスを返すcssメソッドを定義することで、Pulseに追加のスタイルシートをロードするように指示できます。

1class TopSellers extends Card
2{
3    // ...
4 
5    protected function css()
6    {
7        return __DIR__.'/../../dist/top-sellers.css';
8    }
9}

class TopSellers extends Card
{
    // ...

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

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

Tailwind CSS

Tailwind CSSを使用する場合、不要なCSSをロードしたり、PulseのTailwindクラスと競合したりするのを避けるために、専用のTailwind設定ファイルを作成する必要があります。

 1export default {
 2    darkMode: 'class',
 3    important: '#top-sellers',
 4    content: [
 5        './resources/views/livewire/pulse/top-sellers.blade.php',
 6    ],
 7    corePlugins: {
 8        preflight: false,
 9    },
10};

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

その後、CSSエントリポイントで設定ファイルを指定できます。

1@config "../../tailwind.top-sellers.config.js";
2@tailwind base;
3@tailwind components;
4@tailwind utilities;

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

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

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

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

データキャプチャと集計

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

エントリのキャプチャ

Pulseでは、Pulse::recordメソッドを使用して「エントリ」を記録できます。

1use Laravel\Pulse\Facades\Pulse;
2 
3Pulse::record('user_sale', $user->id, $sale->amount)
4    ->sum()
5    ->count();

use Laravel\Pulse\Facades\Pulse;

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

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

利用可能な集計メソッドは次のとおりです：

avg
count
max
min
sum

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

集計データの取得

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

1class TopSellers extends Card
2{
3    public function render()
4    {
5        return view('livewire.pulse.top-sellers', [
6            'topSellers' => $this->aggregate('user_sale', ['sum', 'count'])
7        ]);
8    }
9}

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

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

1@foreach ($topSellers as $seller)
2    {{ $seller->key }}
3    {{ $seller->sum }}
4    {{ $seller->count }}
5@endforeach

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

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

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

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

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

ユーザーの表示

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

 1$aggregates = $this->aggregate('user_sale', ['sum', 'count']);
 2 
 3$users = Pulse::resolveUsers($aggregates->pluck('key'));
 4 
 5return view('livewire.pulse.top-sellers', [
 6    'sellers' => $aggregates->map(fn ($aggregate) => (object) [
 7        'user' => $users->find($aggregate->key),
 8        'sum' => $aggregate->sum,
 9        'count' => $aggregate->count,
10    ])
11]);

$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コンポーネントに直接渡すことができます。

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

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

カスタムレコーダ

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

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

 1[
 2    // ...
 3    'recorders' => [
 4        Acme\Recorders\Deployments::class => [
 5            // ...
 6        ],
 7 
 8        // ...
 9    ],
10]

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

        // ...
    ],
]

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

 1<?php
 2 
 3namespace Acme\Recorders;
 4 
 5use Acme\Events\Deployment;
 6use Illuminate\Support\Facades\Config;
 7use Laravel\Pulse\Facades\Pulse;
 8 
 9class Deployments
10{
11    /**
12     * The events to listen for.
13     *
14     * @var array<int, class-string>
15     */
16    public array $listen = [
17        Deployment::class,
18    ];
19 
20    /**
21     * Record the deployment.
22     */
23    public function record(Deployment $event): void
24    {
25        $config = Config::get('pulse.recorders.'.static::class);
26 
27        Pulse::record(
28            // ...
29        );
30    }
31}

<?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(
            // ...
        );
    }
}

序文

はじめに

アーキテクチャのコンセプト

基本

より深く知る

セキュリティ

データベース

Eloquent ORM

テスト

パッケージ

Laravel Pulse

製品

パッケージ

リソース