Laravel Telescope 9.x Laravel

イントロダクション

Laravel Telescope（テレスコープ、望遠鏡）は、ローカルLaravel開発環境の素晴らしい相棒になります。Telescopeは、アプリケーションが受信するリクエスト、例外、ログエントリ、データベースクエリ、キュー投入したジョブ、メール、通知、キャッシュ操作、スケジュール済みタスク、変数ダンプなどに関する眼力を与えてくれます。

インストレーション

Composerパッケージマネージャで、TelescopeをLaravelプロジェクトへインストールできます。

composer require laravel/telescope

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

php artisan telescope:install

php artisan migrate

マイグレーションのカスタマイズ

Telescopeのデフォルトのマイグレーションを使用しない場合は、アプリケーションのApp\Providers\AppServiceProviderクラスのregisterメソッドでTelescope::ignoreMigrationsメソッドを呼び出す必要があります。php artisan vendor:publish --tag=telescope-migrationsのコマンドで、デフォルトのマイグレーションをエクスポートできます。

ローカルのみへインストール

ローカル開発を支援するためにのみTelescopeの使用を計画している場合は、--devフラグを使用してTelescopeをインストールしてください。

composer require laravel/telescope --dev

php artisan telescope:install

php artisan migrate

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

/**
 * 全アプリケーションサービスの登録
 *
 * @return void
 */
public function register()
{
    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コマンドをスケジュールして毎日実行する必要があります。

$schedule->command('telescope:prune')->daily();

デフォルトでは、２４時間を過ぎているすべてのエンティティが削除されます。Telescopeデータをどの期間保持するかを指定するために、コマンド呼び出し時にhoursオプションが使えます。

$schedule->command('telescope:prune --hours=48')->daily();

ダッシュボードの認可

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

/**
 * Telescopeゲートの登録
 *
 * このゲートはlocal以外の環境で、誰がTelescopeへアクセスできるかを決定している。
 *
 * @return void
 */
protected function gate()
{
    Gate::define('viewTelescope', function ($user) {
        return in_array($user->email, [
            'taylor@laravel.com',
        ]);
    });
}

Warning!! 実行環境では、APP_ENV環境変数を必ずproductionに変更してください。それ以外の値の場合、Telescopeインストールは一般公開されます。

Telescopeのアップグレード

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

また、Telescopを新しいバージョンへアップグレードするときは、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が記録したデータは、App\Providers\TelescopeServiceProviderクラスで定義されているfilterクロージャを介してフィルタリングできます。デフォルトでは、このクロージャは、local環境のすべてのデータと、例外、失敗したジョブ、スケジュール済みタスク、および他のすべての環境の監視対象のデータをタグ付きで記録します。

use Laravel\Telescope\IncomingEntry;
use Laravel\Telescope\Telescope;

/**
 * 全アプリケーションサービスの登録
 *
 * @return void
 */
public function register()
{
    $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\Telescope;

/**
 * 全アプリケーションサービスの登録
 *
 * @return void
 */
public function register()
{
    $this->hideSensitiveRequestDetails();

    Telescope::filterBatch(function (Collection $entries) {
        if ($this->app->environment('local')) {
            return true;
        }

        return $entries->contains(function ($entry) {
            return $entry->isReportableException() ||
                $entry->isFailedJob() ||
                $entry->isScheduledTask() ||
                $entry->isSlowQuery() ||
                $entry->hasMonitoredTag();
            });
    });
}

タグ付け

Telescopeでは、「タグ」でエントリを検索できます。多くの場合、タグは、Telescopeがエントリに自動的に追加するEloquentモデルクラス名または認証済みユーザーIDです。場合によっては、独自のカスタムタグをエントリに添付することもできます。これを実現するために、Telescope::tagメソッドが使用できます。tagメソッドはクロージャを引数に取り、タグの配列を返す必要があります。クロージャが返すタグは、Telescopeがエントリに自動的に添付するタグとマージされます。通常、App\Providers\TelescopeServiceProviderクラスのregisterメソッド内でtagメソッドを呼び出す必要があります。

use Laravel\Telescope\IncomingEntry;
use Laravel\Telescope\Telescope;

/**
 * 全アプリケーションサービスの登録
 *
 * @return void
 */
public function register()
{
    $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,
    ],
    ...
],

Batchワッチャー

Batchワッチャーは、ジョブや接続情報など、キュー投入したバッチに関する情報を記録します。

Cacheワッチャー

Cacheワッチャーは、キャッシュキーのヒット、不一致、削除時にデータを記録します。

Commandワッチャー

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

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

Dumpワッチャー

Dumpワッチャーは、変数ダンプをTelescopeに記録して表示します。Laravelを使用すると、変数をグローバルなdump関数を使用してダンプできます。ダンプを記録するには、ブラウザで[Dumpワッチャー]タブを開いている必要があります。開いていない場合、ワッチャーはダンプを無視します。

Eventワッチャー

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

Exceptionワッチャー

Exceptionワッチャーは、アプリケーション投げた報告可能（reportable）な例外のデータとスタックトレースを記録します。

Gateワッチャー

Gateワッチャーは、アプリケーションによるゲートとポリシーチェックのデータと結果を記録します。ワッチャーによる記録から特定のアビリティを除外したい場合は、config/telescope.phpファイルのignore_abilitiesオプションで指定できます。

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

HTTPクライアントワッチャー

HTTPクライアントウォッチャーは、アプリケーションが作成したHTTPクライアントリクエストを記録します。

Jobワッチャー

Jobワッチャーは、アプリケーションがディスパッチしたジョブのデータとステータスを記録します。

Logワッチャー

Logワッチャーは、アプリケーションが書き混んだログデータを記録します。

Mailワッチャー

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

Modelワッチャー

Modelワッチャーは、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,
    ],
    ...
],

Notificationワッチャー

Notificationワッチャーは、アプリケーションから送信されたすべての通知を記録します。通知によって電子メールがトリガーされ、メールワッチャーが有効になっている場合、その電子メールはワッチャー画面でプレビューすることもできます。

Queryワッチャー

Queryワッチャーは、アプリケーションが実行するすべてのクエリの素のSQL、バインディング、および実行時間を記録します。ワッチャーは、100ミリ秒より遅いクエリへslowというタグを付けます。ウォッチャーのslowオプションを使用して、低速クエリのしきい値をカスタマイズできます。

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

Redisワッチャー

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

Requestワッチャー

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

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

Scheduleワッチャー

Scheduleワッチャーは、アプリケーションが実行したスケジュール済みタスクのコマンドと出力を記録します。

Viewワッチャー

Viewワッチャーは、ビューのレンダリング時に使用するビューの名前、パス、データ、および「コンポーザ」を記録します。

ユーザーアバターの表示

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

use App\Models\User;
use Laravel\Telescope\Telescope;

/**
 * 全アプリケーションサービスの登録
 *
 * @return void
 */
public function register()
{
    // ...

    Telescope::avatar(function ($id, $email) {
        return '/avatars/'.User::find($id)->avatar_path;
    });
}

Laravel 9.x Laravel Telescope