Laravel 11.x Laravel Telescope

イントロダクションIntroduction

Laravel Telescope（テレスコープ、望遠鏡）は、ローカルLaravel開発環境の素晴らしい相棒になります。Telescopeは、アプリケーションが受信するリクエスト、例外、ログエントリ、データベースクエリ、キュー投入したジョブ、メール、通知、キャッシュ操作、スケジュール済みタスク、変数ダンプなどに関する眼力を与えてくれます。Laravel Telescope[https://github.com/laravel/telescope] makes a wonderful companion to your local Laravel development environment. Telescope provides insight into the requests coming into your application, exceptions, log entries, database queries, queued jobs, mail, notifications, cache operations, scheduled tasks, variable dumps, and more.

インストレーションInstallation

Composerパッケージマネージャで、TelescopeをLaravelプロジェクトへインストールできます。You may use the Composer package manager to install Telescope into your Laravel project:

composer require laravel/telescope

Telescopeをインストールしたら、telescope:install Artisanコマンドを使用し、アセットとマイグレーションをリソース公開します。Telescopeをインストールした後、Telescopeのデータを格納するために必要なテーブルを作成するため、migrateコマンドも実行する必要があります。After installing Telescope, publish its assets and migrations using the telescope:install Artisan command. After installing Telescope, you should also run the migrate command in order to create the tables needed to store Telescope's data:

php artisan telescope:install

php artisan migrate

これで、/telescopeにより、Telescopeダッシュボードへアクセスできます。Finally, you may access the Telescope dashboard via the /telescope route.

ローカルのみへインストールLocal Only Installation

ローカル開発を支援するためにのみTelescopeの使用を計画している場合は、--devフラグを使用してTelescopeをインストールしてください。If you plan to only use Telescope to assist your local development, you may install Telescope using the --dev flag:

composer require laravel/telescope --dev

php artisan telescope:install

php artisan migrate

telescope:installを実行した後、アプリケーションのbootstrap/providers.php設定ファイルから、TelescopeServiceProviderサービスプロバイダ登録を削除してください。代わりに、App\Providers\AppServiceProviderクラスのregisterメソッドで、Telescopeのサービスプロバイダを登録します。プロバイダを登録する前に、現在の環境がlocalであることを確認してください。After running telescope:install, you should remove the TelescopeServiceProvider service provider registration from your application's bootstrap/providers.php configuration file. Instead, manually register Telescope's service providers in the register method of your App\Providers\AppServiceProvider class. We will ensure the current environment is local before registering the providers:

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

最後に、composer.jsonファイルに以下を追加して、Telescopeパッケージが自動検出されないようにする必要もあります。Finally, you should also prevent the Telescope package from being auto-discovered[/docs/{{version}}/packages#package-discovery] by adding the following to your composer.json file:

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

設定Configuration

Telescopeのアセットをリソース公開すると、そのプライマリ設定ファイルはconfig/telescope.phpへ配置されます。この設定ファイルを使用すると、ワッチャーオプションを設定できます。各設定オプションにはその目的が説明されているため、このファイルを徹底的に調べてください。After publishing Telescope's assets, its primary configuration file will be located at config/telescope.php. This configuration file allows you to configure your watcher options[#available-watchers]. Each configuration option includes a description of its purpose, so be sure to thoroughly explore this file.

望むのであれば、enabled設定オプションを使用し、Telescopeのデータ収集全体を無効にできます。If desired, you may disable Telescope's data collection entirely using the enabled configuration option:

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

データの整理Data Pruning

データの整理を行わないと、telescope_entriesテーブルにレコードがあっという間に溜まります。これを軽減するに、telescope:prune Artisanコマンドをスケジュールして毎日実行する必要があります。Without pruning, the telescope_entries table can accumulate records very quickly. To mitigate this, you should schedule[/docs/{{version}}/scheduling] the telescope:prune Artisan command to run daily:

use Illuminate\Support\Facades\Schedule;

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

デフォルトでは、２４時間を過ぎているすべてのエンティティが削除されます。Telescopeデータをどの期間保持するかを指定するために、コマンド呼び出し時にhoursオプションが使えます。By default, all entries older than 24 hours will be pruned. You may use the hours option when calling the command to determine how long to retain Telescope data. For example, the following command will delete all records created over 48 hours ago:

use Illuminate\Support\Facades\Schedule;

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

ダッシュボードの認可Dashboard Authorization

Telescopeダッシュボードは、/telescopeルートでアクセスできます。デフォルトでは、このダッシュボードにアクセスできるのはlocal環境のみです。app/Providers/TelescopeServiceProvider.phpファイル内に、認可ゲートの定義があります。この認証ゲートは、非ローカル環境でのTelescopeへのアクセスを制御します。Telescopeの設置へのアクセスを制限するために、必要に応じてこのゲートを自由に変更できます。The Telescope dashboard may be accessed via the /telescope route. By default, you will only be able to access this dashboard in the local environment. Within your app/Providers/TelescopeServiceProvider.php file, there is an authorization gate[/docs/{{version}}/authorization#gates] definition. This authorization gate controls access to Telescope in non-local environments. You are free to modify this gate as needed to restrict access to your Telescope installation:

use App\Models\User;

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

warning Warning! 実行環境では、APP_ENV環境変数を必ずproductionに変更してください。それ以外の値の場合、Telescopeインストールは一般公開されます。[!WARNING]
You should ensure you change your APP_ENV environment variable to production in your production environment. Otherwise, your Telescope installation will be publicly available.

TelescopeのアップグレードUpgrading Telescope

新しいメジャーバージョンのTelescopeへアップグレードするときは、アップグレードガイドを注意深く読むことが重要です。When upgrading to a new major version of Telescope, it's important that you carefully review the upgrade guide[https://github.com/laravel/telescope/blob/master/UPGRADE.md].

また、Telescopを新しいバージョンへアップグレードするときは、Telescopeのアセットを必ず再リソース公開してください。In addition, when upgrading to any new Telescope version, you should re-publish Telescope's assets:

php artisan telescope:publish

アセットを最新状態に保ち、将来のアップデートで起きる問題を防ぐために、アプリケーションのcomposer.jsonファイルのpost-update-cmdスクリプトへ、vendor:publish --tag=laravel-assetsコマンドを追加しておくのが良いでしょう。To keep the assets up-to-date and avoid issues in future updates, you may add the vendor:publish --tag=laravel-assets command to the post-update-cmd scripts in your application's composer.json file:

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

フィルタリングFiltering

エンティティEntries

Telescopeが記録したデータは、App\Providers\TelescopeServiceProviderクラスで定義されているfilterクロージャを介してフィルタリングできます。デフォルトでは、このクロージャは、local環境のすべてのデータと、例外、失敗したジョブ、スケジュール済みタスク、および他のすべての環境の監視対象のデータをタグ付きで記録します。You may filter the data that is recorded by Telescope via the filter closure that is defined in your App\Providers\TelescopeServiceProvider class. By default, this closure records all data in the local environment and exceptions, failed jobs, scheduled tasks, and data with monitored tags in all other environments:

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

バッチBatches

filterクロージャは個々のエントリのデータをフィルタリングしますが、filterBatchメソッドを使用して、特定のリクエストまたはコンソールコマンドのすべてのデータをフィルタリングするクロージャを登録できます。クロージャがtrueを返す場合、すべてのエントリはTelescopeによって記録されます。While the filter closure filters data for individual entries, you may use the filterBatch method to register a closure that filters all data for a given request or console command. If the closure returns true, all of the entries are recorded by 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();
            });
    });
}

タグ付けTagging

Telescopeでは、「タグ」でエントリを検索できます。多くの場合、タグは、Telescopeがエントリに自動的に追加するEloquentモデルクラス名または認証済みユーザーIDです。場合によっては、独自のカスタムタグをエントリに添付することもできます。これを実現するために、Telescope::tagメソッドが使用できます。tagメソッドはクロージャを引数に取り、タグの配列を返す必要があります。クロージャが返すタグは、Telescopeがエントリに自動的に添付するタグとマージされます。通常、App\Providers\TelescopeServiceProviderクラスのregisterメソッド内でtagメソッドを呼び出す必要があります。Telescope allows you to search entries by "tag". Often, tags are Eloquent model class names or authenticated user IDs which Telescope automatically adds to entries. Occasionally, you may want to attach your own custom tags to entries. To accomplish this, you may use the Telescope::tag method. The tag method accepts a closure which should return an array of tags. The tags returned by the closure will be merged with any tags Telescope would automatically attach to the entry. Typically, you should call the tag method within the register method of your App\Providers\TelescopeServiceProvider class:

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

利用可能なワッチャーAvailable Watchers

Telescopeの「ワッチャー」は、リクエストまたはコンソールコマンドが実行されると、アプリケーションデータを収集します。config/telescope.php設定ファイル内で有効にしたいワッチャーのリストをカスタマイズできます。Telescope "watchers" gather application data when a request or console command is executed. You may customize the list of watchers that you would like to enable within your config/telescope.php configuration file:

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

いくつかのワッチャーには、追加のカスタマイズオプションを用意しています。Some watchers also allow you to provide additional customization options:

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

BatchワッチャーBatch Watcher

Batchワッチャーは、ジョブや接続情報など、キュー投入したバッチに関する情報を記録します。The batch watcher records information about queued batches[/docs/{{version}}/queues#job-batching], including the job and connection information.

CacheワッチャーCache Watcher

Cacheワッチャーは、キャッシュキーのヒット、不一致、削除時にデータを記録します。The cache watcher records data when a cache key is hit, missed, updated and forgotten.

CommandワッチャーCommand Watcher

Commandワッチャーは、Artisanコマンドが実行されるたびに、引数、オプション、終了コード、および出力を記録します。ワッチャーによる記録から特定のコマンドを除外したい場合は、config/telescope.phpファイル内のignoreオプションでコマンドを指定できます。The command watcher records the arguments, options, exit code, and output whenever an Artisan command is executed. If you would like to exclude certain commands from being recorded by the watcher, you may specify the command in the ignore option within your config/telescope.php file:

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

DumpワッチャーDump Watcher

Dumpワッチャーは、変数ダンプをTelescopeに記録して表示します。Laravelを使用すると、変数をグローバルなdump関数を使用してダンプできます。ダンプを記録するには、ブラウザで[Dumpワッチャー]タブを開いている必要があります。開いていない場合、ワッチャーはダンプを無視します。The dump watcher records and displays your variable dumps in Telescope. When using Laravel, variables may be dumped using the global dump function. The dump watcher tab must be open in a browser for the dump to be recorded, otherwise, the dumps will be ignored by the watcher.

EventワッチャーEvent Watcher

Eventワッチャーは、アプリケーションがディスパッチしたイベントのペイロード、リスナ、およびブロードキャストデータを記録します。Laravelフレームワークの内部イベントをEventワッチャーは無視します。The event watcher records the payload, listeners, and broadcast data for any events[/docs/{{version}}/events] dispatched by your application. The Laravel framework's internal events are ignored by the Event watcher.

ExceptionワッチャーException Watcher

Exceptionワッチャーは、アプリケーション投げた報告可能（reportable）な例外のデータとスタックトレースを記録します。The exception watcher records the data and stack trace for any reportable exceptions that are thrown by your application.

GateワッチャーGate Watcher

Gateワッチャーは、アプリケーションによるゲートとポリシーチェックのデータと結果を記録します。ワッチャーによる記録から特定のアビリティを除外したい場合は、config/telescope.phpファイルのignore_abilitiesオプションで指定できます。The gate watcher records the data and result of gate and policy[/docs/{{version}}/authorization] checks by your application. If you would like to exclude certain abilities from being recorded by the watcher, you may specify those in the ignore_abilities option in your config/telescope.php file:

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

HTTPクライアントワッチャーHTTP Client Watcher

HTTPクライアントウォッチャーは、アプリケーションが作成したHTTPクライアントリクエストを記録します。The HTTP client watcher records outgoing HTTP client requests[/docs/{{version}}/http-client] made by your application.

JobワッチャーJob Watcher

Jobワッチャーは、アプリケーションがディスパッチしたジョブのデータとステータスを記録します。The job watcher records the data and status of any jobs[/docs/{{version}}/queues] dispatched by your application.

LogワッチャーLog Watcher

Logワッチャーは、アプリケーションが書き混んだログデータを記録します。The log watcher records the log data[/docs/{{version}}/logging] for any logs written by your application.

Telescopeは、デフォルトでerrorレベル以上のログしか記録しません。しかし、アプリケーションのconfig/telescope.php設定ファイルのlevelオプションを変更することで、この動作を変更できます。By default, Telescope will only record logs at the error level and above. However, you can modify the level option in your application's config/telescope.php configuration file to modify this behavior:

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

    // ...
],

MailワッチャーMail Watcher

Mailワッチャーを使用すると、アプリケーションから送信したメールのブラウザ内プレビューと関連するデータを表示できます。メールを .emlファイルとしてダウンロードすることもできます。The mail watcher allows you to view an in-browser preview of emails[/docs/{{version}}/mail] sent by your application along with their associated data. You may also download the email as an .eml file.

ModelワッチャーModel Watcher

Modelワッチャーは、Eloquentモデルイベントがディスパッチされるたびにモデルの変更を記録します。ワッチャーのeventsオプションを使用して、記録するモデルイベントを指定できます。The model watcher records model changes whenever an Eloquent model event[/docs/{{version}}/eloquent#events] is dispatched. You may specify which model events should be recorded via the watcher's events option:

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

特定のリクエスト中にハイドレートされたモデルの数を記録する場合は、hydrationsオプションを有効にします。If you would like to record the number of models hydrated during a given request, enable the hydrations option:

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

NotificationワッチャーNotification Watcher

Notificationワッチャーは、アプリケーションから送信されたすべての通知を記録します。通知によって電子メールがトリガーされ、メールワッチャーが有効になっている場合、その電子メールはワッチャー画面でプレビューすることもできます。The notification watcher records all notifications[/docs/{{version}}/notifications] sent by your application. If the notification triggers an email and you have the mail watcher enabled, the email will also be available for preview on the mail watcher screen.

QueryワッチャーQuery Watcher

Queryワッチャーは、アプリケーションが実行するすべてのクエリの素のSQL、バインディング、および実行時間を記録します。ワッチャーは、100ミリ秒より遅いクエリへslowというタグを付けます。ウォッチャーのslowオプションを使用して、低速クエリのしきい値をカスタマイズできます。The query watcher records the raw SQL, bindings, and execution time for all queries that are executed by your application. The watcher also tags any queries slower than 100 milliseconds as slow. You may customize the slow query threshold using the watcher's slow option:

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

RedisワッチャーRedis Watcher

Redisワッチャーは、アプリケーションが実行したすべてのRedisコマンドを記録します。キャッシュにRedisを使用している場合、キャッシュコマンドもRedisワッチャーは記録します。The Redis watcher records all Redis[/docs/{{version}}/redis] commands executed by your application. If you are using Redis for caching, cache commands will also be recorded by the Redis watcher.

RequestワッチャーRequest Watcher

Requestワッチャーは、アプリケーションが処理してリクエストに関連したリクエスト、ヘッダ、セッション、およびレスポンスデータを記録します。size_limit(キロバイト単位)オプションを使用して、記録するレスポンスデータを制限できます。The request watcher records the request, headers, session, and response data associated with any requests handled by the application. You may limit your recorded response data via the size_limit (in kilobytes) option:

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

ScheduleワッチャーSchedule Watcher

Scheduleワッチャーは、アプリケーションが実行したスケジュール済みタスクのコマンドと出力を記録します。The schedule watcher records the command and output of any scheduled tasks[/docs/{{version}}/scheduling] run by your application.

ViewワッチャーView Watcher

Viewワッチャーは、ビューのレンダリング時に使用するビューの名前、パス、データ、および「コンポーザ」を記録します。The view watcher records the view[/docs/{{version}}/views] name, path, data, and "composers" used when rendering views.

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

Telescopeダッシュボードでは、特定のエントリが保存されたときに認証されていたユーザーのユーザーアバターが表示されます。デフォルトでTelescopeはGravatarWebサービスを使用してアバターを取得します。ただし、App\Providers\TelescopeServiceProviderクラスにコールバックを登録することで、アバターのURLをカスタマイズもできます。コールバックはユーザーのIDとメールアドレスを受け取り、ユーザーのアバター画像のURLを返す必要があります。The Telescope dashboard displays the user avatar for the user that was authenticated when a given entry was saved. By default, Telescope will retrieve avatars using the Gravatar web service. However, you may customize the avatar URL by registering a callback in your App\Providers\TelescopeServiceProvider class. The callback will receive the user's ID and email address and should return the user's avatar image 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;
    });
}