Пакет 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
.
Только локальная установка
Если вы планируете использовать Telescope только для локальной разработки, то вы можете установить Telescope с параметром --dev
:
composer require laravel/telescope --dev
php artisan telescope:install
php artisan migrate
После запуска telescope:install
вы должны удалить регистрацию поставщика TelescopeServiceProvider
из файла конфигурации bootstrap/providers.php
вашего приложения. Вместо этого самостоятельно зарегистрируйте поставщика службы Telescope в методе register
вашего класса App\Providers\AppServiceProvider
. Прежде чем зарегистрировать поставщика, убедитесь, что текущее окружение является локальным:
/**
* Регистрация любых служб приложения.
*/
public function register(): void
{
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:
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, [
'[email protected]',
]);
});
}
Убедитесь, что вы изменили значение переменной
APP_ENV
наproduction
в эксплуатационном окружении. В противном случае доступ к Telescope будет публичным.
Обновление пакета Telescope
При обновлении до новой мажорной версии Telescope внимательно ознакомьтесь с руководством по обновлению.
Кроме того, при обновлении до любой новой версии Telescope вы должны повторно опубликовать ресурсы Telescope:
php artisan telescope:publish
Чтобы поддерживать актуальность ресурсов и избежать проблем в будущих обновлениях, вы можете добавить команду vendor:publish --tag=laravel-assets
в сценарий post-update-cmd
файла composer.json
вашего приложения:
{
"scripts": {
"post-update-cmd": [
"@php artisan vendor:publish --tag=laravel-assets --ansi --force"
]
}
}
Фильтрация
Фильтрация записей
Вы можете фильтровать данные, записываемые Telescope, с помощью замыкания метода filter
, определенного в вашем классе App\Providers\TelescopeServiceProvider
. По умолчанию это замыкание записывает все данные в локальном окружении, и в нелокальном окружении – исключения, неуспешные задания, запланированные задачи и данные с отслеживаемыми тегами:
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\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 или идентификаторы аутентифицированных пользователей, которые Telescope автоматически добавляет к записям. По желанию можно прикрепить к записям свои собственные метки. Для этого вы можете использовать метод Telescope::tag
. Метод tag
принимает замыкание, которое должно возвращать массив меток. Метки, возвращаемые замыканием, будут объединены с любыми метками, которые Telescope автоматически прикрепит к записи. Как правило, вызов метода tag
осуществляется в методе register
вашего класса App\Providers\TelescopeServiceProvider
:
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,
],
...
],
Наблюдатель Batch
Наблюдатель записывает информацию о пакетах в очереди, включая информацию о задании и соединении.
Наблюдатель Cache
Наблюдатель записывает данные, когда ключ кеша был запрошен (точнее, возврат значения либо его отсутствие), обновлен или удален.
Наблюдатель Command
Наблюдатель записывает аргументы, параметры, код выхода и вывод всякий раз, когда выполняется команда Artisan. Если вы хотите исключить определенные команды из записываемых наблюдателем, то вы можете указать команду в параметре ignore
в вашем файле config/telescope.php
:
'watchers' => [
Watchers\CommandWatcher::class => [
'enabled' => env('TELESCOPE_COMMAND_WATCHER', true),
'ignore' => ['key:generate'],
],
...
],
По умолчанию Telescope будет записывать только журналы на уровне error
и выше. Однако вы можете изменить параметр level
в файле конфигурации вашего приложения config/telescope.php
, чтобы изменить это поведение:
'watchers' => [
Watchers\LogWatcher::class => [
'enabled' => env('TELESCOPE_LOG_WATCHER', true),
'level' => 'debug',
],
// ...
],
Наблюдатель 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;
/**
* Регистрация любых служб приложения.
*/
public function register(): void
{
// ...
Telescope::avatar(function (string $id, string $email) {
return '/avatars/'.User::find($id)->avatar_path;
});
}