Skip to main content
Il tracciamento distribuito segue una richiesta o un’operazione attraverso i servizi strumentati. Una traccia raggruppa gli span di quel lavoro. Ogni span è un’operazione cronometrata, come una richiesta HTTP, una chiamata al database, un’operazione su una coda o un job in background. Se manca uno span, una parte del percorso resta sconosciuta. Usa una traccia quando un log segnala un errore ma non il percorso dell’operazione. Una traccia può mostrare:
  • Quale operazione ha avviato la richiesta.
  • Dove la richiesta ha impiegato tempo.
  • Quale operazione figlia ha restituito un errore.
  • Quali log, problemi, azioni e metriche hanno lo stesso ID traccia.
  • Quale servizio, ambiente e release hanno inviato ogni span.

​
Campi di traccia e span

Uno span radice avvia una traccia e non ha un padre. Gli span figli hanno lo stesso ID traccia, un proprio ID span e un ID padre. Solo questi ID collegano le operazioni. I timestamp da soli non bastano. LogBrew conta uno span come span di errore solo quando il suo status è error.

​
Una richiesta attraverso più servizi

  1. Il servizio web avvia uno span server per la route del checkout.
  2. Un client di pagamento crea uno span figlio per la sua richiesta HTTP in uscita.
  3. Il servizio di pagamento continua la traccia con un proprio span server.
  4. Un helper del database registra uno span figlio per la scrittura.
  5. L’app invia un log di errore sicuro dentro lo span di pagamento attivo.
Tutti e cinque i record hanno lo stesso ID traccia. Se un servizio non riceve il contesto di traccia, il suo lavoro non entra nella traccia, anche quando gli orari si sovrappongono.

​
Propaga il contesto

Gli SDK di LogBrew usano il contesto di traccia W3C. Ad esempio, l’SDK per Node.js continua un header traceparent in ingresso valido con un nuovo span di richiesta. Se l’header manca o non è valido, l’SDK avvia una nuova radice. Log, problemi, azioni e metriche acquisiti all’interno di quella richiesta contengono la traccia della richiesta. La strumentazione in uscita scrive un header traceparent solo verso le destinazioni che configuri, ad esempio con tracePropagationTargets. Invia il contesto di traccia solo a servizi attendibili e strumentati. Un ID traccia correla le operazioni. Non è un’autenticazione. Anche un messaggio in coda può contenere il contesto di traccia. In Node.js, chiama createLogBrewQueueTraceHeaders() nell’operazione del producer per aggiungere un header traceparent al messaggio. Nel consumer, passa quell’header a queueOperationWithLogBrewSpan() come traceparent. Consulta Tracciamento delle code in JavaScript. Le integrazioni di richiesta e in uscita per Node.js e Python non registrano negli span il corpo di richieste e risposte, le stringhe di query, header arbitrari o il valore grezzo di traceparent. Dai agli span il nome del modello di route, non dell’URL concreto. Per le integrazioni del tuo runtime, leggi la guida all’integrazione SDK.

​
Span di acquisizione

LogBrew memorizza ogni nuovo log, problema, azione e metrica con un ID traccia. Se un segnale non fa riferimento a uno span dello stesso invio, LogBrew aggiunge per quel segnale uno span di acquisizione: Lo span_id del segnale identifica quindi il suo span di acquisizione. Se il segnale non aveva un contesto di traccia, LogBrew crea per lui un nuovo ID traccia. Questa traccia mostra che LogBrew ha memorizzato il segnale. Non mostra il percorso di una richiesta. Non leggere gli span di acquisizione di una traccia come un’unica richiesta. Gli span di acquisizione contano in span_count e error_span_count. Per questo un log di errore può far selezionare a --status error una traccia in cui nessuna operazione dell’applicazione è fallita. Leggi l’operation di ogni span di errore prima di trarre una conclusione.

​
Leggi una traccia

Usa un ID traccia esatto preso da un log, da un problema o da un elenco di tracce:
--status error seleziona le tracce con almeno uno span di errore. --status ok seleziona le tracce senza span di errore. --min-duration-ms 500 seleziona le tracce durate 500 millisecondi o più. Leggi prima la durata dello span radice. Poi esamina gli span figli più lunghi e gli stati di errore. Tieni d’occhio progetto, servizio, ambiente e release, così una traccia di staging non diventa una prova sulla produzione. Una traccia mostra una singola esecuzione, non un riferimento per le prestazioni. Prima di proporre una modifica delle prestazioni, confronta più tracce con l’andamento della metrica correlata.

​
Riepilogo della traccia

GET /api/telemetry/traces/{trace_id}/summary restituisce un riepilogo senza gli attributi degli span: Se root_span.parent_span_id ha un valore, il vero span radice non è nella traccia. Non leggere root_span come l’inizio della richiesta.

​
Spiega una traccia

logbrew explain trace restituisce un’indagine sulla traccia:
analysis.causality vale evidence_only. L’analisi non dimostra una causa principale. La CLI richiede la versione 3 della risposta, in cui ogni problema, azione e metrica correlati hanno anche il proprio span_id esatto. Per esaminare uno span con il suo padre, i suoi figli e i confini tra servizi, esegui:
topology.parent_chain_status indica se la catena di padri è completa:

​
Contesto di traccia mancante

Non tutti gli eventi hanno una traccia della propria richiesta. Leggi lo stato della traccia: not_linked non è un errore. Anche una traccia available può mostrare che l’evento non aveva un contesto di richiesta. Se lo span di acquisizione dell’evento non ha parent_span_id, nessuno span era attivo quando l’app ha acquisito l’evento. Il lavoro in background fuori da una richiesta dà spesso questo risultato. Per trovare una relazione mancante:
  1. Leggi progetto, servizio, ambiente, release e ora dell’evento.
  2. Verifica che il lavoro sia avvenuto all’interno di una richiesta o di un’operazione strumentata.
  3. Verifica che le integrazioni client e server propaghino il contesto attraverso quel confine.
  4. Dopo aver corretto la strumentazione, acquisisci un nuovo evento e leggilo.
Una nuova versione dell’SDK non aggiunge il contesto di traccia agli eventi inviati in precedenza. Non collegare un evento a una traccia in base a timestamp, route, messaggio o release.

​
Pianifica il tracciamento per un progetto

Inizia con una richiesta o un job importante, come il checkout. Strumenta un confine alla volta:
  1. Crea uno span per la richiesta in ingresso o per l’operazione in background.
  2. Aggiungi span figli per le chiamate in uscita importanti.
  3. Continua il contesto di traccia W3C attraverso i confini tra servizi attendibili.
  4. Invia un log sicuro dentro lo span attivo.
  5. Leggi quel log, apri il suo ID traccia e verifica radice, figli, servizio, ambiente, release, stato e durata.
Aggiungi il confine successivo solo quando questo controllo è riuscito. Una traccia condivisa mostra una correlazione. Non dimostra che uno span abbia causato un problema. Per controllare i nomi degli span, esegui logbrew traces --project "<project_id>" --pagination cursor --json. L’oggetto naming_quality conta le tracce di quella pagina con un nome radice generico (generic_name_traces) o una route senza corrispondenza (unmatched_route_traces). Se i nomi richiedono attenzione, naming_quality.next_action.code vale improve_trace_naming.