Telescope: debugging e monitoramento em desenvolvimento

O Laravel Telescope é um pacote de debugging e monitoramento desenvolvido especificamente para o ecossistema Laravel. Diferente de ferramentas genéricas como Clockwork ou Debugbar, o Telescope oferece uma visão completa e estruturada de todas as atividades que ocorrem durante o desenvolvimento de uma aplicação. Enquanto o Horizon foca exclusivamente no gerenciamento de filas Redis, o Telescope abrange requisições, consultas, exceções, logs, jobs, notificações e muito mais.

Para instalar o Telescope, os requisitos mínimos são Laravel 8.x ou superior e PHP 8.0+. A instalação é simples e direta:

composer require laravel/telescope

Instalação e Configuração Básica

Após a instalação via Composer, execute o comando de instalação do Telescope:

php artisan telescope:install

Este comando publica o arquivo de configuração config/telescope.php e os assets necessários. Em seguida, execute as migrações:

php artisan migrate

O arquivo config/telescope.php permite configurar filtros por ambiente, armazenamento e expiração de dados. Exemplo de configuração básica:

// config/telescope.php
return [
    'enabled' => env('TELESCOPE_ENABLED', true),

    'storage' => [
        'driver' => env('TELESCOPE_DRIVER', 'database'),
        'database' => [
            'connection' => env('DB_CONNECTION', 'mysql'),
            'chunk' => 100,
        ],
    ],

    'prune' => [
        'records' => 10000,
        'hours' => 48,
    ],

    'watchers' => [
        Watchers\RequestWatcher::class => [
            'enabled' => env('TELESCOPE_ENABLED', true),
            'size_limit' => 64,
        ],
        // Outros watchers...
    ],
];

Entendendo as Abas do Dashboard

O dashboard do Telescope apresenta várias abas que organizam os dados monitorados:

  • Requests: Requisições HTTP com tempo de resposta, cabeçalhos e payload
  • Commands: Comandos Artisan executados
  • Schedule: Tarefas agendadas
  • Dumps: Dados de dump() e dd()
  • Queries: Consultas SQL com tempo de execução
  • Logs: Registros de log do Laravel
  • Mail: E-mails enviados
  • Notifications: Notificações disparadas
  • Queues: Jobs de fila
  • Redis: Comandos Redis executados
  • Exceptions: Exceções com stack trace completo

Cada aba permite filtros por tipo de evento, data e usuário autenticado. O timeline visual mostra a sequência de eventos durante uma requisição.

Monitoramento de Requests, Queries e Exceptions

O Telescope rastreia detalhadamente cada requisição HTTP. Exemplo de como acessar dados de uma requisição específica:

// Em um controller qualquer
public function index()
{
    // O Telescope captura automaticamente:
    // - Tempo de resposta
    // - Cabeçalhos HTTP
    // - Dados da sessão
    // - Payload da requisição

    $users = User::with('posts')->get();

    return response()->json($users);
}

Para análise de consultas SQL lentas, o Telescope exibe o tempo de execução e o número de consultas. Exemplo de detecção de N+1 queries:

// Consulta que gera N+1 queries
$users = User::all();
foreach ($users as $user) {
    echo $user->posts->count(); // Gera uma consulta adicional para cada usuário
}

// Versão otimizada com eager loading
$users = User::with('posts')->get();
foreach ($users as $user) {
    echo $user->posts->count(); // Apenas 2 consultas no total
}

Exceções são capturadas com stack trace completo e contexto da requisição:

try {
    // Código que pode lançar exceção
    $result = riskyOperation();
} catch (\Exception $e) {
    // O Telescope registra automaticamente
    report($e);
}

Debugging com Dumps e Logs em Tempo Real

O Telescope integra-se perfeitamente com o helper dump():

public function processOrder(Order $order)
{
    $order->load('items', 'customer');

    dump($order->items); // Aparece na aba Dumps do Telescope
    dump($order->customer->name); // Rastreável individualmente

    // Processamento...

    return redirect()->route('orders.show', $order);
}

Para logs, o Telescope filtra por nível (emergency, error, warning, info):

Log::info('Processamento iniciado', ['order_id' => $order->id]);
Log::warning('Estoque baixo para o item', ['item_id' => $item->id]);
Log::error('Falha no pagamento', ['error' => $exception->getMessage()]);

Monitoramento de Filas, Jobs e Eventos

Jobs de fila são monitorados com status detalhados:

// app/Jobs/ProcessPayment.php
class ProcessPayment implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public $tries = 3;
    public $backoff = [5, 10, 15];

    public function handle()
    {
        // O Telescope mostra:
        // - Status: pending, running, failed
        // - Tempo de processamento
        // - Número de tentativas
        // - Payload do job

        $payment = PaymentService::process($this->order);

        if (!$payment->success) {
            $this->release(10); // Reagenda para tentativa
        }
    }
}

Eventos e listeners também são rastreados:

// App\Events\OrderShipped.php
class OrderShipped
{
    use Dispatchable, InteractsWithSockets;

    public function __construct(
        public Order $order
    ) {}
}

// No controller
event(new OrderShipped($order));
// Telescope mostra o evento e todos os listeners acionados

Personalização e Boas Práticas

Para criar watchers customizados:

// app/Telescope/Watchers/CustomWatcher.php
use Laravel\Telescope\Watchers\Watcher;
use Laravel\Telescope\IncomingEntry;

class CustomWatcher extends Watcher
{
    protected $watch = true;

    public function register($app)
    {
        $app['events']->listen('custom.event', function ($data) {
            if (!$this->shouldRecord($data)) {
                return;
            }

            $entry = IncomingEntry::make([
                'type' => 'custom',
                'data' => $data,
            ]);

            $this->record($entry);
        });
    }

    protected function shouldRecord($data)
    {
        return $this->watcherEnabled() && !$this->isProduction();
    }
}

Configuração de pruning automática:

// Agendar no Kernel.php
protected function schedule(Schedule $schedule)
{
    $schedule->command('telescope:prune --hours=48')->daily();
}

Para performance em produção, desabilite o Telescope:

// .env
TELESCOPE_ENABLED=false

Integração com Outras Ferramentas da Série

O Telescope complementa o Horizon no monitoramento de filas. Enquanto o Horizon gerencia workers e métricas, o Telescope fornece detalhes de cada job individual.

Para projetos com Livewire, o Telescope captura requisições AJAX e atualizações de componentes:

// Livewire component
class UserForm extends Component
{
    public $name;
    public $email;

    public function save()
    {
        dump($this->name, $this->email); // Rastreável no Telescope

        User::create([
            'name' => $this->name,
            'email' => $this->email,
        ]);
    }
}

Com Inertia.js, as requisições são monitoradas como requisições normais, permitindo depuração de props e dados compartilhados.

Referências