Arricchire i log Laravel: contesto utente, request ID e tag

Introduzione

Nel mondo delle applicazioni Laravel, i log sono la prima linea di difesa per individuare errori e analizzare il comportamento degli utenti. Tuttavia, i log di default spesso mancano di informazioni cruciali come il contesto dell'utente, un identificatore di richiesta univoco (request ID) e tag personalizzati che facilitano il raggruppamento dei dati. Questo articolo propone un checklist pratico per automatizzare l'arricchimento dei log, spiegando quali KPI monitorare e come interpretare i risultati per migliorare la observability e ridurre il MTTR.

1. Definire i KPI di logging

1.1 Metriche di base

• Rate di errore (error rate) – percentuale di richieste che generano eccezioni.
• Tempo medio di risposta (average response time) – indicatore di latenza complessiva.
• Throughput – numero di richieste al secondo.

1.2 KPI avanzati

• Richieste per utente – quantifica l’attività per singolo cliente.
• Durata delle transazioni per request ID – consente di tracciare il percorso completo di una singola operazione.
• Distribuzione dei tag personalizzati – aiuta a segmentare le richieste per feature, ambiente o tipo di payload.

Perché questi KPI? Misurare questi indicatori consente di correlare rapidamente un picco di errore a un utente specifico o a una specifica transazione, accelerando il processo di diagnosi.

2. Configurare il contesto utente

2.1 Middleware di autenticazione

Aggiungi un middleware che estragga l'ID utente dal token di autenticazione e lo inserisca nel log context.

use Closure;
use Illuminate\Support\Facades\Log;

class LogUserContext
{
    public function handle($request, Closure $next)
    {
        if ($user = $request->user()) {
            Log::withContext(['user_id' => $user->id]);
        }
        return $next($request);
    }
}

2.2 Propagazione del contesto

Assicurati che il contesto venga propagato anche nei job in coda e nei listener di eventi, altrimenti perderai la correlazione.

3. Generare e propagare il request ID

3.1 Generazione automatica

Laravel 9 include già un request_id middleware, ma è consigliabile personalizzarlo per garantire l'unicità globale.

use Illuminate\Support\Str;

class GenerateRequestId
{
    public function handle($request, Closure $next)
    {
        $requestId = (string) Str::uuid();
        $request->headers->set('X-Request-ID', $requestId);
        Log::withContext(['request_id' => $requestId]);
        return $next($request);
    }
}

3.2 Propagazione nei microservizi

Quando la tua applicazione chiama altri servizi, inoltra l'header X-Request-ID per mantenere la catena di tracciamento.

4. Creare tag personalizzati

4.1 Tipologie di tag

• Feature flag – indica se una funzionalità sperimentale è attiva.
• Ambiente – production, staging, testing.
• Tipo di payload – json, xml, form.

4.2 Implementazione

Utilizza un service provider per aggiungere i tag al contesto globale dei log.

public function boot()
{
    Log::withContext([
        'environment' => app()->environment(),
        'feature_flag' => config('feature.experimental') ? 'on' : 'off',
    ]);
}

5. Verifica e monitoraggio dei log arricchiti

5.1 Strumenti consigliati

• Lescopr APM – aggrega i log, visualizza i KPI e permette di filtrare per user_id, request_id e tag.
• Elastic Stack – indice i log e consente query avanzate.

5.2 Dashboard di esempio

1. Grafico a linee per il request rate per utente.
2. Tabella con le ultime 100 richieste contenenti un determinato request_id.
3. Heatmap dei tag per identificare le feature più soggette a errori.

6. Checklist operativa

• Aggiungere middleware per il contesto utente.
• Configurare generazione e propagazione del request ID.
• Definire e inserire tag personalizzati nel log context.
• Verificare che i job in coda ereditino il contesto.
• Configurare gli alert su KPI chiave (error rate, latency, throughput).
• Testare la ricerca dei log per user_id, request_id e tag.

Conclusione

Arricchire i log Laravel con contesto utente, request ID e tag personalizzati trasforma dati grezzi in informazioni azionabili, migliorando la capacità di diagnosi e riducendo il MTTR. Per approfondire, la documentazione di Lescopr descrive la configurazione passo dopo passo.