Laravel 5.7 中文文档

简体中文

English

简体中文

English

主题

Laravel Telescope ​

介绍 ​

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

安装 ​

exclamation

Telescope 需要 Laravel 5.7.7+。

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

php
composer require "laravel/telescope":"~1.0"

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

php
php artisan telescope:install

php artisan migrate

更新 Telescope ​

更新 Telescope 时，您应该重新发布 Telescope 的资产：

php
php artisan telescope:publish

仅在特定环境中安装 ​

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

php
composer require laravel/telescope --dev

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

php
use App\Providers\TelescopeServiceProvider;

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

迁移自定义 ​

如果您不打算使用 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',
        ]);
    });
}

过滤 ​

条目 ​

您可以通过在 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 观察器在请求或控制台命令执行时收集应用程序数据。您可以在 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 观察器 ​

exclamation

必须启用 Redis 事件才能使 Redis 观察器正常工作。您可以在 app/Providers/AppServiceProvider.php 文件的 boot 方法中调用 Redis::enableEvents() 来启用 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),
    ],
    ...
],

计划观察器 ​

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

版权所有 © 2024-2025 laravel.wiki