Laravel Telescope

• 介绍
• 安装
  • 仅限本地环境安装
  • 配置
  • 数据修剪
  • 仪表盘授权
• 升级 Telescope
• 过滤
  • 条目
  • 批次
• 标签
• 可用的监视器
  • 批处理监视器
  • 缓存监视器
  • 命令监视器
  • 变量转储监视器
  • 事件监视器
  • 异常监视器
  • 门面（Gate）监视器
  • HTTP 客户端监视器
  • 任务监视器
  • 日志监视器
  • 邮件监视器
  • 模型监视器
  • 通知监视器
  • 查询监视器
  • Redis 监视器
  • 请求监视器
  • 计划任务监视器
  • 视图监视器
• 显示用户头像

介绍

Laravel Telescope 是您本地 Laravel 开发环境的绝佳调试伴侣。它能深入洞察进入应用的请求、异常、日志条目、数据库查询、队列任务、邮件、通知、缓存操作、定时任务、变量转储等核心运行信息。

安装

通过 Composer 包管理器安装 Telescope：

composer require laravel/telescope

安装 Telescope 后，使用 Artisan 命令 telescope:install 发布其资源文件和迁移文件。安装完成后，还需运行 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 时才进行注册：

/**
 * 注册应用服务
 */
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。该文件允许您配置监视器选项。每个配置选项都包含用途说明，请仔细查阅此文件。

如需完全禁用 Telescope 数据收集，可通过 enabled 配置项实现：

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

数据修剪

若不进行修剪，telescope_entries 表会快速累积记录。建议通过任务调度每天运行 telescope:prune 命令：

use Illuminate\Support\Facades\Schedule;

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

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

use Illuminate\Support\Facades\Schedule;

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

仪表盘访问控制

Telescope 仪表盘可通过 /telescope 路由访问。默认情况下，仅在 local 环境中可访问。在 app/Providers/TelescopeServiceProvider.php 文件中定义了授权门面，用于控制非本地环境下的访问权限。您可以根据需要修改此门面以限制访问：

use App\Models\User;

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

[!警告]
请确保在生产环境中将 APP_ENV 变量设置为 production，否则 Telescope 安装将对公众开放。

升级 Telescope

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

此外，升级任何新版本时都应重新发布资源文件：

php artisan telescope:publish

为保持资源文件最新并避免未来更新问题，可在 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 允许通过「标签」搜索条目。通常标签是 Eloquent 模型类名或认证用户ID，Telescope 会自动添加到条目中。您也可以使用 Telescope::tag 方法添加自定义标签。该方法接受返回标签数组的闭包，返回的标签将与 Telescope 自动添加的标签合并。通常应在 App\Providers\TelescopeServiceProvider 的 register 方法中调用：

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

/**
 * 注册应用服务
 */
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 中配置：

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

变量转储监视器

记录并显示通过全局 dump 函数输出的变量内容。注意：必须在浏览器中打开 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用作缓存，缓存命令也会被记录。

请求监视器

请求监视器记录应用程序处理的请求相关的请求数据、头信息、会话和响应数据。可通过size_limit选项(单位KB)限制记录的响应数据大小：

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

计划任务监视器

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

视图监视器

视图监视器记录视图渲染时使用的视图名称、路径、数据以及「composers」信息。

显示用户头像

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

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

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

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