Laravel Telescope

簡介
安裝
升級 Telescope
篩選
- 條目
- 批次
標記
可用的監視器
顯示使用者頭像

簡介

Laravel Telescope 是您本地 Laravel 開發環境的絕佳夥伴。Telescope 可深入了解傳入您應用程式的請求、例外狀況、記錄條目、資料庫查詢、已排隊的工作、郵件、通知、快取操作、排定的任務、變數傾印等等。

安裝

您可以使用 Composer 套件管理員將 Telescope 安裝到您的 Laravel 專案中

composer require laravel/telescope

安裝 Telescope 後，使用 telescope:install Artisan 命令發佈其資源和遷移。安裝 Telescope 後，您還應該執行 migrate 命令，以便建立儲存 Telescope 資料所需的表格

php artisan telescope:install
 
php artisan migrate

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

僅限本地安裝

如果您計劃僅使用 Telescope 來協助您的本地開發，您可以使用 --dev 旗標安裝 Telescope

composer require laravel/telescope --dev
 
php artisan telescope:install
 
php artisan migrate

執行 telescope:install 後，您應該從應用程式的 bootstrap/providers.php 設定檔中移除 TelescopeServiceProvider 服務提供者註冊。相反地，請在您 App\Providers\AppServiceProvider 類別的 register 方法中手動註冊 Telescope 的服務提供者。我們會在註冊提供者之前確保目前的環境是 local

/**
 * 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"
        ]
    }
},

設定

發佈 Telescope 的資源後，其主要設定檔將位於 config/telescope.php。此設定檔可讓您設定您的監視器選項。每個設定選項都包含其用途的描述，因此請務必仔細瀏覽此檔案。

如果需要，您可以使用 enabled 設定選項完全停用 Telescope 的資料收集

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

資料修剪

如果不修剪，telescope_entries 表格可能會非常快速地累積記錄。為了減輕這種情況，您應該排程 telescope:prune Artisan 命令每天執行

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

依預設，所有超過 24 小時的條目都會被修剪。您可以在呼叫命令時使用 hours 選項來決定要保留 Telescope 資料的時間長度。例如，以下命令將刪除所有超過 48 小時前建立的記錄

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

儀表板授權

可以透過 /telescope 路由存取 Telescope 儀表板。依預設，您只能在 local 環境中存取此儀表板。在您的 app/Providers/TelescopeServiceProvider.php 檔案中，有一個授權閘道定義。此授權閘道控制在非本機環境中對 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, [
            '[email protected]',
        ]);
    });
}

您應該確保在您的生產環境中將 APP_ENV 環境變數變更為 production。否則，您的 Telescope 安裝將公開可用。

升級 Telescope

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

此外，在升級到任何新的 Telescope 版本時，您應該重新發佈 Telescope 的資源

php artisan telescope:publish

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

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

篩選

條目

您可以透過在您的 App\Providers\TelescopeServiceProvider 類別中定義的 filter 閉包來篩選 Telescope 記錄的資料。依預設，此閉包會記錄 local 環境中的所有資料，以及所有其他環境中的例外狀況、失敗的工作、排程的任務和具有受監控標籤的資料

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 記錄

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 可讓您依「標籤」搜尋條目。通常，標籤是 Telescope 自動新增到條目的 Eloquent 模型類別名稱或已驗證的使用者 ID。有時，您可能想要將自己的自訂標籤附加到條目。若要完成此操作，您可以使用 Telescope::tag 方法。tag 方法接受一個閉包，該閉包應傳回標籤陣列。閉包傳回的標籤將會與 Telescope 自動附加到條目的任何標籤合併。通常，您應該在 App\Providers\TelescopeServiceProvider 類別的 register 方法中呼叫 tag 方法

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

可用的監視器

當執行請求或主控台命令時，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,
    ],
    ...
],

批次監視器

批次監視器會記錄已排隊的批次的相關資訊，包括工作和連線資訊。

快取監視器

快取監視器會在快取金鑰命中、遺失、更新和遺忘時記錄資料。

命令監視器

命令監視器會在每次執行 Artisan 命令時記錄引數、選項、結束代碼和輸出。如果您想要排除某些命令不被監視器記錄，您可以在 config/telescope.php 檔案的 ignore 選項中指定該命令

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

傾印監視器

傾印監視器會在 Telescope 中記錄並顯示您的變數傾印。使用 Laravel 時，可以使用全域 dump 函式傾印變數。必須在瀏覽器中開啟傾印監視器索引標籤，才能記錄傾印，否則監視器會忽略傾印。

事件監視器

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

例外狀況監視器

例外狀況監視器會記錄您應用程式擲回的任何可回報例外狀況的資料和堆疊追蹤。

閘道監視器

閘道監視器會記錄您應用程式的閘道和原則檢查的資料和結果。如果您想要排除某些能力不被監視器記錄，您可以在您的 config/telescope.php 檔案的 ignore_abilities 選項中指定這些能力

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

HTTP 用戶端監視器

HTTP 用戶端監視器會記錄您應用程式發出的外寄HTTP 用戶端請求。

工作監視器

工作監視器會記錄您應用程式調度的任何工作的資料和狀態。

記錄監視器

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

依預設，Telescope 只會記錄 error 及其以上的層級的記錄。但是，您可以修改應用程式的 config/telescope.php 設定檔中的 level 選項來修改此行為

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

郵件監視器

郵件監視器可讓您檢視您應用程式傳送的電子郵件的瀏覽器內預覽及其關聯資料。您也可以將電子郵件下載為 .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,
    ],
    ...
],

通知監視器

通知監看器會記錄您的應用程式所發送的所有通知。如果通知觸發了電子郵件，並且您啟用了郵件監看器，則電子郵件也會在郵件監看器畫面中提供預覽。

查詢監視器

查詢監看器會記錄您的應用程式執行的所有查詢的原始 SQL、綁定和執行時間。監看器還會將任何執行時間超過 100 毫秒的查詢標記為 slow。您可以使用監看器的 slow 選項自訂慢查詢的閾值。

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

Redis 監視器

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

請求監視器

請求監看器會記錄與應用程式處理的任何請求相關的請求、標頭、會話和響應數據。您可以使用 size_limit（以 KB 為單位）選項來限制您記錄的響應數據。

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

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

Laravel Telescope

簡介

安裝

僅限本地安裝

設定

資料修剪

儀表板授權

升級 Telescope

篩選

條目

批次

標記

可用的監視器

批次監視器

快取監視器

命令監視器

傾印監視器

事件監視器

例外狀況監視器

閘道監視器

HTTP 用戶端監視器

工作監視器

記錄監視器

郵件監視器

模型監視器

通知監視器

查詢監視器

Redis 監視器

請求監視器

排程監視器

視圖監視器

顯示使用者頭像