Laravel Telescope（Laravel 望远镜）

介绍

Laravel Telescope (opens in a new tab) 是您本地 Laravel 开发环境的绝佳伴侣。Telescope 可以深入了解进入您应用程序的请求、异常、日志条目、数据库查询、排队任务、邮件、通知、缓存操作、计划任务、变量转储等更多内容。

安装

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

composer require laravel/telescope

安装 Telescope 后，使用 telescope:install Artisan 命令发布其资产和迁移。安装 Telescope 后，您还应该运行 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')) {
        $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 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 文件中，有一个授权门定义。此授权门控制在非本地环境中对 Telescope 的访问。您可以根据需要自由修改此门，以限制对您的 Telescope 安装的访问：

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

当升级到 Telescope 的新主要版本时，您务必仔细查看升级指南 (opens in a new tab)。

此外，在升级到任何新的 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 允许您通过“标签”搜索条目。通常，标签是 Eloquent 模型类名或经过身份验证的用户 ID，Telescope 会自动将其添加到条目中。偶尔，您可能想要将自己的自定义标签附加到条目上。要实现此目的，您可以使用 Telescope::tag 方法。tag 方法接受一个闭包，该闭包应返回一个标签数组。闭包返回的标签将与 Telescope 自动附加到条目的任何标签合并。通常，您应该在 App\Providers\TelescopeServiceProvider 类的 register 方法中调用 tag 方法：

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 文件的 ignore 选项中指定该命令：

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

转储观察器

转储观察器会在 Telescope 中记录并显示您的变量转储。在使用 Laravel 时，可以使用全局的 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 进行缓存，缓存命令也会被 Redis 观察器记录。

请求观察器

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

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

计划任务观察器

计划任务观察器会记录您的应用程序运行的任何计划任务的命令和输出。

视图观察器

视图观察器会记录渲染视图时使用的视图名称、路径、数据和“组合器”。

显示用户头像

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 '/avatars/'.User::find($id)->avatar_path;
    });
}

Laravel Socialite Laravel Valet