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 标志进行安装：

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),

内容安全策略（CSP）Nonce

如果你想在 Telescope 视图中使用的 script 和 style 标签上添加nonce 属性，作为内容安全策略的一部分，可以使用 Telescope::cspNonce 方法指定要使用的 nonce。此方法通常应在中间件中调用，以便为每个请求分配新的 nonce：

use Closure;
use Illuminate\Http\Request;
use Laravel\Telescope\Telescope;
use Symfony\Component\HttpFoundation\Response;

public function handle(Request $request, Closure $next): Response
{
    Telescope::cspNonce('csp-nonce');

    return $next($request);
}

你可以将此中间件添加到应用程序 config/telescope.php 配置文件中的 middleware 选项：

'middleware' => [
    'web',
    App\Http\Middleware\AddTelescopeCspNonce::class,
    Authorize::class,
],

数据清理

若不进行清理，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 文件中，有一个授权门（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, [
            '[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\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 配置文件中自定义要启用的监视器列表：

'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 和策略 检查的数据与结果。如果你希望排除某些能力被监视器记录，可以在 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（单位：千字节）选项限制记录的响应数据量：

'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;

/**
 * 注册任何应用服务。
 */
public function register(): void
{
    // ...

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