Laravel Telescope

Вступ
Встановлення
Оновлення Telescope
Фільтрація
- Записи
- Пакети
Тегування
Доступні спостерігачі (Watchers)
Відображення аватарів користувачів

Вступ

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

Встановлення

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

composer require laravel/telescope

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

 /**
 * Зареєструвати будь-які служби застосунку.
 */
public function register(): void
{
    if ($this->app->environment('local') && class_exists(\Laravel\Telescope\TelescopeServiceProvider::class)) {
        $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:

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, [
            'example@example.com',
        ]);
    });
}

Ви повинні переконатися, що змінюєте вашу змінну середовища 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']]
            : [];
    });
}

Доступні спостерігачі (Watchers)

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

Спостерігач Пошти

The mail watcher дозволяє вам переглядати в браузері попередній перегляд електронних листів, надісланих вашим застосунком, разом з їхніми асоційованими даними. Ви також можете завантажити електронний лист як файл .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. Зворотний виклик отримає ID користувача та адресу електронної пошти і повинен повернути URL зображення аватара користувача:

 use App\Models\User;
use Laravel\Telescope\Telescope;
 
/**
 * Зареєструвати будь-які служби застосунку.
 */
public function register(): void
{
    // ...
 
    Telescope::avatar(function (?string $id, ?string $email) {
        return ! is_null($id)
            ? '/avatars/'.User::find($id)->avatar_path
            : '/generic-avatar.jpg';
    });
}

Вступ
Встановлення
Оновлення Telescope
Фільтрація
- Записи
- Пакети
Тегування
Доступні спостерігачі (Watchers)
Відображення аватарів користувачів

	/**
	* Зареєструвати будь-які служби застосунку.
	*/
	public function register(): void
	{
	if ($this->app->environment('local') && class_exists(\Laravel\Telescope\TelescopeServiceProvider::class)) {
	$this->app->register(\Laravel\Telescope\TelescopeServiceProvider::class);
	$this->app->register(TelescopeServiceProvider::class);
	}
	}

	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();
	});
	}

	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();
	});
	});
	}

	use App\Models\User;
	use Laravel\Telescope\Telescope;

	/**
	* Зареєструвати будь-які служби застосунку.
	*/
	public function register(): void
	{
	// ...

	Telescope::avatar(function (?string $id, ?string $email) {
	return ! is_null($id)
	? '/avatars/'.User::find($id)->avatar_path
	: '/generic-avatar.jpg';
	});
	}