Laravel 10.x Laravel Pulse

イントロダクションIntroduction

Laravel Pulseで、アプリケーションのパフォーマンスと使用状況を一目で把握できます。Pulseを使えば、遅いジョブやエンドポイントなどのボトルネックを突き止めたり、最もアクティブなユーザーを見つけたりできます。Laravel Pulse[https://github.com/laravel/pulse] delivers at-a-glance insights into your application's performance and usage. With Pulse, you can track down bottlenecks like slow jobs and endpoints, find your most active users, and more.

個々のイベントの詳細なデバッグには、Laravel Telescopeをチェックしてください。For in-depth debugging of individual events, check out Laravel Telescope[/docs/{{version}}/telescope].

インストールInstallation

warning Warning! Pulseのファーストパーティストレージの実装は、現在MySQLかPostgreSQLデータベースを使っています。別のデータベースエンジンを使用している場合は別に、Pulseデータ用のMySQL／PostgreSQLデータベースが必要になります。[!WARNING]
Pulse's first-party storage implementation currently requires a MySQL or PostgreSQL database. If you are using a different database engine, you will need a separate MySQL or PostgreSQL database for your Pulse data.

Pulseは現在ベータ版なため、ベータリリース版のパッケージをインストールできるように、アプリケーションのcomposer.jsonファイルを調整する必要があるでしょう。Since Pulse is currently in beta, you may need to adjust your application's composer.json file to allow beta package releases to be installed:

"minimum-stability": "beta",
"prefer-stable": true

次に、Composerパッケージマネージャを使い、LaravelプロジェクトへPulseをインストールします。Then, you may use the Composer package manager to install Pulse into your Laravel project:

composer require laravel/pulse

次に、vendor:publish Artisanコマンドを使用し、Pulse設定ファイルとマイグレーションファイルをリソース公開します。Next, you should publish the Pulse configuration and migration files using the vendor:publish Artisan command:

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

最後に、Pulseのデータを格納するテーブルを作成するため、migrateコマンドを実行します。Finally, you should run the migrate command in order to create the tables needed to store Pulse's data:

php artisan migrate

Pulseのデータベースマイグレーションを完了したら、/pulseルートでPulseダッシュボードへアクセスできます。Once Pulse's database migrations have been run, you may access the Pulse dashboard via the /pulse route.

lightbulb Note: パルスデータをアプリケーションのプライマリデータベースに保存したくない場合は、専用のデータベース接続を指定できます。[!NOTE]
If you do not want to store Pulse data in your application's primary database, you may specify a dedicated database connection[#using-a-different-database].

設定Configuration

Pulseの設定オプションの多くは、環境変数を使い制御できます。利用可能なオプションを確認したり、新しいレコーダを登録したり、高度なオプションを設定したりするには、config/pulse.php設定ファイルをリソース公開してください：Many of Pulse's configuration options can be controlled using environment variables. To see the available options, register new recorders, or configure advanced options, you may publish the config/pulse.php configuration file:

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

ダッシュボードDashboard

認可Authorization

Pulseダッシュボードは、/pulse経由でアクセスします。このダッシュボードはデフォルトでアクセスできるのはlocal環境だけなため、'viewPulse'認可ゲートをカスタマイズして、本番環境用の許可設定する必要があります。この設定は、アプリケーションのapp/Providers/AuthServiceProvider.phpファイルで行います。The Pulse dashboard may be accessed via the /pulse route. By default, you will only be able to access this dashboard in the local environment, so you will need to configure authorization for your production environments by customizing the 'viewPulse' authorization gate. You can accomplish this within your application's app/Providers/AuthServiceProvider.php file:

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

/**
 * すべての認証・認可サービスの登録
 */
public function boot(): void
{
    Gate::define('viewPulse', function (User $user) {
        return $user->isAdmin();
    });

    // ...
}

カスタマイズCustomization

Pulseダッシュボードのカードとレイアウトは、ダッシュボードビューをリソース公開することで設定できます。ダッシュボードビューは、resources/views/vendor/pulse/dashboard.blade.phpとして公開します。The Pulse dashboard cards and layout may be configured by publishing the dashboard view. The dashboard view will be published to resources/views/vendor/pulse/dashboard.blade.php:

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

ダッシュボードは、Livewire（和訳）を活用しており、JavaScriptアセットをまったく再構築しなくとも、カードやレイアウトをカスタマイズできます。The dashboard is powered by Livewire[https://livewire.laravel.com/], and allows you to customize the cards and layout without needing to rebuild any JavaScript assets.

このファイルの中では、<x-pulse>コンポーネントがダッシュボードのレンダを担当し、カードのグリッドレイアウトを提供しています。ダッシュボードを画面の幅いっぱいに表示したい場合は、full-widthプロパティをコンポーネントへ指定します。Within this file, the <x-pulse> component is responsible for rendering the dashboard and provides a grid layout for the cards. If you would like the dashboard to span the full width of the screen, you may provide the full-width prop to the component:

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

<x-pulse>コンポーネントはデフォルトで、１２カラムのグリッドを作成しますが、colsプロップを使ってカスタマイズ可能です。By default, the <x-pulse> component will create a 12 column grid, but you may customize this using the cols prop:

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

各カードは、colsとrowsプロップを引数に取り、スペースと位置をコントロールできます。Each card accepts a cols and rows prop to control the space and positioning:

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

ほとんどのカードは、expandプロップも引数に取り、スクロールする代わりにカード全体を表示します。Most cards also accept an expand prop to show the full card instead of scrolling:

<livewire:pulse.slow-queries expand />

ユーザーの解決Resolving Users

アプリケーション使用状況カードなど、ユーザーに関する情報を表示するカードの場合、PulseはユーザーのIDのみ記録します。ダッシュボードをレンダする際、PulseはデフォルトのAuthenticatableモデルから、nameフィールドとemailフィールドを解決し、Gravatarウェブサービスを使用してアバターを表示します。For cards that display information about your users, such as the Application Usage card, Pulse will only record the user's ID. When rendering the dashboard, Pulse will resolve the name and email fields from your default Authenticatable model and display avatars using the Gravatar web service.

アプリケーションのApp\Providers\AppServiceProviderクラス内の、Pulse::userメソッドを呼び出せば、フィールドとアバターをカスタマイズできます。You may customize the fields and avatar by invoking the Pulse::user method within your application's App\Providers\AppServiceProvider class.

userメソッドはクロージャを引数に取ります。そのクロージャは表示するAuthenticatableモデルを引数に受け、ユーザーのname、extra、avatar情報を含む配列を返す必要があります。The user method accepts a closure which will receive the Authenticatable model to be displayed and should return an array containing name, extra, and avatar information for the user:

use Laravel\Pulse\Facades\Pulse;

/**
 * 全アプリケーションサービスの初期起動処理
 */
public function boot(): void
{
    Pulse::user(fn ($user) => [
        'name' => $user->name,
        'extra' => $user->email,
        'avatar' => $user->avatar_url,
    ]);

    // ...
}

lightbulb Note: Laravel\Pulse\Contracts\ResolvesUsers契約を実装し、Laravelのサービスコンテナでバインドすることで、認証されたユーザーを取得する方法を完全にカスタマイズできます。[!NOTE]
You may completely customize how the authenticated user is captured and retrieved by implementing the Laravel\Pulse\Contracts\ResolvesUsers contract and binding it in Laravel's service container[/docs/{{version}}/container#binding-a-singleton].

カードCards

サーバServers

<livewire:pulse.servers />カードは、pulse:checkコマンドを実行しているすべてのサーバのシステムリソースの使用状況を表示します。システムリソースのレポートについては、サーバレコーダ のドキュメントを参照してください。The <livewire:pulse.servers /> card displays system resource usage for all servers running the pulse:check command. Please refer to the documentation regarding the servers recorder[#servers-recorder] for more information on system resource reporting.

Application UsageApplication Usage

<livewire:pulse.usage />カードは、アプリケーションへのリクエスト、ジョブのディスパッチ、遅いリクエストを作り出した上位１０ユーザーを表示します。The <livewire:pulse.usage /> card displays the top 10 users making requests to your application, dispatching jobs, and experiencing slow requests.

すべての使用量メトリクスを同時に画面に表示したい場合は、カードを複数インクルードし、type属性を指定してください。If you wish to view all usage metrics on screen at the same time, you may include the card multiple times and specify the type attribute:

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

Pulseがユーザー情報を取得・表示する方法をカスタマイズする方法については、ユーザーの解決のドキュメントを参照してください。To learn how to customize how Pulse retrieves and displays user information, consult our documentation on resolving users[#dashboard-resolving-users].

lightbulb Note: アプリケーションがたくさんのリクエストを受け取ったり、たくさんのジョブをディスパッチしたりする場合は、サンプリングを有効にするとよいでしょう。詳しくは、ユーザーリクエストのレコーダ、ユーザージョブのレコーダ、遅いジョブのレコーダのドキュメントを参照してください。[!NOTE]
If your application receives a lot of requests or dispatches a lot of jobs, you may wish to enable sampling[#sampling]. See the user requests recorder[#user-requests-recorder], user jobs recorder[#user-jobs-recorder], and slow jobs recorder[#slow-jobs-recorder] documentation for more information.

例外Exceptions

<livewire:pulse.exceptions />カードは、アプリケーションで発生した例外の発生頻度と間隔を表示します。デフォルトでは、例外は例外クラスと発生場所に基づいてグループ化されます。詳しくは 例外レコーダのドキュメントを参照してください。The <livewire:pulse.exceptions /> card shows the frequency and recency of exceptions occurring in your application. By default, exceptions are grouped based on the exception class and location where it occurred. See the exceptions recorder[#exceptions-recorder] documentation for more information.

キューQueues

<livewire:pulse.queues />カードは、キュー投入されたジョブ、処理中、処理済み、解放、失敗などの数を含む、アプリケーション内のキューのスループットを表示します。詳細は キューレコーダ のドキュメントを参照してください。The <livewire:pulse.queues /> card shows the throughput of the queues in your application, including the number of jobs queued, processing, processed, released, and failed. See the queues recorder[#queues-recorder] documentation for more information.

スローリクエストSlow Requests

<livewire:pulse.slow-requests />カードは、設定したしきい値(デフォルトでは1,000ms)を超えたアプリケーションへのリクエストを表示します。詳しくは、スローリクエストレコーダのドキュメントを参照してください。The <livewire:pulse.slow-requests /> card shows incoming requests to your application that exceed the configured threshold, which is 1,000ms by default. See the slow requests recorder[#slow-requests-recorder] documentation for more information.

スロージョブSlow Jobs

<livewire:pulse.slow-jobs />カードは、設定したしきい値(デフォルトでは1,000ms)を超えたアプリケーションのキュー投入したジョブを表示します。詳しくは、スロージョブレコーダのドキュメントを参照してください。The <livewire:pulse.slow-jobs /> card shows the queued jobs in your application that exceed the configured threshold, which is 1,000ms by default. See the slow jobs recorder[#slow-jobs-recorder] documentation for more information.

スロークエリSlow Queries

<livewire:pulse.slow-queries />カードは、設定したしきい値（デフォルトでは1,000ms）を超えるアプリケーションのデータベースクエリを表示します。The <livewire:pulse.slow-queries /> card shows the database queries in your application that exceed the configured threshold, which is 1,000ms by default.

スロークエリはデフォルトで、ＳＱＬクエリ（バインディングなし）と発生場所に基づいてグループ化されますが、ＳＱＬクエリのみでグループ化したい場合は、発生場所をキャプチャしないこともできます。By default, slow queries are grouped based on the SQL query (without bindings) and the location where it occurred, but you may choose to not capture the location if you wish to group solely on the SQL query.

詳しくはスロークエリレコーダのドキュメントを参照してください。See the slow queries recorder[#slow-queries-recorder] documentation for more information.

スロー送信リクエストSlow Outgoing Requests

<livewire:pulse.slow-outgoing-requests />カードは、LaravelのHTTPクライアントを使用して送信したたリクエストのうち、設定したしきい値（デフォルトでは1,000ms）を超えたものを表示します。The <livewire:pulse.slow-outgoing-requests /> card shows outgoing requests made using Laravel's HTTP client[/docs/{{version}}/http-client] that exceed the configured threshold, which is 1,000ms by default.

エントリはデフォルトで、完全なURLでグループ化されます。しかし、正規表現を使うことで、似たようなリクエストを正規化したり、グループ化したりできます。詳しくは スロー送信リクエストレコーダのドキュメントを参照してください。By default, entries will be grouped by the full URL. However, you may wish to normalize or group similar outgoing requests using regular expressions. See the slow outgoing requests recorder[#slow-outgoing-requests-recorder] documentation for more information.

キャッシュCache

<livewire:pulse.cache />カードは、アプリケーションのキャッシュのヒットとミスの統計を、グローバルと個々のキーの両方で表示します。The <livewire:pulse.cache /> card shows the cache hit and miss statistics for your application, both globally and for individual keys.

エントリはデフォルトで、キーによりグループ化されます。ただし、正規表現を使用して、類似したキーを正規化またはグループ化できます。詳細はキャッシュ操作レコーダのドキュメントを参照してください。By default, entries will be grouped by key. However, you may wish to normalize or group similar keys using regular expressions. See the cache interactions recorder[#cache-interactions-recorder] documentation for more information.

エンティティのキャプチャCapturing Entries

ほとんどのPulseレコーダは、Laravelが発行するフレームワークイベントに基づき、自動的にエントリーをキャプチャします。しかし、サーバレコーダやいくつかのサードパーティカードは、定期的に情報をポーリングする必要があります。これらのカードを使用するには、個々のアプリケーションサーバ上でpulse:checkデーモンを実行する必要があります：Most Pulse recorders will automatically capture entries based on framework events dispatched by Laravel. However, the servers recorder[#servers-recorder] and some third-party cards must poll for information regularly. To use these cards, you must run the pulse:check daemon on all of your individual application servers:

php artisan pulse:check

lightbulb Note: pulse:checkプロセスをバックグラウンドで永続的に実行し続けるには、Supervisorのようなプロセスモニタを使い、コマンドの実行が止まらないようにする必要があります。[!NOTE]
To keep the pulse:check process running permanently in the background, you should use a process monitor such as Supervisor to ensure that the command does not stop running.

pulse:checkコマンドは起動終了しないプロセスなため、再起動しないとコードベースの変更が現れません。アプリケーションのデプロイ処理中に、pulse:restartコマンドを呼び出し、コマンドを悠然と再起動する必要があります。As the pulse:check command is a long-lived process, it will not see changes to your codebase without being restarted. You should gracefully restart the command by calling the pulse:restart command during your application's deployment process:

php artisan pulse:restart

lightbulb Note: Pulseは再起動シグナルを保持するためにキャッシュを使用します。そのため、この機能を使用する前に、アプリケーション用にキャッシュドライバを適切に設定済みであることを確認する必要があります。[!NOTE]
Pulse uses the cache[/docs/{{version}}/cache] to store restart signals, so you should verify that a cache driver is properly configured for your application before using this feature.

レコーダRecorders

レコーダは、Pulseデータベースに記録するため、アプリケーションからのエントリをキャプチャする役割を果たします。レコーダはPulse設定ファイルのrecordersセクションで登録・設定します。Recorders are responsible for capturing entries from your application to be recorded in the Pulse database. Recorders are registered and configured in the recorders section of the Pulse configuration file[#configuration].

キャッシュ操作Cache Interactions

CacheInteractionsレコーダは、アプリケーションで発生したキャッシュのヒットとミスに関する情報を取得し、キャッシュカードに表示します。The CacheInteractions recorder captures information about the cache[/docs/{{version}}/cache] hits and misses occurring in your application for display on the Cache[#cache-card] card.

オプションでサンプルレートと無視するキーのパターンを調整できます。You may optionally adjust the sample rate[#sampling] and ignored key patterns.

また、キーのグループ化を設定し、類似のキーを同じエントリとしてグループ化することもできます。例えば、同じタイプの情報をキャッシュするキーから、一意のIDを削除したい場合などです。グループは、キーの一部を「FindしてReplaceする」正規表現を使い設定する。一例は設定ファイルに含まれています。You may also configure key grouping so that similar keys are grouped as a single entry. For example, you may wish to remove unique IDs from keys caching the same type of information. Groups are configured using a regular expression to "find and replace" parts of the key. An example is included in the configuration file:

レコード\CacheInteractions::class => [
    // ...
    'groups' => [
        // '/:\d /' => ':*',
    ],
],

最初にマッチしたパターンを適用します。マッチするパターンがなければ、キーをそのままキャプチャします。The first pattern that matches will be used. If no patterns match, then the key will be captured as-is.

例外Exceptions

Exceptionsレコーダは、アプリケーションで発生した報告可能(reportable)な例外に関する情報を記録し、例外カードに表示します。The Exceptions recorder captures information about reportable exceptions occurring in your application for display on the Exceptions[#exceptions-card] card.

オプションでサンプルレートと無視する例外パターンを調整できます。例外が発生した場所をキャプチャするかどうかも設定可能です。キャプチャした場所は、Pulseダッシュボードに表示され、例外の発生元を追跡するのに役立ちます。ただし、同じ例外が複数の場所で発生した場合は、固有の場所ごとに複数回表示します。You may optionally adjust the sample rate[#sampling] and ignored exceptions patterns. You may also configure whether to capture the location that the exception originated from. The captured location will be displayed on the Pulse dashboard which can help to track down the exception origin; however, if the same exception occurs in multiple locations then it will appear multiple times for each unique location.

キューQueues

Queuesレコーダーはアプリケーションのキューに関する情報を記録し、キューに表示します。The Queues recorder captures information about your applications queues for display on the Queues[#queues-card].

オプションでサンプルレートと無視するジョブパターンを調整できます。You may optionally adjust the sample rate[#sampling] and ignored jobs patterns.

スロージョブSlow Jobs

SlowJobsレコーダーは、アプリケーションで発生したスロージョブの情報をスロージョブカードに表示するためにキャプチャします。The SlowJobs recorder captures information about slow jobs occurring in your application for display on the Slow Jobs[#slow-jobs-recorder] card.

オプションで、スロージョブのしきい値、サンプル・レート、無視するジョブのパターンを調整できます。You may optionally adjust the slow job threshold, sample rate[#sampling], and ignored job patterns.

スロー送信リクエストSlow Outgoing Requests

SlowOutgoingRequestsレコーダーは、LaravelのHTTPクライアントを使用して行われた送信HTTPリクエストのうち、設定した閾値を超えたリクエストに関する情報を取得し、スロー送信リクエストカードに表示します。The SlowOutgoingRequests recorder captures information about outgoing HTTP requests made using Laravel's HTTP client[/docs/{{version}}/http-client] that exceed the configured threshold for display on the Slow Outgoing Requests[#slow-outgoing-requests-card] card.

オプションで、スロー送信リクエストのしきい値、サンプルレート、無視するURLパターンを調整できます。You may optionally adjust the slow outgoing request threshold, sample rate[#sampling], and ignored URL patterns.

また、URLのグループ化を設定して、類似のURLを同じエントリとしてグループ化することもできます。例えば、URLパスから一意のIDを削除したり、ドメインのみでグループ化したりすることができます。グループは、URLの一部を「FindしてReplaceする」正規表現を使用して設定します。一例を設定ファイルに用意しています。You may also configure URL grouping so that similar URLs are grouped as a single entry. For example, you may wish to remove unique IDs from URL paths or group by domain only. Groups are configured using a regular expression to "find and replace" parts of the URL. Some examples are included in the configuration file:

レコード\OutgoingRequests::class => [
    // ...
    'groups' => [
        // '#^https://api\.github\.com/repos/.*$#' => 'api.github.com/repos/*',
        // '#^https?://([^/]*).*$#' => '\1',
        // '#/\d #' => '/*',
    ],
],

最初にマッチしたパターンを使用します。マッチするパターンがない場合、URLをそのままキャプチャします。The first pattern that matches will be used. If no patterns match, then the URL will be captured as-is.

スロークエリSlow Queries

SlowQueriesレコーダは、スロークエリカードに表示するため、設定したしきい値を超えるアプリケーションのデータベースクエリをキャプチャします。The SlowQueries recorder captures any database queries in your application that exceed the configured threshold for display on the Slow Queries[#slow-queries-card] card.

オプションで、スロークエリのしきい値、サンプルレート、無視するクエリパターンを調整できます。また、クエリの場所をキャプチャするかも設定可能です。キャプチャした場所は、Pulseダッシュボードに表示され、クエリの発信元を追跡するのに役立ちますが、同じクエリが複数の場所で行われた場合は、それぞれの場所で複数回表示します。You may optionally adjust the slow query threshold, sample rate[#sampling], and ignored query patterns. You may also configure whether to capture the query location. The captured location will be displayed on the Pulse dashboard which can help to track down the query origin; however, if the same query is made in multiple locations then it will appear multiple times for each unique location.

スローリクエストSlow Requests

Requestsレコーダは、アプリケーションへのリクエストに関する情報を記録し、スローリクエストカードとアプリケーションの使用状況カードに表示します。The Requests recorder captures information about requests made to your application for display on the Slow Requests[#slow-requests-card] and Application Usage[#application-usage-card] cards.

オプションで、スロールートのしきい値、サンプルレート、無視するパスを調整できます。You may optionally adjust the slow route threshold, sample rate[#sampling], and ignored paths.

サーバServers

Serversレコーダは、アプリケーションを動かしているサーバのCPU、メモリ、ストレージの使用状況をキャプチャし、サーバカードに表示します。このレコーダを使うには、pulse:checkコマンドを監視する各サーバ上で実行する必要があります。The Servers recorder captures CPU, memory, and storage usage of the servers that power your application for display on the Servers[#servers-card] card. This recorder requires the pulse:check command[#capturing-entries] to be running on each of the servers you wish to monitor.

報告する各サーバは、一意な名前を持っていなければなりません。Pulseはデフォルトで、PHPのgethostname関数が返す値を使用します。これをカスタマイズしたい場合は、PULSE_SERVER_NAME環境変数を設定します。Each reporting server must have a unique name. By default, Pulse will use the value returned by PHP's gethostname function. If you wish to customize this, you may set the PULSE_SERVER_NAME environment variable:

PULSE_SERVER_NAME=load-balancer

Pulse設定ファイルでは、監視するディレクトリをカスタマイズすることもできます。The Pulse configuration file also allows you to customize the directories that are monitored.

ユーザージョブUser Jobs

UserJobsレコーダは、アプリケーションの使用状況カードに表示するために、アプリケーションでジョブをディスパッチしているユーザーに関する情報を取得します。The UserJobs recorder captures information about the users dispatching jobs in your application for display on the Application Usage[#application-usage-card] card.

オプションでサンプルレートと無視するジョブパターンを調整できます。You may optionally adjust the sample rate[#sampling] and ignored job patterns.

ユーザーリクエストUser Requests

UserRequestsレコーダは、あなたのアプリケーションにリクエストをしているユーザーに関する情報を取得し、アプリケーションの使用状況カードに表示します。The UserRequests recorder captures information about the users making requests to your application for display on the Application Usage[#application-usage-card] card.

オプションでサンプルレートと無視するジョブパターンを調整できます。You may optionally adjust the sample rate[#sampling] and ignored job patterns.

フィルタリングFiltering

これまで見てきたように、多くのレコーダは設定により、リクエストURLのような値に基づき、受信エントリを「無視」する機能を提供しています。しかし、時には他の要素、例えば現在認証済みのユーザーに基づいてレコードをフィルタリングすることが役立つこともあるでしょう。そのようにレコードをフィルタリングするには、Pulseのfilterメソッドへクロージャを渡します。通常、filterメソッドはアプリケーションのAppServiceProviderのbootメソッド内で呼び出す必要があります。As we have seen, many recorders[#recorders] offer the ability to, via configuration, "ignore" incoming entries based on their value, such as a request's URL. But, sometimes it may be useful to filter out records based on other factors, such as the currently authenticated user. To filter out these records, you may pass a closure to Pulse's filter method. Typically, the filter method should be invoked within the boot method of your application's AppServiceProvider:

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

/**
 * 全アプリケーションサービスの初期起動処理
 */
public function boot(): void
{
    Pulse::filter(function (Entry|Value $entry) {
        return Auth::user()->isNotAdmin();
    });

    // ...
}

パフォーマンスPerformance

Pulseはインフラを追加することなく、既存のアプリケーションに組み込めるように設計しています。しかし、トラフィックの多いアプリケーションでは、Pulseがアプリケーションのパフォーマンスに与える影響を取り除く方法がいくつかあります。Pulse has been designed to drop into an existing application without requiring any additional infrastructure. However, for high-traffic applications, there are several ways of removing any impact Pulse may have on your application's performance.

他のデータベースの使用Using a Different Database

トラフィックの多いアプリケーションでは、アプリケーション・データベースへの影響を避けるため、Pulse専用データベース接続を使用を望まれるでしょう。For high-traffic applications, you may prefer to use a dedicated database connection for Pulse to avoid impacting your application database.

PULSE_DB_CONNECTION環境変数を設定すれば、Pulseで使用するデータベース接続をカスタマイズできます。You may customize the database connection[/docs/{{version}}/database#configuration] used by Pulse by setting the PULSE_DB_CONNECTION environment variable.

PULSE_DB_CONNECTION=pulse

Redis統合Redis Ingest

warning Warning! Redisを使用するには、Redis6.2以上と、アプリケーションの設定済みRedisクライアントドライバに、phpredisまたはpredisが必要です。[!WARNING]
The Redis Ingest requires Redis 6.2 or greater and phpredis or predis as the application's configured Redis client driver.

Pulseはデフォルトで、HTTPレスポンスがクライアントに送信した後、またはジョブを処理した後に、設定されたデータベース接続に直接エントリを保存します。しかし、PulseのRedisインジェストドライバを代わりに使用し、Redisストリームへエントリを送信することもできます。これはPULSE_INGEST_DRIVER環境変数を設定すると有効になります。By default, Pulse will store entries directly to the configured database connection[#using-a-different-database] after the HTTP response has been sent to the client or a job has been processed; however, you may use Pulse's Redis ingest driver to send entries to a Redis stream instead. This can be enabled by configuring the PULSE_INGEST_DRIVER environment variable:

PULSE_INGEST_DRIVER=redis

PulseはデフォルトのRedis接続を使いますが、PULSE_REDIS_CONNECTION環境変数を使い、カスタマイズすることもできます。Pulse will use your default Redis connection[/docs/{{version}}/redis#configuration] by default, but you may customize this via the PULSE_REDIS_CONNECTION environment variable:

PULSE_REDIS_CONNECTION=pulse

Redisインジェストを使用する場合は、pulse:workコマンドを実行する必要があります。ストリームを監視し、RedisからPulseのデータベーステーブルへエントリを移動させるためにです。When using the Redis ingest, you will need to run the pulse:work command to monitor the stream and move entries from Redis into Pulse's database tables.

php artisan pulse:work

lightbulb Note: pulse:workプロセスをバックグラウンドで永久に実行し続けるには、Supervisorのようなプロセスモニタを使い、Pulseワーカの実行を止めないようにする必要があります。[!NOTE]
To keep the pulse:work process running permanently in the background, you should use a process monitor such as Supervisor to ensure that the Pulse worker does not stop running.

pulse:workコマンドは起動終了しないプロセスなため、再起動しないとコードベースの変更が現れません。アプリケーションのデプロイ処理中に、pulse:restartコマンドを呼び出し、コマンドを悠然と再起動する必要があります。As the pulse:work command is a long-lived process, it will not see changes to your codebase without being restarted. You should gracefully restart the command by calling the pulse:restart command during your application's deployment process:

php artisan pulse:restart

lightbulb Note: Pulseは再起動シグナルを保持するためにキャッシュを使用します。そのため、この機能を使用する前に、アプリケーション用にキャッシュドライバを適切に設定済みであることを確認する必要があります。[!NOTE]
Pulse uses the cache[/docs/{{version}}/cache] to store restart signals, so you should verify that a cache driver is properly configured for your application before using this feature.

サンプリングSampling

Pulseはデフォルトで、アプリケーションで発生するすべての関連イベントをキャプチャします。トラフィックの多いアプリケーションの場合、特に長期間では、ダッシュボードに何百万ものデータベース行を集約する必要が生じる可能性があります。By default, Pulse will capture every relevant event that occurs in your application. For high-traffic applications, this can result in needing to aggregate millions of database rows in the dashboard, especially for longer time periods.

その代わりに、特定のPulseデータレコーダでは「サンプリング」を有効にできます。例えば、ユーザーリクエストレコーダのサンプルレートを0.1に設定すると、アプリケーションへのリクエストの約10%だけを記録することになります。ダッシュボードでは、値はスケールアップされ、近似値であることを示すために、~を先頭に付けています。You may instead choose to enable "sampling" on certain Pulse data recorders. For example, setting the sample rate to 0.1 on the User Requests[#user-requests-recorder] recorder will mean that you only record approximately 10% of the requests to your application. In the dashboard, the values will be scaled up and prefixed with a ~ to indicate that they are an approximation.

一般的に、特定のメトリックのエントリが多いほど、精度を犠牲にすることなく、サンプルレートを低く設定できます。In general, the more entries you have for a particular metric, the lower you can safely set the sample rate without sacrificing too much accuracy.

トリミングTrimming

一度ダッシュボードのウィンドウの外に出ると、Pulseは保存したエントリーを自動的にトリミングします。トリミングは、Pulseの設定ファイルでカスタマイズできる抽選システムを使ってデータを取り込むときに行われます。Pulse will automatically trim its stored entries once they are outside of the dashboard window. Trimming occurs when ingesting data using a lottery system which may be customized in the Pulse configuration file[#configuration].

Pulse例外の処理Handling Pulse Exceptions

保存域のデータベースに接続できないなど、Pulseデータの取り込み中に例外が発生した場合、Pulseはアプリケーションに影響を与えないように静かに失敗します。If an exception occurs while capturing Pulse data, such as being unable to connect to the storage database, Pulse will silently fail to avoid impacting your application.

例外の処理方法をカスタマイズしたい場合は、handleExceptionsUsingメソッドにクロージャを指定してください。If you wish to customize how these exceptions are handled, you may provide a closure to the handleExceptionsUsing method:

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(),
    ]);
});

カスタムカードCustom Cards

Pulseでは、アプリケーションの特定のニーズに関連したデータを表示するためのカスタムカードを構築できます。PulseはLivewire（和訳）を使うので、最初のカスタムカードを作る前にそのドキュメントを確認（和訳）してください。Pulse allows you to build custom cards to display data relevant to your application's specific needs. Pulse uses Livewire[https://livewire.laravel.com], so you may want to review its documentation[https://livewire.laravel.com/docs] before building your first custom card.

カードコンポーネントCard Components

Laravel Pulseでカスタムカードを作成するには、ベースとなるCard Livewireコンポーネントを拡張し、対応するビューを定義することから始めます。Creating a custom card in Laravel Pulse starts with extending the base Card Livewire component and defining a corresponding view:

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属性を尊重したプレースホルダを自動的に提供します。When using Livewire's lazy loading[https://livewire.laravel.com/docs/lazy] feature, The Card component will automatically provide a placeholder that respects the cols and rows attributes passed to your component.

Pulseカードに対応するビューを記述するときは、PulseのBladeコンポーネントを活用して、一貫したルック＆フィールを実現できます。When writing your Pulse card's corresponding view, you may leverage Pulse's Blade components for a consistent look and feel:

<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=""属性を含めてください。The $cols, $rows, $class, and $expand variables should be passed to their respective Blade components so the card layout may be customized from the dashboard view. You may also wish to include the wire:poll.5s="" attribute in your view to have the card automatically update.

Livewireコンポーネントとテンプレートを定義したら、そのカードをダッシュボードビューに含めることができます。Once you have defined your Livewire component and template, the card may be included in your dashboard view[#dashboard-customization]:

<x-pulse>
    ...

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

lightbulb Note: カードがパッケージに含まれている場合、Livewire::componentメソッドを使用してコンポーネントをLivewireに登録する必要があります。[!NOTE]
If your card is included in a package, you will need to register the component with Livewire using the Livewire::component method.

スタイルStyling

Pulseに含まれているクラスやコンポーネント以上のスタイリングが必要な場合、カードにカスタムCSSを含めるための選択肢がいくつかあります。If your card requires additional styling beyond the classes and components included with Pulse, there are a few options for including custom CSS for your cards.

Laravel Vite統合Laravel Vite Integration

カスタムカードがアプリケーションのコードベース内にあり、LaravelのVite統合を使用している場合、カード専用のCSSエントリーポイントを含めるために、vite.config.jsファイルを更新してください。If your custom card lives within your application's code base and you are using Laravel's Vite integration[/docs/{{version}}/vite], you may update your vite.config.js file to include a dedicated CSS entry point for your card:

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

次に、ダッシュボードビュー内で@vite Bladeディレクティブを使用し、カードのCSSエントリポイントを指定してください。You may then use the @vite Blade directive in your dashboard view[#dashboard-customization], specifying the CSS entrypoint for your card:

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

    ...
</x-pulse>

CSSファイルCSS Files

パッケージ内にPulseカードを持つ構成を含む他の使用例では、CSSファイルへのファイルパスを返すcssメソッドをLivewireコンポーネントに定義することで、Pulseに追加のスタイルシートを読み込むように指示できます。For other use cases, including Pulse cards contained within a package, you may instruct Pulse to load additional stylesheets by defining a css method on your Livewire component that returns the file path to your CSS file:

class TopSellers extends Card
{
    // ...

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

このカードがダッシュボードに含まれる場合、Pulseは自動的にこのファイルの内容を<style>タグ内に含めますので、publicディレクトリで公開する必要はありません。When this card is included on the dashboard, Pulse will automatically include the contents of this file within a <style> tag so it does not need to be published to the public directory.

Tailwind CSSTailwind CSS

Tailwind CSSを使用する場合は、不要なCSSを読み込んだり、PulseのTailwindクラスと競合しないように、専用のTailwind設定ファイルを作成する必要があります。When using Tailwind CSS, you should create a dedicated Tailwind configuration file to avoid loading unnecessary CSS or conflicting with Pulse's Tailwind classes:

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

それから、CSSエントリーポイントに設定ファイルを指定します。You may then specify the configuration file in your CSS entrypoint:

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

また、カードのビューに、Tailwindのimportantセレクタ戦略へ渡したセレクタにマッチするid属性またはclass属性を含める必要があります。You will also need to include an id or class attribute in your card's view that matches the selector passed to Tailwind's important selector strategy[https://tailwindcss.com/docs/configuration#selector-strategy]:

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

データキャプチャと集積Data Capture and Aggregation

カスタムカードはどこからでもデータを取得し表示できますが、Pulseの強力で効率的なデータ記録・集計システムを活用したくなるでしょう。Custom cards may fetch and display data from anywhere; however, you may wish to leverage Pulse's powerful and efficient data recording and aggregation system.

エンティティのキャプチャCapturing Entries

Pulseは、Pulse::recordメソッドを使い、「エントリ」を記録しています。Pulse allows you to record "entries" using the Pulse::record method:

use Laravel\Pulse\Facades\Pulse;

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

recordメソッドに渡す最初の引数は、記録するエントリのtypeで、第２引数は集計したデータをどのようにグループ化するかを決定するためのkeyです。ほとんどの集約メソッドでは、集約する値（value）も指定する必要があります。上記例では、集約値は$sale->amountです。その後、（sumのような）集約メソッドを１つ以上呼び出すことで、Pulseは集約前の値を「バケット」に取り込み、後で効率的に取り出します。The first argument provided to the record method is the type for the entry you are recording, while the second argument is the key that determines how the aggregated data should be grouped. For most aggregation methods you will also need to specify a value to be aggregated. In the example above, the value being aggregated is $sale->amount. You may then invoke one or more aggregation methods (such as sum) so that Pulse may capture pre-aggregated values into "buckets" for efficient retrieval later.

利用可能な集計方法は以下の通りです。The available aggregation methods are:

• avgavg
• countcount
• maxmax
• minmin
• sumsum

lightbulb Note: 現在認証済みのユーザーIDをキャプチャするカードパッケージを構築するときは、Pulse::resolveAuthenticatedUserId() メソッドを使うべきでしょう。これは、アプリケーションに対して行う、ユーザーリゾルバのカスタマイズを尊重します。[!NOTE]
When building a card package that captures the currently authenticated user ID, you should use the Pulse::resolveAuthenticatedUserId() method, which respects any user resolver customizations[#dashboard-resolving-users] made to the application.

集積データの取得Retrieving Aggregate Data

PulseのCard Livewireコンポーネントを拡張する場合、aggregateメソッドを使用して、ダッシュボードで表示する期間の集計データを取得できます。When extending Pulse's Card Livewire component, you may use the aggregate method to retrieve aggregated data for the period being viewed in the dashboard:

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

aggregateメソッドは、PHPのstdClassオブジェクトのコレクションを返します。各オブジェクトは、先に取得したkeyプロパティと、リクエストした集約キーを含みます。The aggregate method returns return a collection of PHP stdClass objects. Each object will contain the key property captured earlier, along with keys for each of the requested aggregates:

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

Pulseは事前に集約したバケットからデータを主に取得します。したがって、指定する集約はPulse::recordメソッドを使用して事前にキャプチャしておく必要があります。通常、最も古いバケットは部分的に期間外になっているため、Pulseはギャップを埋めるために、最も古いエントリを集約して、各ポーリングリクエストで期間全体を集約する必要なく、期間全体の正確な値を提供します。Pulse will primarily retrieve data from the pre-aggregated buckets; therefore, the specified aggregates must have been captured up-front using the Pulse::record method. The oldest bucket will typically fall partially outside the period, so Pulse will aggregate the oldest entries to fill the gap and give an accurate value for the entire period, without needing to aggregate the entire period on each poll request.

aggregateTotalメソッドを使用して、指定するタイプの合計値を取得することもできます。たとえば、次のメソッドでは、ユーザーごとにグループ化するのではなく、全ユーザーの売上合計を取得します。You may also retrieve a total value for a given type by using the aggregateTotal method. For example, the following method would retrieve the total of all user sales instead of grouping them by user.

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

ユーザーの表示Displaying Users

キーとしてユーザーIDを記録する集約を扱う場合、Pulse::resolveUsersメソッドを使用し、キーをユーザーレコードにして解決できます。When working with aggregates that record a user ID as the key, you may resolve the keys to user records using the Pulse::resolveUsers method:

$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コンポーネントへ直接渡せます。The find method returns an object containing name, extra, and avatar keys, which you may optionally pass directly to the <x-pulse::user-card> Blade component:

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

カスタムレコーダCustom Recorders

パッケージの制作者は、ユーザーがデータの取り込みを設定できるようにレコーダクラスの提供を望むかもしれません。Package authors may wish to provide recorder classes to allow users to configure the capturing of data.

レコーダは、アプリケーションの設定ファイルconfig/pulse.phpのrecordersセクションで登録しています。Recorders are registered in the recorders section of the application's config/pulse.php configuration file:

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

        // ...
    ],
]

レコーダは、$listenプロパティを指定することで、イベントをリッスンします。Pulseは自動的にリスナを登録し、レコーダーのrecordメソッドを呼び出します：Recorders may listen to events by specifying a $listen property. Pulse will automatically register the listeners and call the recorders record method:

<?php

namespace Acme\Recorders;

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

class Deployments
{
    /**
     * リッスンするイベント
     *
     * @var list<class-string>
     */
    public array $listen = [
        Deployment::class,
    ];

    /**
     * デプロイメントを記録
     */
    public function record(Deployment $event): void
    {
        $config = Config::get('pulse.recorders.'.static::class);

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