Observabilidade em Produção com Laravel Nightwatch

Quando um endpoint de checkout começa a estourar timeout às 2h da manhã, a diferença entre um fix rápido e um incidente longo quase sempre está na observabilidade. Você precisa saber qual controller rodou, quais queries foram executadas, se algum job entrou na fila e se uma chamada externa travou — tudo em uma única linha do tempo. Ferramentas APM genéricas chegam perto, mas tratam Laravel como mais um app PHP. O Laravel Nightwatch segue outro caminho: é uma plataforma de monitoramento hospedada, construída especificamente para Laravel, com conhecimento profundo de requisições, filas, tarefas agendadas, e-mail, notificações e todo o ciclo de vida do framework.

O Nightwatch chegou à disponibilidade geral em 2025 e se encaixa ao lado do Telescope e do Pulse na estratégia de observabilidade do Laravel. A distinção importa na prática. O Telescope serve para debug local. O Pulse entrega métricas agregadas de produção na sua própria infraestrutura. O Nightwatch é a camada gerenciada, pensada para produção, que armazena eventos individuais, conecta tudo em traces e transforma exceções recorrentes em issues rastreáveis. Se você já colocou Laravel em produção e ultrapassou a fase de ficar só olhando logs, o Nightwatch merece atenção de verdade.

Como o Nightwatch se encaixa no ecossistema Laravel

Antes de instalar qualquer coisa, vale entender onde cada ferramenta se encaixa:

Telescope — Self-hosted, excelente para inspecionar requisições durante o desenvolvimento. Não foi feito para tráfego alto em produção.
Pulse — Dashboard self-hosted com métricas agregadas como queries lentas, throughput de filas e carga do servidor. Leve e gratuito, mas não retém traces completos de eventos.
Nightwatch — SaaS hospedado que captura eventos individuais, monta contextos de execução e oferece alertas, gestão de issues e integrações com Slack e Linear.

Essas ferramentas se complementam, não se excluem. Muitos times debugam localmente com Telescope, mantêm o Pulse para um check rápido de saúde e confiam no Nightwatch quando precisam da história completa do que aconteceu na produção na terça passada às 14h03.

Arquitetura: por que o agent importa

O design do Nightwatch é o que o torna viável em produção. Ao instalar o pacote laravel/nightwatch, sua aplicação grava telemetria em um socket local. Um processo agent separado escuta em 127.0.0.1:2407 por padrão, agrupa os eventos recebidos e os envia para a nuvem do Nightwatch de forma assíncrona. A thread da requisição HTTP nunca fica esperando uma chamada de rede para um backend remoto de telemetria.

A documentação do Laravel estima o overhead em tipicamente menos de 3 milissegundos por requisição — um bom ponto de partida, embora você deva medir no seu próprio hardware e padrão de tráfego. Como o agent se conecta ao event dispatcher do Laravel, o Nightwatch enxerga conceitos do framework pelo nome: queries Eloquent, jobs enfileirados, commands agendados, hits de cache, chamadas HTTP externas e envios de e-mail. O valor não está na lista de tipos de evento. Está na correlação. Uma requisição lenta de checkout, as doze queries que ela disparou, o job que foi enfileirado e a notificação que esse job enviou depois aparecem em um único trace conectado.

Primeiros passos

A configuração é direta. Crie uma conta gratuita em nightwatch.laravel.com, crie uma organização e uma aplicação, escolha a região de dados (EUA, UE ou Austrália) e copie o token do ambiente.

Instale o pacote e configure o ambiente:

composer require laravel/nightwatch

Adicione o token ao .env:

NIGHTWATCH_TOKEN=seu-token-de-ambiente

Inicie o agent — ele precisa rodar continuamente em qualquer ambiente onde você queira coletar dados:

php artisan nightwatch:agent

Verifique se o agent está saudável com:

php artisan nightwatch:status

Em poucos minutos, requisições, queries e exceções devem aparecer no dashboard do Nightwatch. Em produção, rode o agent sob um monitor de processos. O Laravel oferece guias dedicados para Forge, Cloud, Vapor, Docker e outros provedores. No Forge, a integração oficial cuida da configuração do agent automaticamente, incluindo deploys multi-site onde cada aplicação precisa do seu próprio agent em uma porta separada.

Desabilite o Nightwatch localmente e nos testes para não poluir sua cota nem deixar a suíte mais lenta:

NIGHTWATCH_ENABLED=false

Adicione a mesma variável no phpunit.xml para manter o CI limpo.

O que você vê de fato no dashboard

O Nightwatch organiza a telemetria em torno de contextos de execução — o ponto de origem que disparou uma cadeia de atividades. No Laravel, existem três tipos de contexto: requisições HTTP, commands Artisan e tarefas agendadas. Tudo que acontece dentro desse contexto vira um evento filho em uma única linha do tempo.

Os tipos de evento capturados automaticamente incluem:

Requisições HTTP e chamadas externas de API
Queries de banco via Eloquent, query builder ou SQL puro
Jobs enfileirados e detalhes de execução
Tarefas agendadas e commands Artisan
Operações de cache, e-mail, notificações, logs e exceções

Ao abrir uma requisição lenta, você vê a decomposição de duração com precisão de microssegundos, cada query com seu tempo e qualquer chamada externa que contribuiu para a latência. Ao abrir uma exceção, o Nightwatch mostra o stack trace com código-fonte inline (configurável), número de usuários afetados, timestamps de primeira e última ocorrência e uma lista de ocorrências individuais ligadas ao contexto pai.

A unicidade das exceções é determinada por classe, código e arquivo/linha — não apenas pela mensagem. Esse agrupamento é o que torna o fluxo de issues útil. O Nightwatch cria automaticamente uma issue para cada exceção não tratada e associa novas ocorrências à issue existente, permitindo acompanhar a resolução ao longo do tempo em vez de correr atrás de alertas duplicados.

Gerenciando sua cota de eventos

O Nightwatch cobra por evento, não por host. Cada requisição, query, job, operação de cache, envio de e-mail e assim por diante conta como um evento dentro da franquia mensal. O plano gratuito oferece uma cota inicial generosa com janela de retenção menor; planos pagos aumentam tanto o limite de eventos quanto a retenção.

Para aplicações de alto tráfego, gerenciar a cota não é opcional. O Nightwatch oferece duas alavancas:

Sampling — Controla quais contextos de execução são capturados. Por exemplo, amostrar 10% das requisições reduz drasticamente o volume e ainda oferece uma visão representativa de performance.
Filtering — Exclui tipos específicos de evento dentro de contextos amostrados quando você sabe que são ruído.

Um comportamento importante para internalizar: por padrão, o Nightwatch captura todas as exceções, mesmo de requisições não amostradas. Se uma requisição lança erro, você recebe o trace completo independentemente da taxa de sampling. Esse é o default certo para a maioria dos times — você não quer perder erros de produção por causa de um sampling agressivo. Se precisar de controle mais rígido, defina NIGHTWATCH_EXCEPTION_SAMPLE_RATE=0 para capturar exceções apenas de contextos amostrados.

Revise o breakdown de uso por aplicação, ambiente e tipo de evento no dashboard de configurações. Se queries dominam sua cota em uma API read-heavy, considere filtrar eventos de query em endpoints conhecidamente rápidos ou aumentar o sampling em rotas de health-check que agregam pouco valor diagnóstico.

Segurança e dados sensíveis

Monitoramento de produção, por definição, toca dados sensíveis. O Nightwatch suporta redação de mensagens de exceção via callback registrado no service provider:

use Laravel\Nightwatch\Facades\Nightwatch;
use Laravel\Nightwatch\Records\Exception;

Nightwatch::redactExceptions(function (Exception $exception) {
    $exception->message = str_replace('secret', '***', $exception->message);
});

Desabilite a captura de código-fonte inline se seus stack traces puderem expor lógica proprietária em dashboards compartilhados:

NIGHTWATCH_CAPTURE_EXCEPTION_SOURCE_CODE=false

Escolha a região de dados na criação da aplicação conforme seus requisitos de compliance. A retenção varia por plano, então considere isso nos fluxos de investigação de incidentes — uma janela de 14 dias no plano gratuito funciona bem para debug ativo, mas pode não bastar para análise de tendências mensais.

Considerações de deploy

A maioria dos deploys tradicionais — Forge, VPS, Laravel Cloud — segue o mesmo padrão: instalar o pacote, configurar o token e rodar o agent como processo supervisionado em background.

Laravel Vapor exige uma abordagem diferente porque funções serverless não hospedam um agent de longa duração. O padrão documentado é rodar o agent em uma VM separada à qual sua aplicação Vapor se conecta. Adiciona infraestrutura, mas é o trade-off do compute serverless.

Múltiplas apps no mesmo servidor precisam de processos agent separados, cada um escutando em sua própria porta. Configure NIGHTWATCH_INGEST_URI por aplicação e inicie cada agent com a flag --listen-on correspondente. O Forge cuida disso automaticamente em setups multi-site.

Integrações e fluxos de trabalho em equipe

O Nightwatch se conecta às ferramentas que o time já usa. Notificações no Slack mantêm atualizações de issues nos canais existentes. A integração com Linear permite criar e vincular issues diretamente a partir dos detalhes de exceção do Nightwatch. Webhooks habilitam automações customizadas — disparar alerta no PagerDuty, postar em uma API interna ou acionar um workflow de rollback de deploy.

A plataforma também expõe um servidor MCP, o que significa que assistentes de IA podem consultar a telemetria da sua aplicação diretamente. É um fluxo de trabalho com visão de futuro que vale explorar se seu time já usa ferramentas habilitadas para MCP em resposta a incidentes.

Recomendações práticas

Com base em setups típicos de Laravel em produção, este é um caminho de adoção sensato:

Comece no staging — Instale o Nightwatch em staging primeiro. Confirme que o agent permanece saudável, verifique o volume de eventos contra a cota esperada e ajuste o sampling antes de habilitar produção.
Mantenha o Telescope local — Não substitua debug local por traces de produção. Use o Nightwatch para responder "o que aconteceu em prod" e o Telescope para "por que esse fluxo se comporta assim."
Monitore o monitor — Registre um handler de exceções irrecuperáveis para saber se o próprio Nightwatch falhou em silêncio. Escreva esses erros em um canal diferente do canal de log do Nightwatch.
Defina thresholds cedo — Configure regras de performance para endpoints críticos antes que um incidente force você a aprender o dashboard sob pressão.
Revise a cota mensalmente — O tráfego cresce. Uma estratégia de sampling que funcionou no lançamento pode precisar de ajuste seis meses depois.

Quando o Nightwatch é a escolha certa

O Nightwatch faz mais sentido quando Laravel é sua plataforma principal e você quer observabilidade profunda, consciente do framework, sem configurar um APM genérico do zero. O modelo de precificação por evento recompensa times que ajustam o sampling com critério em vez de capturar tudo cegamente.

É menos ideal se você precisa de um painel único em uma stack poliglota — um microsserviço Go, um worker Node.js e uma API Laravel reportando na mesma ferramenta. Datadog e plataformas similares ainda ganham em amplitude nesse cenário. Mas se sua superfície de produção é Laravel — requisições, filas, scheduler, e-mail, todo o ciclo — o Nightwatch entrega mais sinal por hora de configuração do que adaptar um APM genérico.

Monitoramento de produção deveria parecer uma extensão de como você já pensa em Laravel, não um sistema estranho que você acopla e torce para interpretar seu framework corretamente. O Nightwatch foi construído nessa premissa. Instale o agent, veja os primeiros traces chegando e, da próxima vez que algo quebrar às 2h da manhã, você terá uma linha do tempo conectada em vez de uma pasta de arquivos de log desconectados.