telescope.md

Laravel 9 · Пакет Laravel Telescope

• Введение
• Установка
  • Только локальная установка
  • Конфигурирование
  • Очистка накопленных данных
  • Авторизация доступа к панели управления
• Обновление пакета Telescope
• Фильтрация
  • Фильтрация записей
  • Фильтрация пакетов
• Добавление меток
• Доступные наблюдатели
  • Наблюдатель Batch
  • Наблюдатель Cache
  • Наблюдатель Command
  • Наблюдатель Dump
  • Наблюдатель Event
  • Наблюдатель Exception
  • Наблюдатель Gate
  • Наблюдатель HTTP Client
  • Наблюдатель Job
  • Наблюдатель Log
  • Наблюдатель Mail
  • Наблюдатель Model
  • Наблюдатель Notification
  • Наблюдатель Query
  • Наблюдатель Redis
  • Наблюдатель Request
  • Наблюдатель Schedule
  • Наблюдатель View
• Отображение аватара пользователя

Введение

Laravel Telescope станет прекрасным помощником при локальной разработке приложения Laravel. Telescope дает представление о запросах, поступающих в ваше приложение, исключениях, записях журнала, запросах базы данных, поставленных в очередь заданиях, почте, уведомлениях, операциях кэша, запланированных задачах, дампах переменных и о многом другом.

Установка

Для начала установите Telescope с помощью менеджера пакетов Composer в свой проект:

composer require laravel/telescope

После установки Telescope опубликуйте его ресурсы с помощью команды telescope:install Artisan. После установки Telescope вы также должны запустить команду migrate, чтобы создать таблицы, необходимые для хранения данных Telescope:

php artisan telescope:install

php artisan migrate

Настройка миграции

Если вы не собираетесь использовать миграции Telescope по умолчанию, то вам следует вызвать метод Telescope::ignoreMigrations в методе register поставщика App\Providers\AppServiceProvider. Вы можете экспортировать миграции по умолчанию, используя следующую команду: php artisan vendor:publish --tag=telescope-migrations.

Только локальная установка

Если вы планируете использовать Telescope только для локальной разработки, то вы можете установить Telescope с параметром --dev:

composer require laravel/telescope --dev

php artisan telescope:install

php artisan migrate

После запуска telescope:install вы должны удалить регистрацию поставщика TelescopeServiceProvider из конфигурационного файла config/app.php вашего приложения. Вместо этого самостоятельно зарегистрируйте поставщика службы Telescope в методе register поставщика App\Providers\AppServiceProvider. Прежде чем зарегистрировать поставщика, убедитесь, что текущее окружение является локальным:

/**
 * Регистрация любых служб приложения.
 *
 * @return void
 */
public function register()
{
    if ($this->app->environment('local')) {
        $this->app->register(\Laravel\Telescope\TelescopeServiceProvider::class);
        $this->app->register(TelescopeServiceProvider::class);
    }
}

Наконец, вы также должны предотвратить авто-обнаружение пакета Telescope, добавив в файл composer.json следующее:

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

Конфигурирование

После публикации ресурсов Telescope, его основной конфигурационный файл будет расположен в config/telescope.php. Этот файл конфигурации позволяет настроить параметры наблюдателя. Каждый параметр конфигурации включает описание своего назначения, поэтому обязательно внимательно изучите этот файл.

При желании вы можете полностью отключить сбор данных Telescope, используя параметр enabled конфигурации:

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

Очистка накопленных данных

Если не применять очистку, то таблица telescope_entries может очень быстро накапливать записи. Чтобы избежать этого, вы должны запланировать ежедневный запуск команды telescope:prune Artisan:

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

По умолчанию все записи старше 24 часов будут удалены. Вы можете использовать параметр hours при вызове команды, чтобы определить, как долго хранить данные Telescope. Например, следующая команда удалит все записи, созданные более 48 часов назад:

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

Авторизация доступа к панели управления

Доступ к панели управления Telescope можно получить по маршруту /telescope. По умолчанию вы сможете получить доступ к этой панели управления только в локальном (local) окружении. Однако в поставщике App\Providers\TelescopeServiceProvider есть определение шлюза авторизации. Этот шлюз авторизации контролирует доступ к Telescope в нелокальных окружениях. Вы можете изменить этот шлюз, чтобы ограничить доступ к вашей установке Telescope, если это необходимо:

/**
 * Регистрация шлюза Telescope.
 *
 * Этот шлюз определяют, кто может получить доступ к Telescope в нелокальном окружении.
 *
 * @return void
 */
protected function gate()
{
    Gate::define('viewTelescope', function ($user) {
        return in_array($user->email, [
            '[email protected]',
        ]);
    });
}

Предупреждение
Убедитесь, что вы изменили значение переменной APP_ENV на production в эксплуатационном окружении. В противном случае доступ к Telescope будет публичным.

Обновление пакета Telescope

При обновлении до новой мажорной версии Telescope внимательно ознакомьтесь с руководством по обновлению.

Кроме того, при обновлении до любой новой версии Telescope вы должны повторно опубликовать ресурсы Telescope:

php artisan telescope:publish

Чтобы поддерживать актуальность ресурсов и избежать проблем в будущих обновлениях, вы можете добавить команду telescope:publish в сценарий post-update-cmd файла composer.json вашего приложения:

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

Фильтрация

Фильтрация записей

Вы можете фильтровать данные, записываемые Telescope, с помощью замыкания метода filter, определенного в поставщике App\Providers\TelescopeServiceProvider. По умолчанию это замыкание записывает все данные в локальном окружении, и в нелокальном окружении – исключения, неуспешные задания, запланированные задачи и данные с отслеживаемыми тегами:

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->isSlowQuery() ||
            $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->isSlowQuery() ||
                $entry->hasMonitoredTag();
            });
    });
}

Добавление меток

Telescope позволяет искать записи по «метке». Часто метки представляют собой имена классов модели Eloquent или идентификаторы аутентифицированных пользователей, которые Telescope автоматически добавляет к записям. По желанию можно прикрепить к записям свои собственные метки. Для этого вы можете использовать метод Telescope::tag. Метод tag принимает замыкание, которое должно возвращать массив меток. Метки, возвращаемые замыканием, будут объединены с любыми метками, которые Telescope автоматически прикрепит к записи. Как правило, вызов метода tag осуществляется в методе register вашего класса App\Providers\TelescopeServiceProvider:

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,
    ],
    ...
],

Наблюдатель Batch

Наблюдатель записывает информацию о пакетах в очереди, включая информацию о задании и соединении.

Наблюдатель Cache

Наблюдатель записывает данные, когда ключ кеша был запрошен (точнее, возврат значения либо его отсутствие), обновлен или удален.

Наблюдатель Command

Наблюдатель записывает аргументы, параметры, код выхода и вывод всякий раз, когда выполняется команда Artisan. Если вы хотите исключить определенные команды из записываемых наблюдателем, то вы можете указать команду в параметре ignore в вашем файле config/telescope.php:

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

Наблюдатель Dump

Наблюдатель записывает и отображает дампы переменных в Telescope. При использовании Laravel переменные могут быть выведены с помощью глобальной функции dump. Чтобы дамп был записан, должна быть открыта вкладка в браузере наблюдателя за дампом, в противном случае вывод будет игнорироваться наблюдателем.

Наблюдатель Event

Наблюдатель записывает полезную нагрузку, слушателей и трансляцию данных любых событий, инициированных вашим приложением. Внутренние события фреймворка Laravel игнорируются данным наблюдателем.

Наблюдатель Exception

Наблюдатель записывает данные и трассировку стека для любых отчетных исключений, которые генерируются вашим приложением.

Наблюдатель Gate

Наблюдатель записывает данные и результаты проверок шлюза и политик вашего приложения. Если вы хотите исключить определенные полномочия из записываемых наблюдателем, то вы можете указать их в параметре ignore_abilities в вашем файле config/telescope.php:

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

Наблюдатель HTTP Client

Наблюдатель HTTP Client записывает исходящие запросы HTTP Client, сделанные вашим приложением.

Наблюдатель Job

Наблюдатель записывает данные и статус любых заданий, инициированных вашим приложением.

Наблюдатель Log

Наблюдатель записывает данные всех журналов, созданных вашим приложением.

Наблюдатель Mail

Наблюдатель позволяет вам просматривать в браузере письма, отправленные вашим приложением, вместе с соответствующими данными. Вы также можете загрузить электронное письмо в виде файла .eml.

Наблюдатель Model

Наблюдатель записывает изменения модели всякий раз, когда инициируется событие модели 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,
    ],
    ...
],

Наблюдатель Notification

Наблюдатель записывает все уведомления, отправленные вашим приложением. Если уведомление включает отправку электронного письма и у вас включен почтовый наблюдатель, то письмо также будет доступно для предварительного просмотра на экране почтового наблюдателя.

Наблюдатель Query

Наблюдатель записывает сырой SQL, связывания и время выполнения для всех запросов, инициированных вашим приложением. Наблюдатель также помечает любые запросы превышающие 100 миллисекунд как slow (медленные). Вы можете изменить порог медленного запроса, используя параметр slow наблюдателя:

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

Наблюдатель Redis

Наблюдатель записывает все команды Redis, инициированные вашим приложением. Если вы используете Redis для кеширования, то команды кеширования также будут записываться наблюдателем Redis.

Наблюдатель Request

Наблюдатель записывает данные запроса, заголовки, сессию и ответ, связанные с любым запросом, обрабатываемым приложением. Вы можете ограничить записываемые данные ответа с помощью параметра size_limit (в килобайтах):

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

Наблюдатель Schedule

Наблюдатель записывает команды и результаты выполнения любых запланированных задач, инициированных вашим приложением.

Наблюдатель View

Наблюдатель записывает имя шаблона, путь, данные и «компоновщики», используемые при отрисовки шаблонов.

Отображение аватара пользователя

В панели управления Telescope отображается аватар пользователя, который был аутентифицирован при сохранении каждой записи. По умолчанию Telescope получает аватары с помощью веб-службы Gravatar. Однако вы можете изменить URL-адрес аватара, зарегистрировав замыкание в своем классе App\Providers\TelescopeServiceProvider. Замыкание получит идентификатор пользователя и адрес электронной почты и должен вернуть 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;
    });
}