Telescope 调试工具

8.5

8.5 8.x 7.x 6.x 5.8 5.7 5.6 5.5 5.4 5.3 5.2 5.1

Laravel Telescope

简介
安装
升级 Telescope
过滤
- 单项过滤
- 批量过滤
标记
可用的监视器
显示用户头像

简介

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

安装

您可以使用 Composer 将 Telescope 安装到 Laravel 项目中：

composer require laravel/telescope

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

 php artisan telescope:install
 php artisan migrate

自定义迁移

如果不打算使用 Telescope 的默认迁移，则应在应用程序的App\Providers\AppServiceProvider 类的 register 方法中调用 Telescope::ignoreMigrations 方法。您可以使用以下命令导出默认迁移：php artisan vendor:publish--tag=scapel migrations

本地安装

如果您仅打算使用 Telescope 来帮助您的本地开发，您可以使用 --dev 标记安装 Telescope:

composer require laravel/telescope --dev

php artisan telescope:install

php artisan migrate

运行 telescope:install 后，应该从应用程序的 config/app.php 配置文件中删除TelescopeServiceProvider 服务提供者注册。相反，手动注册 telescope 的服务提供者在 App\Providers\AppServiceProvider 类的 register 方法中。在注册提供者之前，我们会确保当前环境是本地的:

/**
 * 注册应用服务
 *
 * @return void
 */
public function register()
{
    if ($this->app->environment('local')) {
        $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 命令：

$schedule->command('telescope:prune')->daily();

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

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

仪表板授权

访问 /telescope 即可显示仪表盘。默认情况下，您只能在 local 环境中访问此仪表板。在 app/Providers/TelescopeServiceProvider.php 文件中，有一个 gate 授权。此授权能控制在 非本地 环境中对 Telescope 的访问。您可以根据需要随意修改此权限以限制对 Telescope 安装和访问：

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

注意：你应该确保在生产环境中将 APP_ENV 环境变量更改为 Production。否则，你的 Telescope 调试工具将公开可用。

更新 Telescope

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

此外，升级到任何新的 Telescope 版本时，你都应该重建 Telescope 实例：

php artisan telescope:publish

为了使实例保持最新状态并避免将来的更新中出现问题，可以在应用程序的 composer.json文件中的 post-update-cmd 脚本添加 telescope:publish 命令：

{
    "scripts": {
        "post-update-cmd": [
            "@php artisan telescope:publish --ansi"
        ]
    }
}

过滤

单项过滤

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

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

/**
 * 注册应用服务
 *
 * @return void
 */
public function register()
{
    $this->hideSensitiveRequestDetails();

    Telescope::filter(function (IncomingEntry $entry) {
        if ($this->app->environment('local')) {
            return true;
        }

        return $entry->isReportableException() ||
            $entry->isFailedJob() ||
            $entry->isScheduledTask() ||
            $entry->hasMonitoredTag();
    });
}

批量过滤

filter 闭包过滤单个条目的数据，您也可以使用 filterBatch 方法注册一个闭包，该闭包过滤给定请求或控制台命令的所有数据。如果闭包返回 true，则所有数据都由 Telescope 记录：

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

/**
 * 注册应用服务
 *
 * @return void
 */
public function register()
{
    $this->hideSensitiveRequestDetails();

    Telescope::filterBatch(function (Collection $entries) {
        if ($this->app->environment('local')) {
            return true;
        }

        return $entries->contains(function ($entry) {
            return $entry->isReportableException() ||
                $entry->isFailedJob() ||
                $entry->isScheduledTask() ||
                $entry->hasMonitoredTag();
            });
    });
}

Telescope 允许你通过「tag」搜索条目。通常，标签是 Eloquent 模型的类名或经过身份验证的用户 ID，这些标签会自动添加到条目中。有时，您可能希望将自己的自定义标签附加到条目中。你可以使用 Telescope::tag 方法。 tag 方法接受一个闭包，该闭包应返回一个标签数组。返回的标签将与 Telescope 自动附加到条目的所有标签合并。您应该在 App\Providers\TelescopeServiceProvider 类中的 register 方法调用 tag 方法：

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

/**
 * 注册应用服务
 *
 * @return void
 */
public function register()
{
    $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 文件的 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'],
    ],
    ...
],

任务监视器

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

日志监视器

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

邮件监视器

邮件监视器允许您查看应用发送的邮件及其相关数据的浏览器内预览。您也可以将该电子邮件下载为 .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 （以KB为单位）选项限制记录的响应数据：

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

定时任务监视器

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

视图监视器

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

显示用户头像

Telescope 仪表盘显示保存给定条目时会有登录用户的用户头像。默认情况下，Telescope 将使用 Gravatar Web 服务检索头像。但是，您可以通过在 App\Providers\TelescopeServiceProvider 中注册一个回调来自定义头像 URL。回调将收到用户的 ID 和电子邮件地址，并应返回用户的头像 URL：

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

/**
 * 注册应用服务
 *
 * @return void
 */
public function register()
{
    // ...

    Telescope::avatar(function ($id, $email) {
        return '/avatars/'.User::find($id)->avatar_path;
    });
}

本文章首发在网站上。

Telescope 调试工具 8.5 8.5 8.x 7.x 6.x 5.8 5.7 5.6 5.5 5.4 5.3 5.2 5.1

Laravel Telescope

简介

安装

自定义迁移

本地安装

配置

数据修改

仪表板授权

更新 Telescope

过滤

单项过滤

批量过滤

标签

可用的观察者

批量监视器

缓存监视器

命令监视器

输出监视器

事件监视器

异常监视器

Gate 监视器

任务监视器

日志监视器

邮件监视器

模型监视器

消息通知监视器

数据查询监视器

Redis 监视器

请求监视器

定时任务监视器

视图监视器

显示用户头像

Telescope 调试工具

8.5

8.5 8.x 7.x 6.x 5.8 5.7 5.6 5.5 5.4 5.3 5.2 5.1