Laravel Telescope

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

イントロダクション

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

インストール

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

1composer require laravel/telescope

composer require laravel/telescope

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

1php artisan telescope:install
2 
3php artisan migrate

php artisan telescope:install

php artisan migrate

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

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

Telescopeをローカル開発の補助としてのみ使用する場合は、--devフラグを使用してTelescopeをインストールできます。

1composer require laravel/telescope --dev
2 
3php artisan telescope:install
4 
5php artisan migrate

composer require laravel/telescope --dev

php artisan telescope:install

php artisan migrate

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

 1/**
 2 * Register any application services.
 3 */
 4public function register(): void
 5{
 6    if ($this->app->environment('local') && class_exists(\Laravel\Telescope\TelescopeServiceProvider::class)) {
 7        $this->app->register(\Laravel\Telescope\TelescopeServiceProvider::class);
 8        $this->app->register(TelescopeServiceProvider::class);
 9    }
10}

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

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

1"extra": {
2    "laravel": {
3        "dont-discover": [
4            "laravel/telescope"
5        ]
6    }
7},

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

設定

Telescopeのアセットを公開すると、その主要な設定ファイルがconfig/telescope.phpに配置されます。この設定ファイルを使用すると、ウォッチャーのオプションを設定できます。各設定オプションにはその目的の説明が含まれているので、このファイルを徹底的に調べてください。

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

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

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

データ整理

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

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

use Illuminate\Support\Facades\Schedule;

Schedule::command('telescope:prune')->daily();

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

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

use Illuminate\Support\Facades\Schedule;

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

ダッシュボードの認可

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

 1use App\Models\User;
 2 
 3/**
 4 * Register the Telescope gate.
 5 *
 6 * This gate determines who can access Telescope in non-local environments.
 7 */
 8protected function gate(): void
 9{
10    Gate::define('viewTelescope', function (User $user) {
11        return in_array($user->email, [
12            '[email protected]',
13        ]);
14    });
15}

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

本番環境では、APP_ENV環境変数をproductionに変更することを確実にしてください。そうしないと、Telescopeのインストールが公開されてしまいます。

Telescopeのアップグレード

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

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

1php artisan telescope:publish

php artisan telescope:publish

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

1{
2    "scripts": {
3        "post-update-cmd": [
4            "@php artisan vendor:publish --tag=laravel-assets --ansi --force"
5        ]
6    }
7}

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

フィルタリング

エントリ

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

 1use Laravel\Telescope\IncomingEntry;
 2use Laravel\Telescope\Telescope;
 3 
 4/**
 5 * Register any application services.
 6 */
 7public function register(): void
 8{
 9    $this->hideSensitiveRequestDetails();
10 
11    Telescope::filter(function (IncomingEntry $entry) {
12        if ($this->app->environment('local')) {
13            return true;
14        }
15 
16        return $entry->isReportableException() ||
17            $entry->isFailedJob() ||
18            $entry->isScheduledTask() ||
19            $entry->isSlowQuery() ||
20            $entry->hasMonitoredTag();
21    });
22}

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によって記録されます。

 1use Illuminate\Support\Collection;
 2use Laravel\Telescope\IncomingEntry;
 3use Laravel\Telescope\Telescope;
 4 
 5/**
 6 * Register any application services.
 7 */
 8public function register(): void
 9{
10    $this->hideSensitiveRequestDetails();
11 
12    Telescope::filterBatch(function (Collection $entries) {
13        if ($this->app->environment('local')) {
14            return true;
15        }
16 
17        return $entries->contains(function (IncomingEntry $entry) {
18            return $entry->isReportableException() ||
19                $entry->isFailedJob() ||
20                $entry->isScheduledTask() ||
21                $entry->isSlowQuery() ||
22                $entry->hasMonitoredTag();
23            });
24    });
25}

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メソッドを呼び出す必要があります。

 1use Laravel\Telescope\IncomingEntry;
 2use Laravel\Telescope\Telescope;
 3 
 4/**
 5 * Register any application services.
 6 */
 7public function register(): void
 8{
 9    $this->hideSensitiveRequestDetails();
10 
11    Telescope::tag(function (IncomingEntry $entry) {
12        return $entry->type === 'request'
13            ? ['status:'.$entry->content['response_status']]
14            : [];
15    });
16}

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設定ファイル内でカスタマイズできます。

1'watchers' => [
2    Watchers\CacheWatcher::class => true,
3    Watchers\CommandWatcher::class => true,
4    // ...
5],

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

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

1'watchers' => [
2    Watchers\QueryWatcher::class => [
3        'enabled' => env('TELESCOPE_QUERY_WATCHER', true),
4        'slow' => 100,
5    ],
6    // ...
7],

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

バッチウォッチャー

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

キャッシュウォッチャー

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

コマンドウォッチャー

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

1'watchers' => [
2    Watchers\CommandWatcher::class => [
3        'enabled' => env('TELESCOPE_COMMAND_WATCHER', true),
4        'ignore' => ['key:generate'],
5    ],
6    // ...
7],

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

ダンプウォッチャー

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

イベントウォッチャー

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

例外ウォッチャー

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

ゲートウォッチャー

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

1'watchers' => [
2    Watchers\GateWatcher::class => [
3        'enabled' => env('TELESCOPE_GATE_WATCHER', true),
4        'ignore_abilities' => ['viewNova'],
5    ],
6    // ...
7],

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

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

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

ジョブウォッチャー

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

ログウォッチャー

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

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

1'watchers' => [
2    Watchers\LogWatcher::class => [
3        'enabled' => env('TELESCOPE_LOG_WATCHER', true),
4        'level' => 'debug',
5    ],
6 
7    // ...
8],

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

    // ...
],

メールウォッチャー

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

モデルウォッチャー

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

1'watchers' => [
2    Watchers\ModelWatcher::class => [
3        'enabled' => env('TELESCOPE_MODEL_WATCHER', true),
4        'events' => ['eloquent.created*', 'eloquent.updated*'],
5    ],
6    // ...
7],

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

特定のリクエスト中にハイドレートされたモデルの数を記録したい場合は、hydrationsオプションを有効にしてください。

1'watchers' => [
2    Watchers\ModelWatcher::class => [
3        'enabled' => env('TELESCOPE_MODEL_WATCHER', true),
4        'events' => ['eloquent.created*', 'eloquent.updated*'],
5        'hydrations' => true,
6    ],
7    // ...
8],

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

通知ウォッチャー

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

クエリウォッチャー

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

1'watchers' => [
2    Watchers\QueryWatcher::class => [
3        'enabled' => env('TELESCOPE_QUERY_WATCHER', true),
4        'slow' => 50,
5    ],
6    // ...
7],

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

Redisウォッチャー

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

リクエストウォッチャー

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

1'watchers' => [
2    Watchers\RequestWatcher::class => [
3        'enabled' => env('TELESCOPE_REQUEST_WATCHER', true),
4        'size_limit' => env('TELESCOPE_RESPONSE_SIZE_LIMIT', 64),
5    ],
6    // ...
7],

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

 1use App\Models\User;
 2use Laravel\Telescope\Telescope;
 3 
 4/**
 5 * Register any application services.
 6 */
 7public function register(): void
 8{
 9    // ...
10 
11    Telescope::avatar(function (string $id, string $email) {
12        return '/avatars/'.User::find($id)->avatar_path;
13    });
14}

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;
    });
}

序文

はじめに

アーキテクチャのコンセプト

基本

より深く知る

セキュリティ

データベース

Eloquent ORM

テスト

パッケージ

Laravel Telescope

製品

パッケージ

リソース