Laravel Telescope (Laravel Telescope)

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

導入 (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 ダッシュボードにアクセスできます。

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

ローカル開発を支援するためにのみ 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"
        ]
    }
},

構成

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

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

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

データのプルーニング

プルーニングを行わない場合、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();

ダッシュボードの認証

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

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

Telescopeのアップグレード (Upgrading 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"
        ]
    }
}

フィルタリング (Filtering)

エントリー

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

バッチ

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,
    ],
    ...
],

バッチウォッチャー

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

キャッシュウォッチャー

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

コマンドウォッチャー

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

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

ダンプウォッチャー

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

イベントウォッチャー

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

例外ウォッチャー

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

ゲートウォッチャー

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

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

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

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

ジョブウォッチャー

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

ログウォッチャー

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

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

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

    // ...
],

メールウォッチャー

メール ウォッチャーを使用すると、アプリケーションによって送信された emails とその関連データのブラウザー内プレビューを表示できます。電子メールを .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,
    ],
    ...
],

通知ウォッチャー

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

クエリウォッチャー

クエリ ウォッチャーは、アプリケーションによって実行されるすべてのクエリの生の 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),
    ],
    ...
],

スケジュールウォッチャー

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

ビューウォッチャー

ビュー ウォッチャーは、ビューのレンダリング時に使用される 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;
    });
}