Laravel Telescope

• イントロダクション
• インストール
  • ローカル限定インストール
  • 設定
  • データプルーニング
  • ダッシュボード認証
• Telescopeのアップグレード
• フィルタリング
  • エントリ
  • バッチ
• タグ付け
• 利用可能なウォッチャー
  • バッチウォッチャー
  • キャッシュウォッチャー
  • コマンドウォッチャー
  • ダンプウォッチャー
  • イベントウォッチャー
  • 例外ウォッチャー
  • ゲートウォッチャー
  • HTTPクライアントウォッチャー
  • ジョブウォッチャー
  • ログウォッチャー
  • メールウォッチャー
  • モデルウォッチャー
  • 通知ウォッチャー
  • クエリウォッチャー
  • Redisウォッチャー
  • リクエストウォッチャー
  • スケジュールウォッチャー
  • ビューウォッチャー
• ユーザーアバターの表示

イントロダクション

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

インストール

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

composer require laravel/telescope

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

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` に配置されます。この設定ファイルでは、ウォッチャーオプションを設定できます。各設定オプションにはその目的の説明が含まれているため、このファイルを thoroughly調べてください。

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

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

データプルーニング

プルーニングを行わないと、 `telescope_entries` テーブルにレコードが非常に schnellに蓄積される可能性があります。これを軽減するには、 `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, [
            '[email protected]',
        ]);
    });
}

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"
        ]
    }
}

フィルタリング

エントリ

`App\Providers\TelescopeServiceProvider` クラスで定義されている `filter` クロージャを介して、Telescopeによって記録されるデータをフィルタリングできます。デフォルトでは、このクロージャは `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がエントリに自動的に添付するタグとマージされます。通常、 `App\Providers\TelescopeServiceProvider` クラスの `register` メソッド内で `tag` メソッドを呼び出す必要があります

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コマンドが実行されるたびに、引数、オプション、終了コード、および出力を記録します。ウォッチャーによる記録から特定のコマンドを除外したい場合は、config/telescope.phpファイルのignoreオプションでコマンドを指定できます。

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

ダンプウォッチャー

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

イベントウォッチャー

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

例外ウォッチャー

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

ゲートウォッチャー

ゲートウォッチャーは、アプリケーションによるゲートおよびポリシーチェックのデータと結果を記録します。ウォッチャーによる記録から特定の権限を除外したい場合は、config/telescope.phpファイルの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 Webサービスを使用してアバターを取得します。ただし、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;
    });
}