Quando un’operazione attraversa una richiesta HTTP, una coda e uno o più servizi esterni, i relativi log si distribuiscono tra processi distinti. Senza un dato comune, indagare su un incidente richiede ricerche per orario, utente o contenuto: criteri che possono essere ambigui o sensibili. Un ID di correlazione in PHP consente di raggruppare gli eventi legati a un’operazione e ricostruirne il percorso.
Per funzionare, l’ID deve avere un’origine definita, essere propagato esplicitamente attraverso i confini asincroni e comparire nei log in modo coerente. Non è una soluzione completa di osservabilità né una credenziale: serve a correlare gli eventi, non a spiegare da solo che cosa è andato storto o chi è autorizzato.
Che cosa risolve e che cosa resta escluso
Un ID di correlazione è un valore opaco associato a una richiesta o a un’operazione. Inserendolo nei log dell’applicazione, è possibile individuare i messaggi prodotti da componenti diversi che condividono quel valore. Per esempio, si possono correlare la ricezione di una richiesta, l’invio di un job, il suo consumo e la risposta di un’API esterna.
Questo migliora la diagnosi quando i log sono centralizzati e consultabili per campi. Non garantisce, tuttavia, che tutti i componenti abbiano registrato correttamente l’ID, né misura durata, volume o errori aggregati. Le metriche servono per tendenze e alert; le tracce distribuite mostrano relazioni e tempi tra i componenti; i log forniscono eventi e contesto. Sono segnali complementari.
La correlazione non va confusa con autenticazione, autorizzazione o identità dell’utente. Conoscere un ID non dovrebbe dare accesso ai dati né consentire di eseguire un’operazione. Se il valore viene esposto in un URL o a un sistema di terze parti, potrebbe essere visibile a più persone del previsto.
Definire dove viene generato e come viene convalidato
In un’applicazione, il punto abituale da cui avviare il contesto è il middleware HTTP che riceve la richiesta. Può accettare un ID in ingresso per mantenere la continuità con un proxy o un servizio precedente, oppure generarne uno nuovo se non è presente. La policy deve essere esplicita: fidarsi di tutti i valori esterni può consentire l’invio di input malformati, troppo lunghi o predisposti per contaminare i log.
Per il traffico pubblico, una scelta sicura consiste nel generare sempre un ID interno e, se occorre conservare il valore in ingresso, trattarlo come dato non attendibile e convalidarlo rigorosamente. Un’altra possibilità è accettare il valore dell’header solo da componenti attendibili, applicando regole configurate al perimetro. La scelta dipende dall’architettura e da chi può chiamare il servizio.
Il formato deve essere facile da convalidare e compatibile con i sistemi che lo trasportano. Si può usare un valore casuale generato con una sorgente crittografica del sistema, come random_bytes(), e codificato con un insieme limitato di caratteri. È meglio non costruirlo usando timestamp, indirizzi IP o dati personali. Un ID univoco non deve rivelare informazioni di business.
$correlationId = bin2hex(random_bytes(16));
Questo esempio genera un valore esadecimale casuale; non prescrive un formato universale. Definisci una lunghezza massima, i caratteri consentiti e l’header usato dai componenti, per esempio X-Correlation-ID. Se la piattaforma ha già adottato uno standard di tracing, evita di creare senza necessità un meccanismo parallelo: la correlazione dei log e il contesto di tracing possono coesistere, ma non sono concetti identici.
Propagare il contesto attraverso ogni confine
Nel middleware, convalida o crea l’ID all’inizio della richiesta e aggiungilo al contesto di logging. Se viene restituito al client in una risposta, assicurati che non esponga informazioni aggiuntive e che la policy di fiducia sia chiara. Il resto dell’applicazione dovrebbe ricevere il contesto tramite una dipendenza esplicita, senza affidarsi a variabili globali difficili da testare.
All’interno del processo PHP, passa l’ID ai servizi che registrano eventi rilevanti. Per i job asincroni, includilo nei metadati del messaggio o in un campo dedicato del payload, secondo le convenzioni del sistema di code. Quando il messaggio viene consumato, imposta il contesto prima di eseguire il job e cancellalo al termine. Questo è particolarmente importante nei processi di lunga durata, in cui lo stesso worker gestisce messaggi successivi: un contesto non cancellato può propagarsi a un’altra operazione.
Quando chiami un’API esterna, trasmetti il valore in un header concordato solo se il provider lo supporta e se è opportuno condividerlo. Non inviare dati interni non necessari. Per le integrazioni che non conservano gli header, registra l’ID insieme al risultato locale della chiamata; non dare per scontato che il sistema remoto lo restituisca nei propri log.
Se una richiesta genera più job indipendenti, ciascuno può conservare l’ID dell’operazione d’origine. Se invece occorre distinguere le sotto-operazioni, aggiungi un ID specifico per ciascuna e mantieni la relazione tramite il contesto di tracing o campi di business non sensibili. Evita di riutilizzare lo stesso valore con significati diversi senza documentarlo.
Usarlo nei log strutturati, non come sostituto dell’osservabilità
Registra l’ID come campo strutturato, per esempio correlation_id, invece di inserirlo soltanto in una frase di testo. In questo modo, una piattaforma di logging può filtrare e raggruppare gli eventi senza dipendere da ricerche approssimative. Adotta una convenzione uniforme tra applicazione, worker e integrazioni e verifica che il serializer non ometta il campo.
Includilo negli eventi utili alla diagnosi: ricezione della richiesta, creazione del messaggio, avvio e completamento del job e risultato di una chiamata esterna. Non è necessario ripeterlo in ogni riga se il sistema offre un contesto persistente per operazione. In tal caso, verifica che il contesto venga ripristinato tra una richiesta e l’altra e che i log restino interpretabili anche se un componente non lo supporta.
Non usare l’ID come label di metriche ad alta cardinalità. Creare una serie temporale per ogni richiesta può aumentare i costi e rendere le metriche poco utili. Inoltre, non registrare insieme all’ID token, password, dati di pagamento, contenuti integrali dei messaggi o informazioni personali non necessarie. Applica le regole dell’organizzazione in materia di minimizzazione, accesso e conservazione dei log.
Retry, esecuzioni differite e guasti
In genere, un retry dello stesso job mantiene l’ID di correlazione originale: fa ancora parte della stessa operazione logica. Per distinguere i tentativi, registra un numero di tentativo o un ID specifico, senza sostituire il contesto originale. In questo modo è possibile indagare sia sul percorso completo sia sulla causa di ogni esecuzione.
Se un job viene pianificato per essere eseguito molto più tardi, conserva l’ID come metadato persistente; non fare affidamento sulla memoria del processo né su una sessione HTTP ormai terminata. Se il job avvia una nuova operazione autonoma, stabilisci se eredita il contesto d’origine o ne riceve uno nuovo e registra la relazione tra i due. Questa decisione evita che una correlazione troppo ampia mescoli attività non correlate.
Quando la coda o un servizio esterno scarta i metadati, documenta il limite e conserva il contesto nel componente che controlli. L’applicazione deve restare operativa anche se l’ID manca: generane uno all’ingresso nel processo oppure registra chiaramente che il contesto non era disponibile.
Test e verifiche operative
- Testa il middleware con un ID assente, valido e malformato; conferma che applichi la policy definita e che il valore non superi i limiti stabiliti.
- Verifica che l’ID della richiesta compaia nei log dei servizi interni e nei metadati del messaggio inviato alla coda.
- Esegui un messaggio in un worker e verifica che il contesto venga aggiunto ai log e cancellato prima del messaggio successivo.
- Simula un retry e conferma che la correlazione originale venga mantenuta e che sia possibile distinguere il tentativo.
- Verifica l’output della chiamata esterna e la gestione degli errori, senza esporre segreti o corpi sensibili nei log.
- Controlla che dashboard e alert non dipendano dalla ricerca di singoli ID nelle metriche.
Una verifica end-to-end deve seguire un’operazione di test dall’ingresso HTTP al job e alla relativa integrazione, consultando i log tramite lo stesso campo. Se l’ID manca in un passaggio, individua il confine esatto: middleware, serializzazione del messaggio, consumer, client HTTP o configurazione del logger. Questa osservazione indica dove correggere la propagazione, invece di aggiungere log indiscriminatamente.
La scelta pratica consiste nel mantenere un contesto ridotto, esplicito e non sensibile, con regole chiare di fiducia e ciclo di vita. In questo modo, l’ID di correlazione in PHP riduce il tempo necessario per indagare durante un incidente, senza sostituire i controlli di sicurezza, le tracce, le metriche o una progettazione attenta dei log.
