Laravel Telescope

简介

Laravel Telescope 是一个专门为 Laravel 框架打造的优雅的调试助手。Telescope 可以为进入应用的请求、异常、日志、数据库查询、队列任务、邮件、通知、缓存操作、调度任务、变量打印等所有操作提供洞察明细功能，因此，它将成为你本地 Laravel 开发环境的又一绝佳伴侣。

安装

我们可以使用 Composer 来安装 Telescope 到 Laravel 项目：

$ composer require laravel/telescope

安装完成后，使用 Artisan 命令 telescope:install 发布其公共资源，然后运行 migrate 命令执行数据库变更：

$ php artisan telescope:install
$ php artisan migrate

只在指定环境安装

如果我们计划只在本地开发环境安装 Telescope，可以在安装的时候使用 --dev 标记：

$ composer require laravel/telescope --dev

安装完成后，需要从 app 配置文件中移除 TelescopeServiceProvider Service Provider的注册。取而代之地，要手动在 AppServiceProvider 的 register 方法中注册它：

/**
 * Register any application services.
 *
 * @return void
 */
public function register()
{
    if ($this->app->isLocal()) {
        $this->app->register(TelescopeServiceProvider::class);
    }
}

此外，还要在 composer.json 文件中添加如下代码阻止自动发现 Telescope 扩展包：

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

迁移自定义

如果你不想使用 Telescope 的默认迁移，可以在 AppServiceProvider 的 register 方法中调用 Telescope::ignoreMigrations 方法。然后通过以下命令导出默认迁移文件进行自定义。

$ php artisan vendor:publish --tag=telescope-migrations

配置

发布完 Telescope 的公共资源后，它的配置文件位于 config/telescope.php。该配置文件允许我们配置监听选项 watchers，每个配置项都包含其用途说明，所以建议使用 Telescope 之前通篇读一下这个配置文件。

如果需要，我们可以完全禁止 Telescope 的数据收集功能，通过配置项 enabled 来设置即可：

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

数据清理

如果没有清理的话，telescope_entries 表会迅速累积记录。要缓解这一现状，需要通过调度任务每天运行 Artisan 命令 telescope:prune 来清理老数据：

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

默认情况下，所有 24 小时之前的数据都会被清理，你可以在运行上述命令的时候使用 hours 选项来决定要保存多长时间以内的 Telescope 数据。例如，下面这个命令将会删除所有 48 小时以前创建的数据：

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

后台授权

Telescope 可以通过 /telescope 后台访问。和 Horizon 一样，默认情况下，你只能在本地开发环境（local）下访问。在我们的 app/Providers/TelescopeServiceProvider.php 文件中，有一个 gate 方法，通过该访问控制方法，可以配置哪些用户可以在非本地环境访问 Telescope 后台，你可以根据需要随时修改该方法，以便限制对 Telescope 的访问：

/**
 * Register the Telescope gate.
 *
 * This gate determines who can access Telescope in non-local environments.
 *
 * @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 的resource：

$ php artisan telescope:publish

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

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

过滤

单个条目

我们可以通过 TelescopeServiceProvider 中注册的 filter 回调过滤 Telescope 记录的数据。默认情况下，该回调记录 local 环境中所有的数据以及其他环境中的异常、失败任务、调度任务和被打上监控标签的数据：

/**
 * Register any application services.
 *
 * @return void
 */
public function register()
{
    $this->hideSensitiveRequestDetails();
    Telescope::filter(function (IncomingEntry $entry) {
        if ($this->app->isLocal()) {
            return true;
        }
        return $entry->isReportableException() ||
            $entry->isFailedJob() ||
            $entry->isScheduledTask() ||
            $entry->hasMonitoredTag();
    });
}

批量过滤

filter 回调可用于过滤单个条目的数据，而 filterBatch 方法可用于注册过滤回调用来过滤给定请求或控制台命令对应的所有数据。如果该回调返回 true，则对应的条目都会被 Telescope 记录：

use Illuminate\Support\Collection;
/**
 * Register any application services.
 *
 * @return void
 */
public function register()
{
    $this->hideSensitiveRequestDetails();
    Telescope::filterBatch(function (Collection $entries) {
        if ($this->app->isLocal()) {
            return true;
        }
        return $entries->contains(function ($entry) {
            return $entry->isReportableException() ||
                $entry->isFailedJob() ||
                $entry->isScheduledTask() ||
                $entry->hasMonitoredTag();
            });
    });
}

标签

Telescope 允许我们通过“标签”搜索条目，通常，标签是 Eloquent 模型类名或者 Telescope 自动添加到条目的认证用户 ID。有时候，我们可能想要添加自定义的标签到条目，要实现这个功能，需要使用 Telescope::tag 方法。该方法接收一个返回标签数组的回调，回调返回的标签会被合并到 Telescope 自动维护的条目标签中。我们可以在 TelescopeServiceProvider 中调用 tag 方法：

use Laravel\Telescope\Telescope;
/**
 * Register any application services.
 *
 * @return void
 */
public function register()
{
    $this->hideSensitiveRequestDetails();
    Telescope::tag(function (IncomingEntry $entry) {
        if ($entry->type === 'request') {
            return ['status:'.$entry->content['response_status']];
        }
        return [];
    });
 }

有效的监控器

当执行请求或控制台命令时，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 监控器标签页，否则会被忽略。

事件监控器

事件监控器会记录所有应用分发事件记录负载数据、监听器和广播数据。Laravel 框架的内部事件则会被忽略。

异常监控器

异常监控器会为所有应用抛出的可报告异常记录数据和堆栈信息。

Gate 监控器

gate 监控器会记录应用 gate 和 policy 检查数据和结果。如果你想要排除监控器记录的特定权限检查，可以在 config/telescope.php 文件的 ignore_abilities 选项中指定它们：

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

任务监控器

任务监控器会记录应用分发的队列任务数据和状态。

日志监控器

日志监控器会记录应用写入的所有日志数据。

邮件监控器

邮件监控器允许你在浏览器中预览邮件以及与之相关联的数据，还可以以 .eml 格式下载邮件文件。

模型监控器

模型监控器会 Eloquent created、updated、restored 或者 deleted 事件触发时记录模型变更，你可以通过监控器的 events 选项指定记录哪些模型事件：

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

通知监控器

通知监控器会记录应用发送的所有通知。如果通知触发了邮件发送同时你也开启了邮件监控器，则该邮件还可以在邮件监控界面进行预览。

查询监控器

查询监控器记录应用执行的所有数据库查询对应的原生 SQL、绑定、执行时间。该监控器还会将时间慢于 100ms 的查询打上 slow 标签。你可以使用 show 选项自定义慢查询阈值：

'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 网络服务检索头像。但是，我们可以通过在TelescopeServiceProvider注册回调来自定义头像图片的URL，这个回调函数将接收用户的 ID 和电子邮件地址，并应返回用户的头像图片 URL：

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

/**
 * Register any application services.
 *
 * @return void
 */
public function register()
{
    Telescope::avatar(function ($id, $email) {
        return '/avatars/'.User::find($id)->avatar_path;
    });
}