Laravel Telescope

介绍
安装
升级 Telescope
过滤
- 条目
- 批次
标记
可用的观察者
显示用户头像

介绍

Laravel Telescope 是 Laravel 框架的一个优雅的调试助手。Telescope 提供对进入应用程序的请求、异常、日志条目、数据库查询、队列作业、邮件、通知、缓存操作、计划任务、变量转储等的洞察。Telescope 是本地 Laravel 开发环境的绝佳伴侣。

安装

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

php

composer require laravel/telescope "^3.0"

安装 Telescope 后，使用 telescope:install Artisan 命令发布其资产。安装 Telescope 后，您还应该运行 migrate 命令：

php

php artisan telescope:install

php artisan migrate

仅在特定环境中安装

如果您计划仅使用 Telescope 来协助本地开发，您可以使用 --dev 标志安装 Telescope：

php

composer require laravel/telescope "^3.0" --dev

运行 telescope:install 后，您应该从 app 配置文件中删除 TelescopeServiceProvider 服务提供者注册。相反，在 AppServiceProvider 的 register 方法中手动注册服务提供者：

php

/**
 * 注册任何应用程序服务。
 *
 * @return void
 */
public function register()
{
    if ($this->app->isLocal()) {
        $this->app->register(\Laravel\Telescope\TelescopeServiceProvider::class);
        $this->app->register(TelescopeServiceProvider::class);
    }
}

您还应该通过在 composer.json 文件中添加以下内容来防止 Telescope 包被自动发现：

php

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

迁移自定义

如果您不打算使用 Telescope 的默认迁移，您应该在 AppServiceProvider 的 register 方法中调用 Telescope::ignoreMigrations 方法。您可以使用 php artisan vendor:publish --tag=telescope-migrations 命令导出默认迁移。

配置

发布 Telescope 的资产后，其主要配置文件将位于 config/telescope.php。此配置文件允许您配置观察者选项，每个配置选项都包含其目的的描述，因此请务必彻底探索此文件。

如果需要，您可以使用 enabled 配置选项完全禁用 Telescope 的数据收集：

php

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

数据修剪

如果不进行修剪，telescope_entries 表可能会快速积累记录。为此，您应该安排 telescope:prune Artisan 命令每天运行：

php

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

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

php

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

仪表板授权

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

php

/**
 * 注册 Telescope 门控。
 *
 * 此门控决定谁可以在非本地环境中访问 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

php artisan telescope:publish

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

php

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

过滤

条目

您可以通过在 TelescopeServiceProvider 中注册的 filter 回调来过滤 Telescope 记录的数据。默认情况下，此回调在 local 环境中记录所有数据，并在所有其他环境中记录异常、失败的作业、计划任务和带有监控标签的数据：

php

/**
 * 注册任何应用程序服务。
 *
 * @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 记录：

php

use Illuminate\Support\Collection;

/**
 * 注册任何应用程序服务。
 *
 * @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 方法。tag 方法接受一个回调，该回调应返回一个标签数组。回调返回的标签将与 Telescope 自动附加到条目的任何标签合并。您应该在 TelescopeServiceProvider 中调用 tag 方法：

php

use Laravel\Telescope\Telescope;

/**
 * 注册任何应用程序服务。
 *
 * @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 配置文件中自定义要启用的观察者列表：

php

'watchers' => [
    Watchers\CacheWatcher::class => true,
    Watchers\CommandWatcher::class => true,
    ...
],

某些观察者还允许您提供其他自定义选项：

php

'watchers' => [
    Watchers\QueryWatcher::class => [
        'enabled' => env('TELESCOPE_QUERY_WATCHER', true),
        'slow' => 100,
    ],
    ...
],

缓存观察者

缓存观察者在缓存键被命中、未命中、更新和遗忘时记录数据。

命令观察者

命令观察者在执行 Artisan 命令时记录参数、选项、退出代码和输出。如果您希望排除某些命令不被观察者记录，您可以在 config/telescope.php 文件中的 ignore 选项中指定命令：

php

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

转储观察者

转储观察者记录并显示您的变量转储在 Telescope 中。在使用 Laravel 时，可以使用全局 dump 函数转储变量。转储观察者选项卡必须在浏览器中打开才能进行记录，否则转储将被观察者忽略。

事件观察者

事件观察者记录应用程序调度的任何事件的有效负载、监听器和广播数据。Laravel 框架的内部事件被事件观察者忽略。

异常观察者

异常观察者记录应用程序抛出的任何可报告异常的数据和堆栈跟踪。

门观察者

门观察者记录应用程序的门和策略检查的数据和结果。如果您希望排除某些能力不被观察者记录，您可以在 config/telescope.php 文件中的 ignore_abilities 选项中指定这些能力：

php

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

作业观察者

作业观察者记录应用程序调度的任何作业的数据和状态。

日志观察者

日志观察者记录应用程序编写的任何日志的数据。

邮件观察者

邮件观察者允许您查看电子邮件的浏览器预览及其相关数据。您还可以将电子邮件下载为 .eml 文件。

模型观察者

模型观察者在 Eloquent created、updated、restored 或 deleted 事件被调度时记录模型更改。您可以通过观察者的 events 选项指定应记录哪些模型事件：

php

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

通知观察者

通知观察者记录应用程序发送的所有通知。如果通知触发了电子邮件并且您启用了邮件观察者，则电子邮件也可以在邮件观察者屏幕上预览。

查询观察者

查询观察者记录应用程序执行的所有查询的原始 SQL、绑定和执行时间。观察者还将任何慢于 100ms 的查询标记为 slow。您可以使用观察者的 slow 选项自定义慢查询阈值：

php

'watchers' => [
    Watchers\QueryWatcher::class => [
        'enabled' => env('TELESCOPE_QUERY_WATCHER', true),
        'slow' => 50,
    ],
    ...
],

Redis 观察者

Redis 观察者记录应用程序执行的所有 Redis 命令。如果您使用 Redis 进行缓存，缓存命令也将被 Redis 观察者记录。

请求观察者

请求观察者记录应用程序处理的任何请求的请求、头、会话和响应数据。您可以通过 size_limit（以 KB 为单位）选项限制响应数据：

php

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

php

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

/**
 * 注册任何应用程序服务。
 *
 * @return void
 */
public function register()
{
    Telescope::avatar(function ($id, $email) {
        return '/avatars/'.User::find($id)->avatar_path;
    });
}

Laravel Telescope ​

介绍 ​

安装 ​

仅在特定环境中安装 ​

迁移自定义 ​

配置 ​

数据修剪 ​

仪表板授权 ​

升级 Telescope ​

过滤 ​

条目 ​

批次 ​

标记 ​

可用的观察者 ​

缓存观察者 ​

命令观察者 ​

转储观察者 ​

事件观察者 ​

异常观察者 ​

门观察者 ​

作业观察者 ​

日志观察者 ​

邮件观察者 ​

模型观察者 ​

通知观察者 ​

查询观察者 ​

Redis 观察者 ​

请求观察者 ​

计划观察者 ​

显示用户头像 ​

Laravel Telescope

介绍

安装

仅在特定环境中安装

迁移自定义

配置

数据修剪

仪表板授权

升级 Telescope

过滤

条目

批次

标记

可用的观察者

缓存观察者

命令观察者

转储观察者

事件观察者

异常观察者

门观察者

作业观察者

日志观察者

邮件观察者

模型观察者

通知观察者

查询观察者

Redis 观察者

请求观察者

计划观察者

显示用户头像