Telescope

未匹配的标注
本文档最新版为 12.x,旧版本可能放弃维护,推荐阅读最新版!

Laravel Telescope

介绍

Laravel Telescope 是本地 Laravel 开发环境的得力助手。Telescope 可以帮助你深入了解应用收到的请求、异常、日志条目、数据库查询、队列任务、邮件、通知、缓存操作、计划任务、变量转储等信息。

telescope-example.png

安装

你可以通过 Composer 包管理器将 Telescope 安装到 Laravel 项目中:

composer require laravel/telescope

安装 Telescope 后,使用 telescope:install Artisan 命令发布其资源和迁移文件。之后还应运行 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:

/**
 * 注册应用服务。
 */
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 文件中定义了一个 授权 Gate,用于控制在 非本地 环境中对 Telescope 的访问。你可以根据需要修改该 Gate,以限制对 Telescope 的访问:

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 的资源:

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;

/**
 * 注册应用服务。
 */
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;

/**
 * 注册应用服务。
 */
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'],
    ],
    // ...
],

变量转储监视器

变量转储监视器在 Telescope 中记录并显示变量转储内容。在 Laravel 中,可以使用全局 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),
    ],
    // ...
],

计划任务监视器

计划任务监视器记录应用运行的所有 计划任务 的命令和输出。

视图监视器

视图监视器记录渲染视图时使用的 视图 名称、路径、数据和「composer」。

显示用户头像

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

本文章首发在 LearnKu.com 网站上。

本译文仅用于学习和交流目的,转载请务必注明文章译者、出处、和本文链接
我们的翻译工作遵照 CC 协议,如果我们的工作有侵犯到您的权益,请及时联系我们。

原文地址:https://learnku.com/docs/laravel/13.x/te...

译文地址:https://learnku.com/docs/laravel/13.x/te...

上一篇 下一篇
《L03 构架 API 服务器》
你将学到如 RESTFul 设计风格、PostMan 的使用、OAuth 流程,JWT 概念及使用 和 API 开发相关的进阶知识。
《G01 Go 实战入门》
从零开始带你一步步开发一个 Go 博客项目,让你在最短的时间内学会使用 Go 进行编码。项目结构很大程度上参考了 Laravel。
贡献者:1
讨论数量: 0
发起讨论 只看当前版本


暂无话题~