Lang x Lang

︙

Laravel Telescope

Table of Contents

Introduction

Laravel Telescope は、ローカルの Laravel 開発環境の素晴らしいパートナーになります。 Telescope は、application への requests、例外、log エントリ、databasequery、queue に入った jobs、mail、通知、cache 操作、schedule されたタスク、variable のダンプなど、さまざまな内容を把握することを提供します。

Installation

あなたは Composer パッケージマネージャーを使って、 Laravel project に Telescope をインストールすることができます：

composer require laravel/telescope

Telescope をインストールした後、publish そのアセットと migrations を telescope:install の Artisan command を使用して行います。Telescope をインストールした後、Telescope の data を保存するために必要なテーブルを作成するために、migrate の command も実行する必要があります。

php artisan telescope:install

php artisan migrate

最後に、/telescope route を通じて Telescope ダッシュボードにアクセスすることができます。

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

もし、ローカル開発をアシストするために Telescope のみを使用する予定であれば、 --dev フラグを使用して Telescope をインストールすることができます：

composer require laravel/telescope --dev

php artisan telescope:install

php artisan migrate

telescope:installを実行した後、application のbootstrap/providers.php設定ファイルからTelescopeServiceProvider service providers の登録を削除する必要があります。代わりに、App\Providers\AppServiceProvider class のregister method で Telescope の service providers を手動で“登録してください。現在の環境がlocalであることを事前に確認してから、providers を登録します。

/**
 * Register any application services.
 */
public function register(): void
{
    if ($this->app->environment('local')) {
        $this->app->register(\Laravel\Telescope\TelescopeServiceProvider::class);
        $this->app->register(TelescopeServiceProvider::class);
    }
}

最後に、以下をあなたのcomposer.jsonファイルに追加することで、 Telescope パッケージが自動検出されるのを防ぐべきです：

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

Configuration

Telescope のアセットを公開した後、その primary 設定ファイルはconfig/telescope.phpに配置されます。この設定ファイルを使用すると、watcher optionsを設定することができます。各設定オプションにはその目的の説明が含まれているので、このファイルをしっかりと探索するようにしてください。

希望により、enabled 設定 option を使用して、Telescope の datacollection を完全に無効にすることができます。

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

Data プルーニング

telescope_entries テーブルは、剪定しないと、非常に速くレコードを蓄積する可能性があります。これを緩和するために、telescope:prune の Artisan command をscheduleし、毎日実行すべきです。

use Illuminate\Support\Facades\Schedule;

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

default では、24 時間以上前のすべてのエントリが剪定されます。command を呼び出す際にhoursoption を使用して、Telescope data をどの程度保持するかを決定できます。例えば、次の command は 48 時間以上前に作成されたすべてのレコードを削除します：

use Illuminate\Support\Facades\Schedule;

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

Dashboard Authorization

Telescope ダッシュボードには、/telescope route からアクセスできます。Default では、このダッシュボードにはlocal 環境でのみアクセスできます。app/Providers/TelescopeServiceProvider.phpファイル内には、authorization gateの定義があります。この 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, [
            'taylor@laravel.com',
        ]);
    });
}

WARNING

あなたはあなたの APP_ENV environment 変数を production に変更するように確認すべきです。それがあなたの production environment でです。そうでなければ、あなたの Telescope のインストールは公開されてしまいます。

Upgrading Telescope

Telescope の新しいメジャーバージョンにアップグレードする際には、慎重にアップグレードガイド を確認することが重要です。

さらに、新しい Telescopeversion にアップグレードする際には、Telescope のアセットを再公開する必要があります：

php artisan telescope:publish

アセットを最新の状態に保ち、将来のアップデートで問題を避けるために、vendor:publish --tag=laravel-assets command をアプリケーションのcomposer.jsonファイルのpost-update-cmdスクリプトに追加することができます：

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

Filtering

Entries

Telescope によって recorded された data は、App\Providers\TelescopeServiceProvider class に定義されているfilterクロージャを通じてフィルタリングすることができます。 default では、このクロージャはlocal environment 内のすべての data と exceptions 、失敗した jobs 、予定されたタスク、そして他のすべての environments 内の監視された tags 付き data を記録します。

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クロージャは個々のエントリのための data をフィルタリングしますが、filterBatch method を使用して、特定の request または console command の全ての data をフィルタリングするクロージャを register することができます。クロージャがtrueを返すと、全てのエントリが Telescope によって recorded されます：

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 は、tags によるエントリーの search を可能にします。通常、tags は Eloquent model class の名前や authentication された user の ID であり、Telescope はこれらを自動的にエントリーに追加します。稀に、自分自身の custom tags をエントリーに attach したい場合があります。これを達成するためには、Telescope::tag method を使用することができます。tag method はクロージャを受け入れ、そのクロージャは tags の array を返すべきです。クロージャによって返された tags は、Telescope が自動的にエントリーに attach する任意の tags と merge されます。典 types 的には、tag method をあなたのApp\Providers\TelescopeServiceProvider class のregister method 内で呼び出すべきです。

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 の観測者は、request または console command が実行されると applicationdata を収集します。config/telescope.php設定ファイルの中で有効にしたい観測者のリストをカスタマイズすることができます。

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

一部の観察者は、追加のカスタマイズ options を提供することも許可しています：

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

Batch ウォッチャー

batch ウォッチャーは、キューに入れられたバッチについての情報、 job および connection 情報を含めて記録します。

Cache ウォッチャー

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

Command ウォッチャー

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

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

Dump ウォッチャー

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

Event ウォッチャー

イベントウォッチャーは、あなたの webapplication が dispatch するすべてのeventsに対して、ペイロード、listeners、そして broadcastdata を記録します。Laravel フレームワークの内部イベントは、イベントウォッチャーから無視されます。

例外ウォッチャー

例外ウォッチャーは、 application がスローするレポート可能な exceptions の data と stack トレースを記録します。

ゲートウォッチャー

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

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

HTTP Client ウォッチャー

HTTP client ウォッチャは、あなたの application で行われるHTTP client requestを記録します。

Job ウォッチャー

job ウォッチャーは、あなたの application によってディスパッチされたjobsの data および status を記録します。

Log ウォッチャー

log ウォッチャーは、あなたの application が書き込んだすべての log のためのlog dataを記録します。

default では、 Telescope はerrorレベル以上のログのみを記録します。しかし、アプリケーションのconfig/telescope.php設定ファイルのlevelオプションを変更することで、この動作を変更することができます:

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

    // ...
],

Mail ウォッチャー

mail ウォッチャーは、emailsのブラウザ内 preview を view することができ、それらはあなたの application によって送信されたものであり、それらに関連する data と共に表示されます。また、email を.emlファイルとして download することもできます。

Model ウォッチャー

model ウォッチャーは、 Eloquent model event がディスパッチされるたびに model の変更を記録します。ウォッチャーの events オプションを通じて、どの model events が recorded されるべきかを指定することができます。

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

特定の request 中に水和された models の数を記録したい場合は、hydrationsオプションを有効にします:

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

Notification ウォッチャー

notification ウォッチャーは、あなたの application から送信されるすべてのnotificationsを記録します。もし notification が email をトリガーし、あなたが mail ウォッチャーを有効にしている場合、その email は mail ウォッチャー画面でもプレビューできるようになります。

Query ウォッチャー

query ウォッチャーは、 application が実行するすべてのクエリの生の SQL、バインディング、および実行時間を記録します。ウォッチャーは、100 ミリ秒より遅いクエリにslowという tags を付けます。ウォッチャーのslowオプションを使用して、遅い query の閾値をカスタマイズすることもできます。

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

Redis ウォッチャー

Redis ウォッチャーは、ご使用の application が実行したすべてのRedisコマンドを記録します。 Redis をキャッシングに使用している場合、 cache コマンドも Redis ウォッチャーによって recorded されます。

Request ウォッチャー

request ウォッチャーは、 application が処理するすべてのリクエストに関連する request 、 headers 、 session 、及び recorded response data を記録します。size_limit(キロバイト単位)オプションを使用して、記録する response data の量を制限することができます。

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

Schedule Watcher

schedule 監視者は、application によって実行されるscheduled tasksの任意の command と output を記録します。

View ウォッチャー

view ウォッチャーは、view 名、path、data、および rendering 時に使用される "composers" を記録します。

Displaying User Avatars

Telescope ダッシュボードは、指定されたエントリが保存されたときに authentication された user のアバターを表示します。default では、Telescope は Gravatarweb service を使用してアバターを取得します。ただし、App\Providers\TelescopeServiceProviderclass でコールバックを登録することで、アバターの URL をカスタマイズすることができます。このコールバックは、user の ID と email アドレスを受け取り、user のアバターの image 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;
    });
}

当社サイトでは、Cookie を使用しています。各規約をご確認の上ご利用ください:
Cookie Policy, Privacy Policy および Terms of Use