Laravel Telescope

• 簡介
• 安裝
  • 僅限本機安裝
  • 設定
  • 資料修剪
  • 儀表板授權
• 升級 Telescope
• 篩選
  • 條目
  • 批次
• 標籤
• 可用的觀察者
  • 批次觀察者
  • 快取觀察者
  • 命令觀察者
  • Dump 觀察者
  • 事件觀察者
  • 異常觀察者
  • Gate 觀察者
  • HTTP 客戶端觀察者
  • 任務觀察者
  • 日誌觀察者
  • 郵件觀察者
  • 模型觀察者
  • 通知觀察者
  • 查詢觀察者
  • Redis 觀察者
  • 請求觀察者
  • 排程觀察者
  • 視圖觀察者
• 顯示使用者頭像

簡介

Laravel Telescope 是您本機 Laravel 開發環境的絕佳伴侶。Telescope 提供了對進入應用程式的請求、異常、日誌條目、資料庫查詢、佇列任務、郵件、通知、快取操作、排程任務、變數 dump 等的深入了解。

安裝

您可以使用 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') && class_exists(\Laravel\Telescope\TelescopeServiceProvider::class)) {
        $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]',
        ]);
    });
}

[!WARNING] 您應該確保在生產環境中將 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 允許您透過「標籤」搜尋條目。通常，標籤是 Eloquent 模型類別名稱或已認證的使用者 ID，Telescope 會自動將它們新增到條目中。有時，您可能想將自己的自訂標籤附加到條目。要實現此目的，可以使用 Telescope::tag 方法。tag 方法接受一個應返回標籤陣列的閉包。閉包返回的標籤將與 Telescope 自動附加到條目的任何標籤合併。通常，您應該在 App\Providers\TelescopeServiceProvider 類別的 register 方法中呼叫 tag 方法：

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 配置檔中自訂要啟用的觀察者列表：

'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'],
    ],
    // ...
],

Dump 觀察者

dump 觀察者在 Telescope 中記錄並顯示您的變數 dump。使用 Laravel 時，可以使用全域 dump 函數來 dump 變數。必須在瀏覽器中開啟 dump 觀察者標籤頁才能記錄 dump，否則 dump 將被觀察者忽略。

事件觀察者

事件觀察者記錄應用程式派發的任何事件的有效負載、監聽器和廣播資料。Laravel 框架的內部事件被事件觀察者忽略。

異常觀察者

異常觀察者記錄應用程式拋出的任何可報告異常的資料和堆疊追蹤。

Gate 觀察者

Gate 觀察者記錄應用程式的 gate 和 policy 檢查的資料和結果。如果您想排除某些能力不被觀察者記錄，可以在 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 觀察者也將記錄快取命令。

請求觀察者

請求觀察者記錄與應用程式處理的任何請求關聯的請求、標頭、Session 和響應資料。您可以透過 size_limit（千位元組）選項限制記錄的響應資料：

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

排程觀察者

排程觀察者記錄應用程式運行的任何排程任務的命令和輸出。

視圖觀察者

視圖觀察者記錄渲染視圖時使用的視圖名稱、路徑、資料和「合成器」。

顯示使用者頭像

Telescope 儀表板顯示儲存給定條目時已認證的使用者的頭像。預設情況下，Telescope 將使用 Gravatar 網路服務來檢索頭像。但是，您可以透過在 App\Providers\TelescopeServiceProvider 類別中註冊回呼來自訂頭像 URL。回呼將接收使用者的 ID 和電子郵件地址，並應返回使用者的頭像圖片 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 ! is_null($id)
            ? '/avatars/'.User::find($id)->avatar_path
            : '/generic-avatar.jpg';
    });
}