Laravel Telescope

• Introduction
• Installation
  • Local Only Installation
  • Configuration
  • Data Pruning
  • Dashboard Authorization
• Upgrading Telescope
• Filtering
  • Entries
  • Batches
• Tagging
• Available Watchers
  • Batch Watcher
  • Cache Watcher
  • Command Watcher
  • Dump Watcher
  • Event Watcher
  • Exception Watcher
  • Gate Watcher
  • HTTP Client Watcher
  • Job Watcher
  • Log Watcher
  • Mail Watcher
  • Model Watcher
  • Notification Watcher
  • Query Watcher
  • Redis Watcher
  • Request Watcher
  • Schedule Watcher
  • View Watcher
• Displaying User Avatars

Introduction

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

Installation

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

composer require laravel/telescope

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

php artisan telescope:install

php artisan migrate

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

Local Only Installation

ローカル開発を支援するためにのみ 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') && class_exists(\Laravel\Telescope\TelescopeServiceProvider::class)) {
        $this->app->register(\Laravel\Telescope\TelescopeServiceProvider::class);
        $this->app->register(TelescopeServiceProvider::class);
    }
}

最後に、composer.json ファイルに以下を追加して、Telescope パッケージが auto-discovered になるのを防ぐ必要もあります。

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

Configuration

Telescope のアセットを公開すると、そのプライマリ構成ファイルは config/telescope.php に配置されます。この設定ファイルを使用すると、watcher options を設定できます。各構成オプションにはその目的の説明が含まれているため、このファイルをよく調べてください。

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

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

Data Pruning

プルーニングを行わない場合、telescope_entries テーブルは非常に迅速にレコードを蓄積できます。これを軽減するには、schedule 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();

Dashboard Authorization

Telescope ダッシュボードには、/telescope ルート経由でアクセスできます。デフォルトでは、local 環境でのみこのダッシュボードにアクセスできます。 app/Providers/TelescopeServiceProvider.php ファイル内には、authorization gate 定義があります。この認可ゲートは、非ローカル環境での 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]',
        ]);
    });
}

運用環境では、APP_ENV 環境変数を production に必ず変更する必要があります。そうしないと、Telescope のインストールが公開されてしまいます。

Upgrading Telescope

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

さらに、新しい 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"
        ]
    }
}

Filtering

Entries

Telescope によって記録されたデータは、App\Providers\TelescopeServiceProvider クラスで定義されている 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();
    });
}

Batches

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

Tagging

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

Available Watchers

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

バッチ ウォッチャーは、ジョブや接続情報など、キューに入れられた batches に関する情報を記録します。

Cache Watcher

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

Command Watcher

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

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

Dump Watcher

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

Event Watcher

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

Exception Watcher

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

Gate Watcher

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

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

HTTP Client Watcher

HTTP クライアント ウォッチャーは、アプリケーションによって作成された送信 HTTP client requests を記録します。

Job Watcher

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

Log Watcher

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

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

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

    // ...
],

Mail Watcher

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

Model Watcher

モデル ウォッチャーは、Eloquent model event がディスパッチされるたびに、モデルの変更を記録します。ウォッチャーの 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

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

Query Watcher

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

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

Redis Watcher

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

Request Watcher

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

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

Schedule Watcher

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

View Watcher

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

Displaying User Avatars

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