Laravel Telescope

简介

Laravel Telescope 是你本地 Laravel 开发环境的绝佳伴侣。Telescope 提供了对进入应用程序的请求、异常、日志条目、数据库查询、队列任务、邮件、通知、缓存操作、计划任务、变量转储等的深入洞察。

安装

你可以使用 Composer 包管理器将 Telescope 安装到你的 Laravel 项目中：

shell

composer require laravel/telescope

安装 Telescope 后，使用 telescope:install Artisan 命令发布其资源文件和迁移文件。安装 Telescope 后，你还应该运行 migrate 命令以创建存储 Telescope 数据所需的表：

shell

php artisan telescope:install

php artisan migrate

最后，你可以通过 /telescope 路由访问 Telescope 仪表盘。

仅本地安装

如果你计划仅使用 Telescope 来辅助本地开发，可以使用 --dev 标志安装 Telescope：

shell

composer require laravel/telescope --dev

php artisan telescope:install

php artisan migrate

运行 telescope:install 后，你应该从应用程序的 bootstrap/providers.php 配置文件中移除 TelescopeServiceProvider 服务提供者注册。取而代之，在 App\Providers\AppServiceProvider 类的 register 方法中手动注册 Telescope 的服务提供者。我们会在注册提供者之前确保当前环境是 local：

php

/**
 * 注册任何应用程序服务。
 */
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 包被自动发现：

json

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

配置

发布 Telescope 的资源文件后，其主要配置文件将位于 config/telescope.php。此配置文件允许你配置监视器选项。每个配置选项都包含其用途的描述，因此请务必仔细浏览此文件。

如果需要，你可以使用 enabled 配置选项完全禁用 Telescope 的数据收集：

php

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

数据清理

如果不进行清理，telescope_entries 表会非常快地累积记录。为了缓解这个问题，你应该调度 telescope:prune Artisan 命令每天运行：

php

use Illuminate\Support\Facades\Schedule;

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

默认情况下，所有超过 24 小时的条目将被清理。你可以在调用命令时使用 hours 选项来确定保留 Telescope 数据的时长。例如，以下命令将删除 48 小时前创建的所有记录：

php

use Illuminate\Support\Facades\Schedule;

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

仪表盘授权

Telescope 仪表盘可以通过 /telescope 路由访问。默认情况下，你只能在 local 环境中访问此仪表盘。在 app/Providers/TelescopeServiceProvider.php 文件中，有一个授权 gate 定义。此授权 gate 控制在非本地环境中对 Telescope 的访问。你可以根据需要修改此 gate 来限制对 Telescope 安装的访问：

php

use App\Models\User;

/**
 * 注册 Telescope gate。
 *
 * 此 gate 决定谁可以在非本地环境中访问 Telescope。
 */
protected function gate(): void
{
    Gate::define('viewTelescope', function (User $user) {
        return in_array($user->email, [
            'taylor@laravel.com',
        ]);
    });
}

WARNING

你应该确保在生产环境中将 APP_ENV 环境变量更改为 production。否则，你的 Telescope 安装将是公开可访问的。

升级 Telescope

升级到 Telescope 的新主版本时，务必仔细阅读升级指南。

此外，升级到任何新的 Telescope 版本时，你应该重新发布 Telescope 的资源文件：

shell

php artisan telescope:publish

为了保持资源文件最新并避免未来更新中出现问题，你可以在应用程序的 composer.json 文件中将 vendor:publish --tag=laravel-assets 命令添加到 post-update-cmd 脚本中：

json

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

过滤

条目

你可以通过 App\Providers\TelescopeServiceProvider 类中定义的 filter 闭包来过滤 Telescope 记录的数据。默认情况下，此闭包在 local 环境中记录所有数据，在其他所有环境中记录异常、失败的任务、计划任务以及带有受监控标签的数据：

php

use Laravel\Telescope\IncomingEntry;
use Laravel\Telescope\Telescope;

/**
 * 注册任何应用程序服务。
 */
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 记录：

php

use Illuminate\Support\Collection;
use Laravel\Telescope\IncomingEntry;
use Laravel\Telescope\Telescope;

/**
 * 注册任何应用程序服务。
 */
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 方法：

php

use Laravel\Telescope\EntryType;
use Laravel\Telescope\IncomingEntry;
use Laravel\Telescope\Telescope;

/**
 * 注册任何应用程序服务。
 */
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 配置文件中自定义要启用的监视器列表：

php

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

某些监视器还允许你提供额外的自定义选项：

php

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

Batch 监视器

Batch 监视器记录有关队列批次的信息，包括任务和连接信息。

Cache 监视器

Cache 监视器在缓存键被命中、未命中、更新和删除时记录数据。

Command 监视器

Command 监视器在每次执行 Artisan 命令时记录参数、选项、退出代码和输出。如果你想排除某些命令不被监视器记录，可以在 config/telescope.php 文件的 ignore 选项中指定命令：

php

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

Dump 监视器

Dump 监视器在 Telescope 中记录并显示你的变量转储。使用 Laravel 时，可以使用全局 dump 函数转储变量。Dump 监视器选项卡必须在浏览器中打开才能记录转储，否则，监视器将忽略这些转储。

Event 监视器

Event 监视器记录应用程序分发的任何事件的负载、监听器和广播数据。Laravel 框架的内部事件会被 Event 监视器忽略。

Exception 监视器

Exception 监视器记录应用程序抛出的任何可报告异常的数据和堆栈跟踪。

Gate 监视器

Gate 监视器记录应用程序的 gate 和策略检查的数据和结果。如果你想排除某些权限不被监视器记录，可以在 config/telescope.php 文件的 ignore_abilities 选项中指定：

php

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

HTTP Client 监视器

HTTP Client 监视器记录应用程序发出的外发 HTTP 客户端请求。

Job 监视器

Job 监视器记录应用程序分发的任何任务的数据和状态。

Log 监视器

Log 监视器记录应用程序写入的任何日志的日志数据。

默认情况下，Telescope 只会记录 error 级别及以上的日志。但是，你可以修改应用程序 config/telescope.php 配置文件中的 level 选项来更改此行为：

php

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

    // ...
],

Mail 监视器

Mail 监视器允许你在浏览器中预览应用程序发送的邮件及其关联数据。你还可以将邮件下载为 .eml 文件。

Model 监视器

Model 监视器在 Eloquent 模型事件被分发时记录模型更改。你可以通过监视器的 events 选项指定应记录哪些模型事件：

php

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

如果你想记录在给定请求期间水合的模型数量，请启用 hydrations 选项：

php

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

Notification 监视器

Notification 监视器记录应用程序发送的所有通知。如果通知触发了邮件并且你启用了 Mail 监视器，该邮件也将在 Mail 监视器界面上可供预览。

Query 监视器

Query 监视器记录应用程序执行的所有查询的原始 SQL、绑定和执行时间。监视器还会将任何慢于 100 毫秒的查询标记为 slow。你可以使用监视器的 slow 选项自定义慢查询阈值：

php

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

Redis 监视器

Redis 监视器记录应用程序执行的所有 Redis 命令。如果你使用 Redis 进行缓存，缓存命令也会被 Redis 监视器记录。

Request 监视器

Request 监视器记录与应用程序处理的任何请求相关的请求、请求头、session 和响应数据。你可以通过 size_limit（以千字节为单位）选项限制记录的响应数据：

php

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

Schedule 监视器

Schedule 监视器记录应用程序运行的任何计划任务的命令和输出。

View 监视器

View 监视器记录渲染视图时使用的视图名称、路径、数据和 "composers"。

显示用户头像

Telescope 仪表盘会显示保存给定条目时已认证用户的头像。默认情况下，Telescope 将使用 Gravatar 网络服务获取头像。但是，你可以通过在 App\Providers\TelescopeServiceProvider 类中注册回调来自定义头像 URL。回调将接收用户的 ID 和邮箱地址，并应返回用户的头像图片 URL：

php

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

/**
 * 注册任何应用程序服务。
 */
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 ​

过滤 ​

条目 ​

批次 ​

标签 ​

可用的监视器 ​

Batch 监视器 ​

Cache 监视器 ​

Command 监视器 ​

Dump 监视器 ​

Event 监视器 ​

Exception 监视器 ​

Gate 监视器 ​

HTTP Client 监视器 ​

Job 监视器 ​

Log 监视器 ​

Mail 监视器 ​

Model 监视器 ​

Notification 监视器 ​

Query 监视器 ​

Redis 监视器 ​

Request 监视器 ​

Schedule 监视器 ​

View 监视器 ​

显示用户头像 ​

Laravel Telescope

简介

安装

仅本地安装

配置

数据清理

仪表盘授权

升级 Telescope

过滤

条目

批次

标签

可用的监视器

Batch 监视器

Cache 监视器

Command 监视器

Dump 监视器

Event 监视器

Exception 监视器

Gate 监视器

HTTP Client 监视器

Job 监视器

Log 监视器

Mail 监视器

Model 监视器

Notification 监视器

Query 监视器

Redis 监视器

Request 监视器

Schedule 监视器

View 监视器

显示用户头像