Laravel 7.x Laravel Telescope

イントロダクションIntroduction

Laravel TelescopeはLaravelフレームワークのエレガントなデバッグアシスタントです。Telescopeはアプリケーションへ送信されたリクエスト、例外、ログエンティティ、データクエリ、キュージョブ、メール、通知、キャッシュ操作、スケジュールされたタスク、さまざまなダンプなどを提示します。TelescopeはLaravelローカル開発環境における、素晴らしいコンパニオンです。Laravel Telescope is an elegant debug assistant for the Laravel framework. 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. Telescope makes a wonderful companion to your local Laravel development environment.

インストレーションInstallation

LaravelプロジェクトへTelescopeをインストールするには、Composerを使用します。You may use Composer to install Telescope into your Laravel project:

composer require laravel/telescope

Telescopeをインストールしたら、telescope:install Artisanコマンドを使用し、アセットをリソース公開してください。Telescopeのインストールが終わったら、migrateコマンドも実行する必要があります。After installing Telescope, publish its assets using the telescope:install Artisan command. After installing Telescope, you should also run the migrate command:

php artisan telescope:install

php artisan migrate

特定の環境でのみのインストレーションInstalling Only In Specific Environments

Telescopeをローカル環境でのみ使用する場合は、--devフラグを付けてインストールします。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

telescope:install実行後、app設定ファイルからTelescopeServiceProviderサービスプロバイダの登録を削除する必要があります。app設定ファイルで登録する代わりに、このサービスプロバイダをAppServiceProviderのregisterメソッドで登録してください。After running telescope:install, you should remove the TelescopeServiceProvider service provider registration from your app configuration file. Instead, manually register the service provider in the register method of your AppServiceProvider:

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

また、composer.jsonへ以下の内容を追加することにより、Telescopeが自動検出されるのを防げます。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"
        ]
    }
},

マイグレーションのカスタマイズMigration Customization

Telescopeのデフォルトマイグレーションに従わない場合、AppServiceProviderのregisterメソッドの中で、Telescope::ignoreMigrationsメソッドを呼び出す必要があります。php artisan vendor:publish --tag=telescope-migrationsコマンドを使い、デフォルトマイグレーションをエクスポートすることもできます。If you are not going to use Telescope's default migrations, you should call the Telescope::ignoreMigrations method in the register method of your AppServiceProvider. You may export the default migrations using the php artisan vendor:publish --tag=telescope-migrations command.

設定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 and 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 the telescope:prune Artisan command to run daily:

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

デフォルトでは、24時間を過ぎているすべてのエンティティが削除されます。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:

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

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

Telescopeはデフォルトで、ダッシュボードを/telescopeで表示します。デフォルトではlocal環境からのみ、このダッシュボードへアクセスできます。app/Providers/TelescopeServiceProvider.phpファイルの中に、gateメソッドが存在しています。この認可ゲートで、Telescopeのlocal以外でのアクセスをコントロールできます。Telescopeに対するアクセスを宣言する必要に応じ、このゲートを自由に変更してください。Telescope exposes a dashboard at /telescope. By default, you will only be able to access this dashboard in the local environment. Within your app/Providers/TelescopeServiceProvider.php file, there is a gate method. 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:

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

Note: note 実行環境では、APP_ENV環境変数を必ずproductionに変更してください。それ以外の値の場合、Telescopeインストールは一般公開されます。{note} 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

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

php artisan telescope:publish

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

{
    "scripts": {
        "post-update-cmd": [
            "@php artisan telescope:publish --ansi"
        ]
    }
}

フィルタリングFiltering

エンティティEntries

TelescopeServiceProviderの中で登録されているfilterコールバックにより、Telescopeが保存するデータをフィルタリングできます。デフォルトでは、このコールバックはlocal環境、例外、失敗したジョブ、スケジュール済みタスク、他の全環境においてモニター対象とタグ付けされたデータを記録します。You may filter the data that is recorded by Telescope via the filter callback that is registered in your TelescopeServiceProvider. By default, this callback records all data in the local environment and exceptions, failed jobs, scheduled tasks, and data with monitored tags in all other environments:

/**
 * 全アプリケーションサービスの登録
 *
 * @return void
 */
public function register()
{
    $this->hideSensitiveRequestDetails();

    Telescope::filter(function (IncomingEntry $entry) {
        if ($this->app->isLocal()) {
            return true;
        }

        return $entry->isReportableException() ||
            $entry->isFailedJob() ||
            $entry->isScheduledTask() ||
            $entry->hasMonitoredTag();
    });
}

バッチBatches

fileterコールバックで個別のエンティティのデータをフィルタリングできますが、指定したリクエストやコンソールコマンドの全データをフィルタリングするコールバックをfilterBatchメソッドにより登録できます。コールバックがtrueを返すと、Telescopeによりすべてのエンティティが保存されます。While the filter callback filters data for individual entries, you may use the filterBatch method to register a callback that filters all data for a given request or console command. If the callback returns true, all of the entries are recorded by Telescope:

use Illuminate\Support\Collection;

/**
 * 全アプリケーションサービスの登録
 *
 * @return void
 */
public function register()
{
    $this->hideSensitiveRequestDetails();

    Telescope::filterBatch(function (Collection $entries) {
        if ($this->app->isLocal()) {
            return true;
        }

        return $entries->contains(function ($entry) {
            return $entry->isReportableException() ||
                $entry->isFailedJob() ||
                $entry->isScheduledTask() ||
                $entry->hasMonitoredTag();
            });
    });
}

タグ付けTagging

Telescopeでは「タグ」により検索を登録できます。タグはEloquentモデルクラス名や認証済みユーザーのIDが多いでしょうが、Telescopeは自動的にエントリーを登録します。まれに、独自のカスタムタグエントリーを追加する必要も起きるでしょう。その場合は、Telescope::tagメソッドを使用してください。tagメソッドはタグの配列を返すコールバックを引数に取ります。コールバックから返されたタグは、Telescopeが自動的にエントリーに追加したタグとマージされます。tagメソッドは、TelescopeServiceProviderの中で呼び出してください。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 callback which should return an array of tags. The tags returned by the callback will be merged with any tags Telescope would automatically attach to the entry. You should call the tag method within your TelescopeServiceProvider:

use Laravel\Telescope\Telescope;

/**
 * 全アプリケーションサービスの登録
 *
 * @return void
 */
public function register()
{
    $this->hideSensitiveRequestDetails();

    Telescope::tag(function (IncomingEntry $entry) {
        if ($entry->type === 'request') {
            return ['status:'.$entry->content['response_status']];
        }

        return [];
    });
 }

利用可能なワッチャー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,
    ],
    ...
],

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 in 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 recording to occur, otherwise the dumps will be ignored by the watcher.

EventワッチャーEvent Watcher

Eventワッチャーは、アプリケーションで発行されたすべてのイベントのペイロード（本体）、リスナ、ブロードキャストデータを記録します。Eventワッチャーは、Laravelフレームワーク内部のイベントを無視します。The event watcher records the payload, listeners, and broadcast data for any 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 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'],
    ],
    ...
],

JobワッチャーJob Watcher

Jobワッチャーは、アプリケーションでディスパッチされた全ジョブのデータと状態を記録します。The job watcher records the data and status of any jobs dispatched by your application.

LogワッチャーLog Watcher

Logワッチャーは、アプリケーションにより書き出されたすべてのログデータを記録します。The log watcher records the log data for any logs written by your application.

MailワッチャーMail Watcher

Mailワッチャーにより、メールのプレビューに加え、関連するデータをブラウザで確認できます。さらに、.emlファイルとしてメールをダウンロードできます。The mail watcher allows you to view an in-browser preview of the emails along with their associated data. You may also download the email as an .eml file.

ModelワッチャーModel Watcher

Modelワッチャーは、Eloquentのcreated、updated、restored、deletedイベントがディスパッチされた時点のモデルの変更を記録します。このワッチャーのeventsオプションにより、どのモデルイベントを記録するかを指定できます。The model watcher records model changes whenever an Eloquent created, updated, restored, or deleted event 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*'],
    ],
    ...
],

NotificationワッチャーNotification Watcher

Notificationワッチャーは、アプリケーションにより送信された全通知を記録します。通知がメールを送信し、Mailワッチャーが有効になっていれば、Mailワッチャー画面によりプレビューも利用できます。The notification watcher records all 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文とバインド、実行時間を記録します。このワッチャーは、100msよりも遅いクエリを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 100ms 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 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オプションによりKB単位でレスポンデータを制限できます。The request watcher records the request, headers, session, and response data associated with any requests handled by the application. You may limit your response data via the size_limit (in KB) 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 run by your application.

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

Telescopeダッシュボードは与えられたエントリーが保存されている時、ログインしているユーザーのアバターを表示します。TelescopeはデフォルトでGravatar Webサービスを使用してアバターを取得します。しかし、TelescopeSeerviceProviderでコールバックを登録すれば、アバターのURLをカスタマイズできます。コールバックにはユーザーのIDとメールアドレスが渡されますので、ユーザーのアバターイメージのURLを返す必用があります。The Telescope dashboard displays the user avatar for the user that was logged in 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 TelescopeServiceProvider. The callback will receive the user's ID and email address and should return the user's avatar image URL:

use App\User;
use Laravel\Telescope\Telescope;

/**
 * 全アプリケーションサービスの登録
 *
 * @return void
 */
public function register()
{
    Telescope::avatar(function ($id, $email) {
        return '/avatars/'.User::find($id)->avatar_path;
    });
}