パッケージ - Telescope - 《Laravel 11.x ドキュメント》日本語

はじめに
インストール
Telescope のアップグレード
フィルタリング
- エントリ
- バッチ
タグ付け
利用可能なウォッチャー
ユーザーアバターの表示

はじめに

Laravel Telescope は、ローカルの Laravel 開発環境に素晴らしい仲間を提供します。Telescope は、アプリケーションに入ってくるリクエスト、例外、ログエントリ、データベースクエリ、キューに入れられたジョブ、メール、通知、キャッシュ操作、スケジュールされたタスク、変数ダンプなどの洞察を提供します。
Telescope - img1

インストール

Composer パッケージマネージャーを使用して、Telescope を Laravel プロジェクトにインストールできます:

composer require laravel/telescope

Telescope をインストールした後、telescope:install Artisan コマンドを使用してそのアセットとマイグレーションを公開します。Telescope をインストールした後、Telescope のデータを保存するために必要なテーブルを作成するために migrate コマンドを実行する必要があります:

php artisan telescope:install
php artisan migrate

最後に、/telescope ルートを介して Telescope ダッシュボードにアクセスできます。

ローカル専用インストール

Telescope をローカル開発の支援にのみ使用する予定の場合、--dev フラグを使用して Telescope をインストールできます:

composer require laravel/telescope --dev
php artisan telescope:install
php artisan migrate

telescope:install を実行した後、アプリケーションの bootstrap/providers.php 設定ファイルから TelescopeServiceProvider サービスプロバイダーの登録を削除する必要があります。代わりに、App\Providers\AppServiceProvider クラスの register メソッド内で Telescope のサービスプロバイダーを手動で登録します。プロバイダーを登録する前に、現在の環境が local であることを確認します:

/**
 * Register any application services.
 */
public function register(): void
{
   if ($this->app->environment('local')) {
   $this->app->register(\Laravel\Telescope\TelescopeServiceProvider::class);
   $this->app->register(TelescopeServiceProvider::class);
   }
}

最後に、次の内容を composer.json ファイルに追加して、Telescope パッケージが自動検出されないようにします:

"extra": {
   "laravel": {
   "dont-discover": [
   "laravel/telescope"
   ]
   }
},

設定

Telescope のアセットを公開した後、その主な設定ファイルは config/telescope.php にあります。この設定ファイルでは、ウォッチャーオプションを設定できます。各設定オプションにはその目的の説明が含まれているため、このファイルを十分に探検してください。

必要に応じて、enabled 設定オプションを使用して Telescope のデータ収集を完全に無効にすることができます:

'enabled' => env('TELESCOPE_ENABLED', true),

データのプルーニング

プルーニングを行わないと、telescope_entries テーブルは非常に迅速にレコードを蓄積する可能性があります。これを軽減するために、telescope:prune Artisan コマンドを毎日実行するようにスケジュールする必要があります:

use Illuminate\Support\Facades\Schedule;
Schedule::command('telescope:prune')->daily();

デフォルトでは、24 時間以上前のすべてのエントリがプルーニングされます。コマンドを呼び出す際に hours オプションを使用して、Telescope データを保持する期間を決定できます。たとえば、次のコマンドは、48 時間以上前に作成されたすべてのレコードを削除します:

use Illuminate\Support\Facades\Schedule;
Schedule::command('telescope:prune --hours=48')->daily();

ダッシュボードの認可

Telescope ダッシュボードには /telescope ルートを介してアクセスできます。デフォルトでは、local 環境でのみこのダッシュボードにアクセスできます。app/Providers/TelescopeServiceProvider.php ファイル内には、認可ゲートの定義があります。この認可ゲートは、非ローカル 環境での Telescope へのアクセスを制御します。必要に応じて、このゲートを変更して Telescope インストールへのアクセスを制限できます:

use App\Models\User;
/**
 * Register the Telescope gate.
 *
 * This gate determines who can access Telescope in non-local environments.
 */
protected function gate(): void
{
   Gate::define('viewTelescope', function (User $user) {
   return in_array($user->email, [
   '',
   ]);
   });
}

プロダクション環境では、APP_ENV 環境変数を production に変更することを確認してください。そうしないと、Telescope インストールが公開されます。

Telescope のアップグレード

Telescope の新しいメジャーバージョンにアップグレードする際は、アップグレードガイドを注意深く確認することが重要です。

さらに、Telescope の新しいバージョンにアップグレードする際は、Telescope のアセットを再公開する必要があります:

php artisan telescope:publish

アセットを最新の状態に保ち、将来のアップデートでの問題を避けるために、アプリケーションの composer.json ファイルの post-update-cmd スクリプトに vendor:publish --tag=laravel-assets コマンドを追加できます:

{
   "scripts": {
   "post-update-cmd": [
   "@php artisan vendor:publish --tag=laravel-assets --ansi --force"
   ]
   }
}

フィルタリング

エントリ

Telescope によって記録されるデータは、filter クローザーを介してフィルタリングできます。このクローザーは、デフォルトで local 環境内のすべてのデータと、例外、失敗したジョブ、スケジュールされたタスク、および他のすべての環境で監視されたタグを持つデータを記録します:

use Laravel\Telescope\IncomingEntry;
use Laravel\Telescope\Telescope;
/**
 * Register any application services.
 */
public function register(): void
{
   $this->hideSensitiveRequestDetails();
   Telescope::filter(function (IncomingEntry $entry) {
   if ($this->app->environment('local')) {
   return true;
   }
   return $entry->isReportableException() ||
   $entry->isFailedJob() ||
   $entry->isScheduledTask() ||
   $entry->isSlowQuery() ||
   $entry->hasMonitoredTag();
   });
}

バッチ

filter クローザーは個々のエントリのデータをフィルタリングしますが、filterBatch メソッドを使用して、特定のリクエストまたはコンソールコマンドのすべてのデータをフィルタリングするクローザーを登録できます。クローザーが true を返す場合、すべてのエントリが Telescope によって記録されます:

use Illuminate\Support\Collection;
use Laravel\Telescope\IncomingEntry;
use Laravel\Telescope\Telescope;
/**
 * Register any application services.
 */
public function register(): void
{
   $this->hideSensitiveRequestDetails();
   Telescope::filterBatch(function (Collection $entries) {
   if ($this->app->environment('local')) {
   return true;
   }
   return $entries->contains(function (IncomingEntry $entry) {
   return $entry->isReportableException() ||
   $entry->isFailedJob() ||
   $entry->isScheduledTask() ||
   $entry->isSlowQuery() ||
   $entry->hasMonitoredTag();
   });
   });
}

タグ付け

Telescope では、エントリを「タグ」で検索できます。タグは、Eloquent モデルクラス名や認証されたユーザー ID であることが多く、Telescope が自動的にエントリに追加します。時には、エントリに独自のカスタムタグを付けたい場合があります。これを実現するために、Telescope::tag メソッドを使用できます。tag メソッドは、タグの配列を返すクローザーを受け入れます。クローザーによって返されたタグは、Telescope がエントリに自動的に追加するタグとマージされます。通常、tag メソッドを register メソッド内で呼び出すべきです:

use Laravel\Telescope\IncomingEntry;
use Laravel\Telescope\Telescope;
/**
 * Register any application services.
 */
public function register(): void
{
   $this->hideSensitiveRequestDetails();
   Telescope::tag(function (IncomingEntry $entry) {
   return $entry->type === 'request'
   ? ['status:'.$entry->content['response_status']]
   : [];
   });
 }

利用可能なウォッチャー

Telescope の「ウォッチャー」は、リクエストまたはコンソールコマンドが実行されるときにアプリケーションデータを収集します。config/telescope.php 設定ファイル内で有効にしたいウォッチャーのリストをカスタマイズできます:

'watchers' => [
   Watchers\CacheWatcher::class => true,
   Watchers\CommandWatcher::class => true,
   ...
],

一部のウォッチャーは、追加のカスタマイズオプションを提供することもできます:

'watchers' => [
   Watchers\QueryWatcher::class => [
   'enabled' => env('TELESCOPE_QUERY_WATCHER', true),
   'slow' => 100,
   ],
   ...
],

バッチウォッチャー

バッチウォッチャーは、キューに入れられたバッチに関する情報を記録します。ジョブおよび接続情報を含みます。

キャッシュウォッチャー

キャッシュウォッチャーは、キャッシュキーがヒット、ミス、更新、忘れられたときにデータを記録します。

コマンドウォッチャー

コマンドウォッチャーは、Artisan コマンドが実行されるたびに、引数、オプション、終了コード、および出力を記録します。特定のコマンドをウォッチャーによって記録されないように除外したい場合は、ignore オプション内でコマンドを指定できます:

'watchers' => [
   Watchers\CommandWatcher::class => [
   'enabled' => env('TELESCOPE_COMMAND_WATCHER', true),
   'ignore' => ['key:generate'],
   ],
   ...
],

ダンプウォッチャー

ダンプウォッチャーは、Telescope における変数ダンプを記録および表示します。Laravel を使用している場合、変数はグローバル dump 関数を使用してダンプできます。ダンプが記録されるためには、ダンプウォッチャータブがブラウザで開いている必要があります。そうでない場合、ダンプはウォッチャーによって無視されます。

イベントウォッチャー

イベントウォッチャーは、アプリケーションによってディスパッチされたイベントのペイロード、リスナー、およびブロードキャストデータを記録します。Laravel フレームワークの内部イベントは、イベントウォッチャーによって無視されます。

例外ウォッチャー

例外ウォッチャーは、アプリケーションによってスローされた報告可能な例外のデータとスタックトレースを記録します。

ゲートウォッチャー

ゲートウォッチャーは、アプリケーションによるゲートおよびポリシーチェックのデータと結果を記録します。特定の能力をウォッチャーによって記録されないように除外したい場合は、ignore_abilities オプション内でそれらを指定できます:

'watchers' => [
   Watchers\GateWatcher::class => [
   'enabled' => env('TELESCOPE_GATE_WATCHER', true),
   'ignore_abilities' => ['viewNova'],
   ],
   ...
],

HTTP クライアントウォッチャー

HTTP クライアントウォッチャーは、アプリケーションによって行われた外部 HTTP クライアントリクエストを記録します。

ジョブウォッチャー

ジョブウォッチャーは、アプリケーションによってディスパッチされたジョブのデータとステータスを記録します。

ログウォッチャー

ログウォッチャーは、アプリケーションによって書き込まれたログデータを記録します。

デフォルトでは、Telescope は error レベル以上のログのみを記録します。ただし、アプリケーションの config/telescope.php 設定ファイル内の level オプションを変更することで、この動作を変更できます:

'watchers' => [
   Watchers\LogWatcher::class => [
   'enabled' => env('TELESCOPE_LOG_WATCHER', true),
   'level' => 'debug',
   ],
   // ...
],

メールウォッチャー

メールウォッチャーを使用すると、アプリケーションによって送信されたメールのブラウザ内プレビューとその関連データを表示できます。また、メールを .eml ファイルとしてダウンロードすることもできます。

モデルウォッチャー

モデルウォッチャーは、Eloquent モデルイベントがディスパッチされるたびにモデルの変更を記録します。ウォッチャーの events オプションを介して、どのモデルイベントを記録するかを指定できます:

'watchers' => [
   Watchers\ModelWatcher::class => [
   'enabled' => env('TELESCOPE_MODEL_WATCHER', true),
   'events' => ['eloquent.created*', 'eloquent.updated*'],
   ],
   ...
],

特定のリクエスト中に水和されたモデルの数を記録したい場合は、hydrations オプションを有効にします:

'watchers' => [
   Watchers\ModelWatcher::class => [
   'enabled' => env('TELESCOPE_MODEL_WATCHER', true),
   'events' => ['eloquent.created*', 'eloquent.updated*'],
   'hydrations' => true,
   ],
   ...
],

通知ウォッチャー

通知ウォッチャーは、アプリケーションによって送信されたすべての通知を記録します。通知がメールをトリガーし、メールウォッチャーが有効になっている場合、メールはメールウォッチャースクリーンでプレビュー可能になります。

クエリウォッチャー

クエリウォッチャーは、アプリケーションによって実行されるすべてのクエリの生 SQL、バインディング、および実行時間を記録します。ウォッチャーは、100 ミリ秒以上遅いクエリに slow タグを付けます。ウォッチャーの slow オプションを使用して、遅いクエリの閾値をカスタマイズできます:

'watchers' => [
   Watchers\QueryWatcher::class => [
   'enabled' => env('TELESCOPE_QUERY_WATCHER', true),
   'slow' => 50,
   ],
   ...
],

Redis ウォッチャー

Redis ウォッチャーは、アプリケーションによって実行されるすべての Redis コマンドを記録します。Redis をキャッシュに使用している場合、キャッシュコマンドも Redis ウォッチャーによって記録されます。

リクエストウォッチャー

リクエストウォッチャーは、アプリケーションによって処理されたリクエストに関連するリクエスト、ヘッダー、セッション、およびレスポンスデータを記録します。記録されるレスポンスデータを size_limit (キロバイト単位) オプションで制限できます:

'watchers' => [
   Watchers\RequestWatcher::class => [
   'enabled' => env('TELESCOPE_REQUEST_WATCHER', true),
   'size_limit' => env('TELESCOPE_RESPONSE_SIZE_LIMIT', 64),
   ],
   ...
],

スケジュールウォッチャー

スケジュールウォッチャーは、アプリケーションによって実行されるスケジュールされたタスクのコマンドと出力を記録します。

ビューウォッチャー

ビューウォッチャーは、ビューをレンダリングする際に使用されるビュー名、パス、データ、および「コンポーザー」を記録します。

ユーザーアバターの表示

Telescope ダッシュボードは、特定のエントリが保存されたときに認証されたユーザーのアバターを表示します。デフォルトでは、Telescope は Gravatar ウェブサービスを使用してアバターを取得します。ただし、App\Providers\TelescopeServiceProvider クラスにコールバックを登録することで、アバター URL をカスタマイズできます。コールバックはユーザーの ID とメールアドレスを受け取り、ユーザーのアバター画像 URL を返す必要があります:

use App\Models\User;
use Laravel\Telescope\Telescope;
/**
 * Register any application services.
 */
public function register(): void
{
   // ...
   Telescope::avatar(function (string $id, string $email) {
   return '/avatars/'.User::find($id)->avatar_path;
   });
}