Monitoring: Laravel Pulse e integração com APMs

1. Introdução ao Monitoramento no Laravel

Aplicações PHP modernas, especialmente aquelas construídas com Laravel, operam em ecossistemas complexos com múltiplas camadas: filas, caches, bancos de dados, serviços externos e workers. Sem monitoramento adequado, problemas como lentidão gradual, vazamentos de memória e falhas em jobs passam despercebidos até afetarem usuários reais.

O monitoramento reativo — aquele que ocorre após uma falha — é insuficiente para aplicações em escala. O monitoramento proativo coleta métricas contínuas, estabelece baselines e alerta sobre anomalias antes que se tornem incidentes. O ecossistema Laravel oferece hoje duas abordagens complementares: o Laravel Pulse, ferramenta nativa de monitoramento em tempo real, e APMs (Application Performance Monitoring) como New Relic e Sentry, que fornecem tracing distribuído e análise profunda de performance.

2. Laravel Pulse: Primeiros Passos

O Laravel Pulse foi introduzido no Laravel 11 como um pacote oficial de monitoramento. Sua instalação é direta:

composer require laravel/pulse
php artisan vendor:publish --provider="Laravel\Pulse\PulseServiceProvider"
php artisan migrate

Após configurar o arquivo config/pulse.php, o dashboard fica acessível em /pulse. A interface exibe cards interativos que mostram:

  • Slow Requests — as requisições mais lentas dos últimos minutos
  • Jobs — status de execução de filas
  • Exceptions — erros agrupados por tipo e frequência
  • Cache — taxas de acerto e erro do cache
  • Slow Queries — consultas SQL que excedem thresholds configurados

Para filtrar por times ou ambientes específicos, você pode configurar usuários autorizados no arquivo de configuração:

// config/pulse.php
'users' => function () {
    return auth()->user()?->hasRole('developer');
},

3. Métricas Essenciais com Laravel Pulse

O Pulse captura automaticamente métricas críticas para qualquer aplicação Laravel. Vamos explorar as mais relevantes:

Requisições lentas e exceções — O pacote registra o tempo de execução de cada requisição e agrupa exceções por classe e mensagem. No dashboard, você vê quais endpoints estão degradados e quais erros estão se repetindo.

Filas e jobs falhos — O Pulse monitora o throughput e o tempo de processamento das filas. Jobs que falham repetidamente aparecem destacados, permitindo ação imediata:

// Exemplo de configuração no config/pulse.php
'recorders' => [
    \Laravel\Pulse\Recorders\JobRecorder::class => [
        'threshold' => 5000, // ms
    ],
],

Cache hits/misses e slow queries — O Pulse rastreia operações de cache e consultas SQL. Configurar thresholds adequados evita alarmes falsos:

// config/pulse.php
'recorders' => [
    \Laravel\Pulse\Recorders\SlowQueryRecorder::class => [
        'threshold' => 1000, // ms
    ],
],

4. Integração com APMs (Application Performance Monitoring)

Enquanto o Pulse oferece uma visão agregada e em tempo real, os APMs fornecem tracing distribuído — a capacidade de rastrear uma requisição através de múltiplos serviços, filas e bancos de dados.

New Relic — Para integrar com New Relic, instale o agente PHP e configure o arquivo newrelic.ini. No Laravel, você pode enviar transações personalizadas:

// App\Http\Middleware\NewRelicTransaction.php
public function handle($request, Closure $next)
{
    if (extension_loaded('newrelic')) {
        newrelic_name_transaction($request->method() . ' ' . $request->path());
        newrelic_add_custom_parameter('user_id', auth()->id());
    }
    return $next($request);
}

Sentry — O Sentry oferece performance tracing com integração nativa para Laravel:

composer require sentry/sentry-laravel

// config/sentry.php
'performance_tracing' => [
    'routes' => true,
    'queues' => true,
    'sql_queries' => true,
],

Com essa configuração, o Sentry captura automaticamente transações, spans de banco de dados e chamadas HTTP externas.

5. Enriquecendo Dados com Eventos e Listeners

O Laravel dispara eventos que podem ser usados para enviar métricas customizadas ao Pulse e aos APMs. Por exemplo, medir o tempo de resposta de um serviço externo:

// App\Listeners\MeasureExternalService.php
use Laravel\Pulse\Facades\Pulse;

public function handle(ServiceCalled $event)
{
    Pulse::record(
        'external_service_duration',
        $event->duration,
        ['service' => $event->serviceName]
    );
}

Para enviar ao Sentry ou New Relic, utilize os listeners apropriados:

// App\Listeners\SendToAPM.php
public function handle(ServiceCalled $event)
{
    \Sentry\addBreadcrumb([
        'category' => 'external_service',
        'message' => $event->serviceName,
        'data' => ['duration' => $event->duration],
    ]);
}

6. Alertas e Notificações Inteligentes

O Pulse permite configurar notificações via Slack, email ou outros canais quando thresholds são excedidos:

// config/pulse.php
'alerting' => [
    'thresholds' => [
        'slow_requests' => 2000, // ms
        'exception_rate' => 10,  // por minuto
    ],
    'notifications' => [
        \Laravel\Pulse\Notifications\SlackNotification::class => [
            'webhook_url' => env('SLACK_WEBHOOK_URL'),
        ],
    ],
],

Para evitar falsos positivos, implemente thresholds dinâmicos baseados em médias móveis:

// App\Services\DynamicThreshold.php
public function calculateThreshold(string $metric): float
{
    $baseline = Cache::get("pulse_baseline_{$metric}", 1000);
    return $baseline * 1.5; // 50% acima da média
}

7. Boas Práticas e Troubleshooting

Monitoramento deve ter overhead mínimo. Algumas práticas essenciais:

  • Amostragem — Configure amostragem para requisições de baixa prioridade:
// config/pulse.php
'sampling' => [
    'slow_requests' => 1.0,  // 100%
    'slow_queries' => 0.1,   // 10%
],

  • Logs combinados — Use o Pulse para identificar o problema e os logs para investigar a causa raiz. Ferramentas como Laravel Telescope ajudam na depuração local.

  • Problemas comuns — Timeouts de fila geralmente aparecem como jobs lentos no Pulse. Vazamentos de memória são identificados pelo crescimento contínuo do tempo de resposta mesmo sem aumento de carga.

8. Conclusão e Próximos Passos

O monitoramento contínuo é a base para aplicações Laravel resilientes. O Pulse oferece visibilidade imediata e de baixo custo, enquanto APMs como New Relic e Sentry fornecem tracing distribuído para cenários complexos. Juntos, eles formam um sistema de observação completo.

Para aprofundar, explore:

  • Laravel Dusk para testes de interface que simulam interações reais
  • Deployment pipelines com monitoramento de métricas pós-release
  • Security Headers e logs de auditoria

Checklist para produção:
1. Pulse configurado com thresholds realistas
2. APM integrado e testado em staging
3. Alertas configurados para canais de comunicação da equipe
4. Amostragem ajustada para evitar overhead

Referências