Riesci a seguire un’azione non riuscita in tutto lo stack della tua app self-hosted? Una checklist per correlare i log
Usa un ID di richiesta o di correlazione, timestamp coerenti e un test controllato per verificare se i log del proxy, dell’applicazione, dei worker e delle dipendenze raccontano un’unica storia utile.
Mappa l’azione prima di cercare nei log
Parti da un errore visibile all’utente e traccia il percorso che potrebbe seguire l’operazione. Una mappa tipica dell’indagine include il reverse proxy, l’applicazione, un worker in background, il database e le eventuali dipendenze esterne coinvolte. Considerala un’ipotesi: una determinata applicazione potrebbe usare solo alcuni di questi componenti o gestire il lavoro in modo diverso.
Per ogni passaggio, annota quale servizio produce i log, dove è possibile consultarli e quale evento indicherebbe che l’azione è arrivata o è stata completata. In questo modo circoscrivi la ricerca, invece di esaminare indiscriminatamente messaggi non correlati.
- Annota l’azione, l’orario approssimativo e il risultato atteso.
- Elenca i componenti che potrebbero gestirla, inclusi gli eventuali worker asincroni.
- Registra come accedere ai log di ciascun componente e se è possibile cercarli per orario o campo.
- Segnala esplicitamente le lacune: un componente senza log accessibili non può contribuire alla traccia.
Scegli un identificatore e verifica dove viene mantenuto
Un ID di richiesta o un ID di correlazione può fornire un valore comune da cercare tra eventi correlati. Non dare per scontato che ogni servizio lo accetti, lo inoltri o lo registri. Controlla la configurazione effettiva e i log di ciascun componente del percorso.
Se una richiesta in ingresso contiene già un identificatore, decidi se mantenerlo o crearne uno in un punto del percorso che controlli. Non considerare attendibile un valore fornito dal client senza verificare come lo gestisce la tua applicazione. La prova pratica consiste nel verificare che lo stesso valore scelto compaia nei record pertinenti, non semplicemente che esista un’impostazione.
- Scegli un nome di campo e un formato che i tuoi componenti possano registrare in modo coerente.
- Controlla prima il proxy e l’applicazione, poi ogni componente a valle.
- Per i componenti che non puoi configurare, annota quali campi alternativi possono aiutarti a restringere la ricerca, come un intervallo temporale o un ID del job.
- Non inserire credenziali, token o informazioni personali nell’identificatore.
Prosegui la traccia nei processi in coda
Un’azione dell’utente può concludere la richiesta web prima che un’attività in coda inizi o venga completata. In tal caso, il solo log della richiesta potrebbe non mostrare l’esito. Verifica se l’applicazione passa un valore di correlazione al job in coda e se il worker lo registra quando avvia, conclude o non riesce a completare l’attività.
Se il sistema di gestione dei job usa un proprio ID, registra la relazione tra tale identificatore e l’ID della richiesta o di correlazione originale. Verifica questo comportamento con l’applicazione e la configurazione della coda che usi effettivamente: il supporto e i nomi dei campi variano.
- Verifica se l’evento di accodamento registra un ID del job e un ID di correlazione.
- Controlla se il worker registra l’avvio e l’esito finale dello stesso job.
- Se l’ID di correlazione non viene mantenuto, documenta il collegamento disponibile tra la richiesta e il job.
- Distingui un job che non è mai stato accodato da uno accodato ma non completato.
Rendi confrontabili timestamp e campi dei log
Per ottenere una traccia utile servono record confrontabili. Verifica quale fuso orario usa ciascun servizio, se i timestamp includono il fuso e se gli orologi sembrano non essere sincronizzati. Se gli eventi appaiono in ordine errato, consideralo un aspetto da indagare, invece di presumere che l’ordine visualizzato corrisponda alla sequenza effettiva.
Campi coerenti e strutturati facilitano i filtri. La documentazione di Datadog specifica che, prima di correlare i log con le trace, i log dovrebbero essere in formato JSON o analizzati dal processore di log appropriato a livello di linguaggio. Questa indicazione riguarda la correlazione con le trace; per un’indagine basata solo sui log, verifica che i tuoi strumenti di ricerca riescano a individuare in modo affidabile i campi necessari.
- Cerca un timestamp, il nome del servizio o del componente, il livello di gravità, il messaggio dell’evento e il campo di correlazione.
- Verifica che i timestamp indichino il fuso orario e che gli orologi dei servizi sembrino sincronizzati.
- Usa un nome di campo stabile per il valore di correlazione in tutti i componenti.
- Verifica come il visualizzatore dei log analizza i campi: non dare per scontato che un valore contenuto in testo non strutturato sia ricercabile come campo.
Esegui un test controllato di errore
Prima di affidarti alla traccia durante un incidente, provala con un’azione a basso rischio in un ambiente controllato o in un momento in cui puoi osservare il risultato in sicurezza. Usa un identificatore noto, attiva un errore che puoi riconoscere e poi cerca nei log di ogni componente. Non provocare un errore che potrebbe influire su dati importanti dei clienti o sulle operazioni aziendali.
Il test ha esito positivo solo se riesci a ricostruire una sequenza utile: dove è entrata l’azione, quale componente l’ha gestita, se il lavoro è stato accodato e dove l’errore è diventato visibile. Se la traccia si interrompe, annota il passaggio mancante e valuta se puoi aggiungere log o se ti serve un’altra fonte di riscontri.
- Usa un’azione di test con un esito di errore previsto e osservabile.
- Cerca usando l’ID di correlazione noto e confronta i record tra i componenti.
- Verifica che l’esito del worker possa essere collegato all’azione che lo ha avviato.
- Annota le lacune, i timestamp ambigui e i campi che non è stato possibile cercare.
Mantieni utile la traccia senza raccogliere dati in eccesso
I log diagnostici aiutano a indagare sul comportamento e sugli errori, ma possono contenere informazioni sensibili se le applicazioni o le configurazioni le registrano. Esamina i campi che il test rende visibili ed evita di registrare credenziali, token di accesso o dati personali non necessari per l’indagine.
Decidi chi deve poter accedere ai log e per quanto tempo devono restare disponibili in base alle tue esigenze operative. Queste scelte dipendono dall’applicazione, dai rischi e dai requisiti di governance: non presumere che l’hosting o la gestione dell’infrastruttura le risolvano automaticamente. Airbip gestisce l’infrastruttura cloud su cui si basano le applicazioni self-hosted e automatizza il routing e i certificati TLS, ma i clienti devono comunque comprendere le proprie modalità di accesso e conservazione dei log.
- Esamina esempi reali di log prima di ampliare la raccolta o condividere l’accesso.
- Limita l’accesso alle persone che ne hanno bisogno per attività operative o di sicurezza.
- Definisci deliberatamente i tempi di conservazione e verifica che siano ancora adeguati alle tue esigenze.
- Ricontrolla la registrazione dei log dopo modifiche all’applicazione o alla configurazione.
Sappi cosa possono — e non possono — dimostrare i log
Una traccia diagnostica correlata può aiutare a spiegare come si è sviluppato un errore, ma non costituisce automaticamente un resoconto completo di chi ha eseguito un’azione né garantisce che un record sia autorevole. Se ti servono prove affidabili delle azioni per finalità di responsabilità o governance, individua e mantieni separatamente i record di audit appropriati.
Documenta i limiti della traccia: componenti che non espongono log, campi che non vengono propagati, intervalli temporali scoperti ed eventi che non possono essere collegati con certezza. Un resoconto chiaro di ciò che i log dimostrano è più utile che considerare un ID di correlazione una prova di ogni passaggio.
- Usa i log diagnostici per indagare sul funzionamento e sugli errori.
- Verifica se le tue esigenze di responsabilità richiedono record di audit separati.
- Registra le lacune note ed evita di dichiarare completa una timeline quando le prove sono incomplete.
- Ripeti il test controllato quando cambiano componenti importanti o le modalità di registrazione dei log.
Domande frequenti
Tutti i servizi devono usare il tracing distribuito per correlare un’azione non riuscita?
No. Questa checklist si concentra sulla possibilità di collegare gli eventi di log correlati tramite un identificatore e confrontarli tra i componenti. Non presuppone che ogni servizio supporti il tracing distribuito. Controlla cosa registra effettivamente ogni componente e documenta le lacune.
E se un job in coda non include l’ID della richiesta originale?
Verifica se l’evento di accodamento registra un ID del job e se il worker registra lo stesso ID. Se non esiste un collegamento affidabile alla richiesta che ha avviato il job, annota la lacuna e valuta se l’applicazione o la configurazione del job possono registrare tale collegamento.
I log dell’applicazione dovrebbero essere in formato JSON?
I log strutturati possono rendere i campi più facili da individuare e cercare. La documentazione di Datadog specifica che, quando si correlano i log con le trace, i log dovrebbero essere in formato JSON o analizzati dal processore di log appropriato a livello di linguaggio. Verifica cosa riescono ad analizzare e cercare i tuoi strumenti.
I log diagnostici sono la stessa cosa dei record di audit?
Non dare per scontato che siano intercambiabili. I log diagnostici servono a indagare sul comportamento del sistema e sugli errori. Se ti serve un resoconto autorevole delle azioni per finalità di responsabilità o governance, determina quali record di audit separati siano appropriati per la tua applicazione e i tuoi requisiti.
L’infrastruttura gestita si occupa dell’accesso e della conservazione dei log?
Non darlo per scontato. Verifica le modalità effettive previste per la tua applicazione e il tuo hosting, compresi chi può accedere ai log e per quanto tempo vengono conservati. La gestione dell’infrastruttura non elimina la necessità di comprendere le tue responsabilità relative ai dati e alla governance.
Fonti e approfondimenti
- Correlate Logs and Traces — Datadog
- Application logs and agent traces in one view — Braintrust