Идёт обновление сайта. Несколько дней возможны сбои в оформлении и переводах. Документация работает — если страница выглядит сломанной, обновите её позже.

Документация
L Laravel ✓ L intervention/image ✓
10.x ✓
🇷🇺 Русский ✓🇪🇸 Español ✓🇯🇵 日本語 ✓
Войти
Главная Laravel 10.x Laravel Telescope

Laravel Telescope

10.x 7 мар 2026 г.

#Введение

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

#Установка

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

composer require laravel/telescope

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

php artisan telescope:install

php artisan migrate

Наконец, вы сможете получить доступ к панели управления Telescope по маршруту /telescope.

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

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

#Только для локальной разработки

Если вы планируете использовать 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 определён authorization gate, который контролирует доступ к Telescope в не локальных окружениях. Вы можете изменить этот gate для ограничения доступа к вашей установке Telescope:

use App\Models\User;

/**
 * Зарегистрировать gate для Telescope.
 *
 * Этот gate определяет, кто может получить доступ к Telescope в не локальных окружениях.
 */
protected function gate(): void
{
    Gate::define('viewTelescope', function (User $user) {
        return in_array($user->email, [
            'taylor@laravel.com',
        ]);
    });
}
Внимание

Убедитесь, что в вашем production-окружении переменная окружения APP_ENV установлена в production. В противном случае ваша установка 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 или ID аутентифицированных пользователей, которые 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 игнорируются.

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

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

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

Наблюдатель Gate записывает данные и результаты проверок gate и policy, выполняемых вашим приложением. Чтобы исключить определённые способности из записи, укажите их в опции 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 model event. Вы можете указать, какие события моделей должны записываться, через опцию 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 для кэширования, команды кэша также будут записываться этим наблюдателем.

#Наблюдатель запросов (Request)

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

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

#Наблюдатель расписания

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

#Наблюдатель представлений

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

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

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