バージョン: 9.x

Laravel Telescope (Laravel Telescope)

Introduction
Installation
Telescopeのアップグレード
Filtering
- Entries
- Batches
Tagging
利用可能なウォッチャー
ユーザーアバターの表示

導入 (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 のデフォルトの移行を使用しない場合は、アプリケーションの 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 サービスプロバイダの登録を削除する必要があります。代わりに、App\Providers\AppServiceProvider クラスの register メソッドで Telescope のサービスプロバイダを手動で登録します。プロバイダを登録する前に、現在の環境が local であることを確認します。

/**
 * Register any application services.
 *
 * @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 パッケージが 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 コマンドを毎日実行する必要があります。

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

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

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

ダッシュボードの認証

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

/**
 * Register the Telescope gate.
 *
 * This gate determines who can access Telescope in non-local environments.
 *
 * @return void
 */
protected function gate()
{
    Gate::define('viewTelescope', function ($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.
 *
 * @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;

/**
 * Register any application services.
 *
 * @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();
            });
    });
}

タグ付け (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.
 *
 * @return void
 */
public function register()
{
    $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 のデータとステータスを記録します。

ログウォッチャー

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

メールウォッチャー

メールウォッチャーを使用すると、アプリケーションによって送信された 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.
 *
 * @return void
 */
public function register()
{
    // ...

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

導入 (Introduction)​

インストール (Installation)​

移行のカスタマイズ​

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

構成​

データのプルーニング​

ダッシュボードの認証​

Telescopeのアップグレード (Upgrading Telescope)​

フィルタリング (Filtering)​

エントリー​

バッチ​

タグ付け (Tagging)​

利用可能なウォッチャー (Available Watchers)​

バッチウォッチャー​

キャッシュウォッチャー​

コマンドウォッチャー​

ダンプウォッチャー​

イベントウォッチャー​

例外ウォッチャー​

ゲートウォッチャー​

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

ジョブウォッチャー​

ログウォッチャー​

メールウォッチャー​

モデルウォッチャー​

通知ウォッチャー​

クエリウォッチャー​

Redis ウォッチャー​

リクエストウォッチャー​

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

ビューウォッチャー​

ユーザーアバターの表示 (Displaying User Avatars)​