Laravel Telescope

• Введение
• Установка
  • Установка только локально
  • Настройка
  • Очистка данных
  • Авторизация панели
• Обновление Telescope
• Фильтрация
  • Записи
  • Пакеты
• Маркировка
• Доступные наблюдатели
  • Наблюдатель пакета
  • Наблюдатель кэша
  • Наблюдатель команды
  • Наблюдатель сброса
  • Наблюдатель событий
  • Наблюдатель исключений
  • Наблюдатель шлюза
  • Наблюдатель HTTP-клиента
  • Наблюдатель задания
  • Наблюдатель журнала
  • Наблюдатель почты
  • Наблюдатель модели
  • Наблюдатель уведомлений
  • Наблюдатель запроса
  • Наблюдатель Redis
  • Наблюдатель запросов
  • Наблюдатель расписания
  • Наблюдатель представления
• Отображение аватаров пользователей

Введение

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

Установка

Вы можете использовать менеджер пакетов Composer для установки Telescope в ваш проект Laravel:

composer require laravel/telescope

После установки Telescope опубликуйте его ресурсы с помощью команды Artisan telescope:install. После установки 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. Мы будем удостоверяться, что текущее окружение - local, перед регистрацией служб:

/**
 * Зарегистрируйте любые службы приложения.
 */
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, записи могут быстро накапливаться. Для смягчения этого эффекта вы должны запланировать выполнение команды Artisan telescope:prune ежедневно:

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

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

$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. По умолчанию это замыкание записывает все данные в среде 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 или идентификаторы аутентифицированных пользователей, которые 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,
    ],
    ...
],

Наблюдатель пакета

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

Наблюдатель кэша

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

Наблюдатель команды

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

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

Наблюдатель сброса

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

Наблюдатель событий

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

Наблюдатель исключений

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

Наблюдатель шлюза

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

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

Наблюдатель HTTP-клиента

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

Наблюдатель задания

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

Наблюдатель журнала

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

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

'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. Однако вы можете настроить 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;
    });
}