Monitorare le chiamate asincrone in Laravel Horizon con Lescopr

Lets Code
Scopri passo‑passo come tracciare le chiamate asincrone in Laravel Horizon, riducendo i colli di bottiglia e migliorando MTTR con Lescopr.

Introduzione

Le applicazioni Laravel che sfruttano Laravel Horizon per gestire code e job asincroni offrono scalabilità, ma spesso mancano di visibilità sui percorsi di esecuzione. Senza un tracciamento distribuito, gli incidenti si manifestano come timeout o retry incontrollati, aumentando il MTTR (Mean Time to Recovery) e minando le SLA. Questo articolo descrive, passo‑passo, come costruire un progetto completo che collega Laravel Horizon a Lescopr, ottenendo tracing end‑to‑end, metriche di latenza e dashboard operative.

Obiettivo: ridurre i tempi di individuazione dei colli di bottiglia da minuti a secondi, migliorando l'affidabilità complessiva dell'app.

1. Pianificazione del progetto

1.1 Definizione dei requisiti

  • Identificare tutti i queue driver (Redis, database) utilizzati.
  • Stabilire quali job richiedono tracciamento (es. invio email, generazione report).
  • Determinare i KPI di osservabilità: latenza media, tasso di errore, tempo di completamento.

1.2 Scelta della stack di tracing

Lescopr supporta OpenTelemetry e Jaeger. Per Laravel, il pacchetto lescopr/laravel-tracing fornisce un middleware pronto all'uso.

1.3 Milestone iniziali

  1. Configurazione di un ambiente di test con Horizon.
  2. Installazione del client Lescopr.
  3. Verifica della generazione di trace di base.

2. Implementazione tecnica

2.1 Installazione del pacchetto Lescopr

composer require lescopr/laravel-tracing
php artisan vendor:publish --tag=lescopr-config

Il file di configurazione config/lescopr.php consente di impostare l'endpoint del collector, il nome del servizio e le regole di campionamento.

2.2 Integrazione con Horizon

Modifica app/Providers/HorizonServiceProvider.php aggiungendo il middleware di tracing:

use Lescopr\Tracing\Middleware\TraceJobMiddleware;

public function boot()
{
    Horizon::auth(function ($request) {
        return true;
    });

    Horizon::whenJobProcessing(function ($job) {
        app(TraceJobMiddleware::class)->handle($job);
    });
}

Questo garantisce che ogni job venga avvolto in uno span, con attributi come job.id, queue.name e attempts.

2.3 Propagazione del contesto

Per mantenere il contesto tra job concatenati, aggiungi al Job base:

public function handle()
{
    $parentSpan = Lescopr::currentSpan();
    // ... esegui la logica del job
    Lescopr::endSpan();
}

In questo modo, i job figli erediteranno il trace ID del job genitore, consentendo una visualizzazione a grafo completa.

2.4 Configurazione del collector

Nel file .env:

LESCOPR_ENDPOINT=https://collector.lescopr.io
LESCOPR_SERVICE_NAME=laravel-horizon-app
LESCOPR_SAMPLING_RATE=0.75

Un tasso di campionamento del 75 % bilancia precisione e overhead di rete.

3. Verifica e ottimizzazione

3.1 Controllo dei trace

Accedi alla UI di Jaeger (o al dashboard Lescopr) e cerca il servizio laravel-horizon-app. Dovresti vedere una gerarchia di span che parte da queue:process fino al singolo job.

3.2 Analisi delle metriche

  • Latency: confronta la durata media dei job prima e dopo l'integrazione.
  • Error Rate: verifica se gli errori sono correlati a specifici job.
  • Throughput: osserva il numero di job completati al minuto.

3.3 Ottimizzazioni comuni

  • Ridurre la profondità di tracing per job ad alta frequenza.
  • Attivare il batch sampling per job di tipo bulk.
  • Utilizzare tags personalizzati per segmentare i trace per cliente.

4. Deployment e monitoraggio continuo

4.1 Pipeline CI/CD

Aggiorna il file ci.yml per includere il test di integrazione Lescopr:

- name: Test tracing
  run: php artisan test --filter=TracingTest

4.2 Alerting

Configura alert su SLA breach quando la latenza supera la soglia definita (es. 500 ms). Lescopr permette di creare regole di alert basate su query OpenTelemetry.

4.3 Documentazione interna

Crea una pagina Confluence con:

  • Diagramma dei flussi di tracing.
  • Guida rapida per aggiungere nuovi job al tracciamento.
  • Checklist di verifica per il rollout in produzione.

Conclusione

Tracciare le chiamate asincrone in un'app Laravel Horizon non è più un compito arduo: con Lescopr si ottiene un’integrazione pronta all’uso, visibilità completa sui job e metriche operative utili per ridurre MTTR e rispettare le SLA. Per approfondire, la documentazione di Lescopr descrive la configurazione passo dopo passo.