Laravel Telescope¶

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

はじめに¶

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ルートから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であることを確認してからプロバイダを登録します：

/**
 * 任意のアプリケーションサービスを登録します。
 */
public function register(): void
{
    if ($this->app->environment('local')) {
        $this->app->register(\Laravel\Telescope\TelescopeServiceProvider::class);
        $this->app->register(TelescopeServiceProvider::class);
    }
}

最後に、Telescopeパッケージが自動検出されないように、composer.jsonファイルに以下を追加する必要があります：

"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;

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

Warning

本番環境では、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"
        ]
    }
}

フィルタリング¶

エントリ¶

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

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

/**
 * 任意のアプリケーションサービスを登録します。
 */
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;

/**
 * 任意のアプリケーションサービスを登録します。
 */
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;

/**
 * 任意のアプリケーションサービスを登録します。
 */
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,
    ],
    ...
],

Batch Watcher¶

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

Cache Watcher¶

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

Command Watcher¶

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

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

Dump Watcher¶

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

Event Watcher¶

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

Exception Watcher¶

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

Gate Watcher¶

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

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

HTTP Client Watcher¶

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

Job Watcher¶

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

Log Watcher¶

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

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

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

    // ...
],

Mail Watcher¶

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

Model Watcher¶

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 Watcher¶

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

Query Watcher¶

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

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

Redis Watcher¶

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

Request Watcher¶

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

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

Schedule Watcher¶

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

View Watcher¶

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

ユーザーアバターの表示¶

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

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

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

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

ユーザーノート

+ ユーザーノートを表示する