Laravel Telescope

簡介
安裝
升級 Telescope
過濾
- 條目
- 批處理
標籤
可用監視器
顯示使用者頭像

簡介

Laravel Telescope 是您本地 Laravel 開發環境的絕佳伴侶。Telescope 可以讓您深入瞭解進入應用程式的請求、異常、日誌條目、資料庫查詢、佇列任務、郵件、通知、快取操作、計劃任務、變數轉儲等資訊。

安裝

您可以使用 Composer 包管理器將 Telescope 安裝到您的 Laravel 專案中

1composer require laravel/telescope

composer require laravel/telescope

安裝 Telescope 後，使用 telescope:install Artisan 命令釋出其資原始檔和遷移檔案。安裝完成後，您還應執行 migrate 命令以建立儲存 Telescope 資料所需的表

1php artisan telescope:install
2 
3php artisan migrate

php artisan telescope:install

php artisan migrate

最後，您可以透過 /telescope 路由訪問 Telescope 儀表板。

僅限本地安裝

如果您計劃僅將 Telescope 用於輔助本地開發，則可以使用 --dev 標誌來安裝它

1composer require laravel/telescope --dev
2 
3php artisan telescope:install
4 
5php artisan migrate

composer require laravel/telescope --dev

php artisan telescope:install

php artisan migrate

執行 telescope:install 後，您應從應用程式的 bootstrap/providers.php 配置檔案中移除 TelescopeServiceProvider 服務提供程式的註冊。相反，請在 App\Providers\AppServiceProvider 類的 register 方法中手動註冊 Telescope 的服務提供程式。在註冊之前，我們將確保當前環境為 local

 1/**
 2 * Register any application services.
 3 */
 4public function register(): void
 5{
 6    if ($this->app->environment('local') && class_exists(\Laravel\Telescope\TelescopeServiceProvider::class)) {
 7        $this->app->register(\Laravel\Telescope\TelescopeServiceProvider::class);
 8        $this->app->register(TelescopeServiceProvider::class);
 9    }
10}

/**
 * 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 包被自動發現

1"extra": {
2    "laravel": {
3        "dont-discover": [
4            "laravel/telescope"
5        ]
6    }
7},

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

配置

釋出 Telescope 的資原始檔後，其主要配置檔案將位於 config/telescope.php。此配置檔案允許您配置監視器選項。每個配置選項都包含了其用途的說明，因此請務必仔細閱讀此檔案。

如果需要，您可以使用 enabled 配置選項完全停用 Telescope 的資料收集功能

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

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

資料清理

如果不進行清理，telescope_entries 表會非常迅速地積累記錄。為了緩解這種情況，您應該計劃 telescope:prune Artisan 命令每天執行一次

1use Illuminate\Support\Facades\Schedule;
2 
3Schedule::command('telescope:prune')->daily();

use Illuminate\Support\Facades\Schedule;

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

預設情況下，所有超過 24 小時的條目都會被清理。您可以在呼叫該命令時使用 hours 選項來決定保留多久的 Telescope 資料。例如，以下命令將刪除 48 小時前建立的所有記錄

1use Illuminate\Support\Facades\Schedule;
2 
3Schedule::command('telescope:prune --hours=48')->daily();

use Illuminate\Support\Facades\Schedule;

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

儀表板授權

可以透過 /telescope 路由訪問 Telescope 儀表板。預設情況下，您只能在 local 環境中訪問此儀表板。在您的 app/Providers/TelescopeServiceProvider.php 檔案中，有一個授權 Gate 定義。此授權 Gate 控制著在非本地環境中對 Telescope 的訪問。您可以根據需要自由修改此 Gate，以限制對 Telescope 安裝的訪問

 1use App\Models\User;
 2 
 3/**
 4 * Register the Telescope gate.
 5 *
 6 * This gate determines who can access Telescope in non-local environments.
 7 */
 8protected function gate(): void
 9{
10    Gate::define('viewTelescope', function (User $user) {
11        return in_array($user->email, [
12            '[email protected]',
13        ]);
14    });
15}

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

升級到 Telescope 的新主版本時，務必仔細查閱升級指南。

此外，升級到任何新的 Telescope 版本時，您都應重新發布 Telescope 的資原始檔

1php artisan telescope:publish

php artisan telescope:publish

為了保持資原始檔為最新狀態並避免將來更新時出現問題，您可以將 vendor:publish --tag=laravel-assets 命令新增到應用程式 composer.json 檔案的 post-update-cmd 指令碼中

1{
2    "scripts": {
3        "post-update-cmd": [
4            "@php artisan vendor:publish --tag=laravel-assets --ansi --force"
5        ]
6    }
7}

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

過濾

條目

您可以透過定義在 App\Providers\TelescopeServiceProvider 類中的 filter 閉包來過濾 Telescope 記錄的資料。預設情況下，此閉包在 local 環境中記錄所有資料，而在所有其他環境中僅記錄異常、失敗的任務、計劃任務以及帶有受監控標籤的資料

 1use Laravel\Telescope\IncomingEntry;
 2use Laravel\Telescope\Telescope;
 3 
 4/**
 5 * Register any application services.
 6 */
 7public function register(): void
 8{
 9    $this->hideSensitiveRequestDetails();
10 
11    Telescope::filter(function (IncomingEntry $entry) {
12        if ($this->app->environment('local')) {
13            return true;
14        }
15 
16        return $entry->isReportableException() ||
17            $entry->isFailedJob() ||
18            $entry->isScheduledTask() ||
19            $entry->isSlowQuery() ||
20            $entry->hasMonitoredTag();
21    });
22}

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 將記錄所有條目

 1use Illuminate\Support\Collection;
 2use Laravel\Telescope\IncomingEntry;
 3use Laravel\Telescope\Telescope;
 4 
 5/**
 6 * Register any application services.
 7 */
 8public function register(): void
 9{
10    $this->hideSensitiveRequestDetails();
11 
12    Telescope::filterBatch(function (Collection $entries) {
13        if ($this->app->environment('local')) {
14            return true;
15        }
16 
17        return $entries->contains(function (IncomingEntry $entry) {
18            return $entry->isReportableException() ||
19                $entry->isFailedJob() ||
20                $entry->isScheduledTask() ||
21                $entry->isSlowQuery() ||
22                $entry->hasMonitoredTag();
23            });
24    });
25}

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

Telescope 允許您透過“標籤”搜尋條目。通常，標籤是 Eloquent 模型類名或已認證的使用者 ID，Telescope 會自動將它們新增到條目中。有時，您可能希望將自己的自定義標籤附加到條目中。為此，您可以使用 Telescope::tag 方法。tag 方法接受一個返回標籤陣列的閉包。閉包返回的標籤將與 Telescope 自動附加到條目的任何標籤合併。通常，您應該在 App\Providers\TelescopeServiceProvider 類的 register 方法中呼叫 tag 方法

 1use Laravel\Telescope\EntryType;
 2use Laravel\Telescope\IncomingEntry;
 3use Laravel\Telescope\Telescope;
 4 
 5/**
 6 * Register any application services.
 7 */
 8public function register(): void
 9{
10    $this->hideSensitiveRequestDetails();
11 
12    Telescope::tag(function (IncomingEntry $entry) {
13        return $entry->type === EntryType::REQUEST
14            ? ['status:'.$entry->content['response_status']]
15            : [];
16    });
17}

use Laravel\Telescope\EntryType;
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 === EntryType::REQUEST
            ? ['status:'.$entry->content['response_status']]
            : [];
    });
}

可用監視器

Telescope “監視器”在執行請求或控制檯命令時收集應用程式資料。您可以在 config/telescope.php 配置檔案中自定義要啟用的監視器列表

1'watchers' => [
2    Watchers\CacheWatcher::class => true,
3    Watchers\CommandWatcher::class => true,
4    // ...
5],

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

某些監視器還允許您提供額外的自定義選項

1'watchers' => [
2    Watchers\QueryWatcher::class => [
3        'enabled' => env('TELESCOPE_QUERY_WATCHER', true),
4        'slow' => 100,
5    ],
6    // ...
7],

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

批處理監視器

批處理監視器記錄有關排隊批處理的資訊，包括任務和連線資訊。

快取監視器

快取監視器在快取鍵命中、未命中、更新和刪除時記錄資料。

命令監視器

命令監視器在執行 Artisan 命令時記錄引數、選項、退出程式碼和輸出。如果您希望排除某些不被監視器記錄的命令，可以在 config/telescope.php 檔案中的 ignore 選項中指定這些命令

1'watchers' => [
2    Watchers\CommandWatcher::class => [
3        'enabled' => env('TELESCOPE_COMMAND_WATCHER', true),
4        'ignore' => ['key:generate'],
5    ],
6    // ...
7],

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

Dump 監視器

Dump 監視器在 Telescope 中記錄並顯示您的變數轉儲。使用 Laravel 時，可以使用全域性 dump 函式轉儲變數。必須在瀏覽器中開啟 Dump 監視器選項卡，轉儲才會被記錄，否則監視器將忽略這些轉儲。

事件監視器

事件監視器記錄應用程式分發的任何事件的有效載荷、監聽器和廣播資料。Laravel 框架的內部事件會被事件監視器忽略。

異常監視器

異常監視器記錄應用程式丟擲的任何可報告異常的資料和堆疊跟蹤。

Gate 監視器

Gate 監視器記錄應用程式進行的門衛（Gate）和策略（Policy）檢查的資料和結果。如果您希望排除某些不被監視器記錄的許可權驗證，可以在 config/telescope.php 檔案中的 ignore_abilities 選項中指定它們

1'watchers' => [
2    Watchers\GateWatcher::class => [
3        'enabled' => env('TELESCOPE_GATE_WATCHER', true),
4        'ignore_abilities' => ['viewNova'],
5    ],
6    // ...
7],

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

HTTP 客戶端監視器

HTTP 客戶端監視器記錄應用程式發出的外部 HTTP 請求。

任務監視器

任務監視器記錄應用程式分發的任何任務的資料和狀態。

日誌監視器

日誌監視器記錄應用程式寫入的任何日誌資料。

預設情況下，Telescope 僅記錄 error 及以上級別的日誌。但是，您可以透過修改應用程式 config/telescope.php 配置檔案中的 level 選項來改變此行為

1'watchers' => [
2    Watchers\LogWatcher::class => [
3        'enabled' => env('TELESCOPE_LOG_WATCHER', true),
4        'level' => 'debug',
5    ],
6 
7    // ...
8],

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

    // ...
],

郵件監視器

郵件監視器允許您在瀏覽器中預覽應用程式傳送的電子郵件及其相關資料。您還可以將電子郵件下載為 .eml 檔案。

模型監視器

模型監視器在每次分發 Eloquent 模型事件時記錄模型更改。您可以透過監視器的 events 選項指定要記錄哪些模型事件

1'watchers' => [
2    Watchers\ModelWatcher::class => [
3        'enabled' => env('TELESCOPE_MODEL_WATCHER', true),
4        'events' => ['eloquent.created*', 'eloquent.updated*'],
5    ],
6    // ...
7],

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

如果您想記錄在給定請求期間水合（hydrated）的模型數量，請啟用 hydrations 選項

1'watchers' => [
2    Watchers\ModelWatcher::class => [
3        'enabled' => env('TELESCOPE_MODEL_WATCHER', true),
4        'events' => ['eloquent.created*', 'eloquent.updated*'],
5        'hydrations' => true,
6    ],
7    // ...
8],

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

通知監視器

通知監視器記錄應用程式傳送的所有通知。如果通知觸發了電子郵件並且您啟用了郵件監視器，該電子郵件也將可在郵件監視器螢幕上預覽。

查詢監視器

查詢監視器記錄應用程式執行的所有查詢的原始 SQL、繫結和執行時間。監視器還會將所有慢於 100 毫秒的查詢標記為 slow。您可以使用監視器的 slow 選項自定義慢查詢閾值

1'watchers' => [
2    Watchers\QueryWatcher::class => [
3        'enabled' => env('TELESCOPE_QUERY_WATCHER', true),
4        'slow' => 50,
5    ],
6    // ...
7],

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

Redis 監視器

Redis 監視器記錄應用程式執行的所有 Redis 命令。如果您使用 Redis 進行快取，快取命令也會被 Redis 監視器記錄。

請求監視器

請求監視器記錄與應用程式處理的任何請求相關的請求、頭部資訊、會話和響應資料。您可以透過 size_limit（以千位元組為單位）選項限制記錄的響應資料大小

1'watchers' => [
2    Watchers\RequestWatcher::class => [
3        'enabled' => env('TELESCOPE_REQUEST_WATCHER', true),
4        'size_limit' => env('TELESCOPE_RESPONSE_SIZE_LIMIT', 64),
5    ],
6    // ...
7],

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

 1use App\Models\User;
 2use Laravel\Telescope\Telescope;
 3 
 4/**
 5 * Register any application services.
 6 */
 7public function register(): void
 8{
 9    // ...
10 
11    Telescope::avatar(function (?string $id, ?string $email) {
12        return ! is_null($id)
13            ? '/avatars/'.User::find($id)->avatar_path
14            : '/generic-avatar.jpg';
15    });
16}

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

/**
 * Register any application services.
 */
public function register(): void
{
    // ...

    Telescope::avatar(function (?string $id, ?string $email) {
        return ! is_null($id)
            ? '/avatars/'.User::find($id)->avatar_path
            : '/generic-avatar.jpg';
    });
}

Laravel Telescope

簡介

安裝

僅限本地安裝

配置

資料清理

儀表板授權

升級 Telescope

過濾

條目

批處理

標籤

可用監視器

批處理監視器

快取監視器

命令監視器

Dump 監視器

事件監視器

異常監視器

Gate 監視器

HTTP 客戶端監視器

任務監視器

日誌監視器

郵件監視器

模型監視器

通知監視器

查詢監視器

Redis 監視器

請求監視器

排程監視器

檢視監視器

顯示使用者頭像

在此頁面上

產品

Packages

資源

合作伙伴