1. O que é o Laravel Telescope e por que você precisa dele?

O Laravel Telescope é uma ferramenta poderosa para depuração e monitoramento de aplicações Laravel, desenvolvida pela própria equipe do Laravel. Ele oferece aos desenvolvedores uma "visão de inspetor" sobre o que acontece dentro da aplicação: desde requisições recebidas e consultas SQL até jobs de fila, exceções e logs. O Telescope funciona como um painel de controle que coleta e exibe toda a telemetria em tempo real.

Por que isso é necessário? No desenvolvimento web moderno, as aplicações estão cada vez mais complexas: usam filas, cache, APIs externas e consultas SQL complexas. Sem uma ferramenta como o Telescope, o desenvolvedor precisa adicionar manualmente dd() ou Log::debug() no código, o que retarda o desenvolvimento e não oferece uma visão completa. O Telescope coleta automaticamente dados de cada requisição, mostrando tempo de execução, número de consultas ao banco, memória utilizada e muito mais. Isso transforma a depuração de um palpite em uma ciência exata.

A principal vantagem do Telescope é sua discrição. Ele funciona "pronto para uso" e não exige alterações no código da aplicação. Os dados são armazenados em um banco de dados (MySQL ou SQLite por padrão), permitindo analisar o histórico de requisições. O Telescope é especialmente útil no desenvolvimento de APIs, trabalho com filas e depuração de páginas lentas.

2. Instalação

A instalação do Laravel Telescope é feita via Composer, o gerenciador de pacotes padrão para PHP. Execute o seguinte comando na raiz do seu projeto Laravel:

composer require laravel/telescope --dev

A flag --dev é importante: o Telescope é destinado apenas ao desenvolvimento local e não deve ser instalado em servidores de produção. Após instalar o pacote, é necessário publicar os assets (CSS/JS) e a configuração:

php artisan telescope:install

Este comando criará o arquivo de configuração config/telescope.php e uma migration para o banco de dados. Em seguida, execute a migration para criar as tabelas que armazenarão os dados do Telescope:

php artisan migrate

Depois disso, o Telescope estará disponível no endereço /telescope da sua aplicação. Se você estiver usando o Laravel Sail (Docker), não se esqueça de reiniciar os containers.

3. Início rápido — exemplo mínimo funcional

Após a instalação, o Telescope começa a coletar dados automaticamente. Você não precisa escrever nenhum código adicional. Basta abrir o navegador e acessar http://sua-app.test/telescope.

Você verá um painel com as abas: Requests, Commands, Schedule, Jobs, Exceptions, Logs, Dumps, Queries, Models, Mail, Notifications, Cache, Events, Gates.

Para verificar se tudo está funcionando, faça uma requisição simples a qualquer rota da sua aplicação. Por exemplo, abra a página inicial. Em seguida, vá até o Telescope e selecione a aba Requests. Você verá um registro da sua requisição com detalhes: método, URI, status, duração, número de consultas SQL, etc.

Aqui está um exemplo de como você pode adicionar dados manualmente ao Telescope para depuração:

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use App\Models\User;
use Laravel\Telescope\Telescope;

class UserController extends Controller
{
    public function show($id)
    {
        // O Telescope registrará esta requisição automaticamente