Skip to main content
Verteiltes Tracing verfolgt eine Anfrage oder Operation durch instrumentierte Dienste. Ein Trace gruppiert die Spans dieser Arbeit. Jeder Span ist eine zeitlich gemessene Operation, zum Beispiel eine HTTP-Anfrage, ein Datenbankaufruf, eine Queue-Operation oder ein Hintergrundjob. Fehlt ein Span, bleibt ein Teil des Pfads unbekannt. Nutzen Sie einen Trace, wenn ein Log einen Fehler meldet, aber nicht den Pfad der Operation. Ein Trace kann zeigen:
  • Welche Operation die Anfrage gestartet hat.
  • Wo die Anfrage Zeit verbraucht hat.
  • Welche untergeordnete Operation einen Fehler zurückgegeben hat.
  • Welche Logs, Issues, Aktionen und Metriken dieselbe Trace-ID haben.
  • Welcher Dienst, welche Umgebung und welches Release jeden Span gesendet hat.

​
Felder von Trace und Span

Ein Root-Span startet einen Trace und hat keinen übergeordneten Span. Child-Spans haben dieselbe Trace-ID, eigene Span-IDs und eine Parent-ID. Nur diese IDs verbinden Operationen. Zeitstempel allein tun das nicht. LogBrew zählt einen Span nur dann als Fehler-Span, wenn sein status gleich error ist.

​
Eine Anfrage über mehrere Dienste

  1. Der Web-Dienst startet einen Server-Span für die Checkout-Route.
  2. Ein Zahlungs-Client erstellt einen Child-Span für seine ausgehende HTTP-Anfrage.
  3. Der Zahlungsdienst setzt den Trace mit einem eigenen Server-Span fort.
  4. Eine Datenbank-Hilfsfunktion zeichnet einen Child-Span für den Schreibvorgang auf.
  5. Die App sendet ein sicheres Fehler-Log innerhalb des aktiven Zahlungs-Span.
Alle fünf Einträge haben dieselbe Trace-ID. Erhält ein Dienst keinen Trace-Kontext, wird seine Arbeit nicht Teil des Trace, auch wenn sich die Zeiten überschneiden.

​
Kontext weitergeben

LogBrew-SDKs verwenden W3C Trace Context. Das Node.js-SDK setzt zum Beispiel einen gültigen eingehenden traceparent-Header mit einem neuen Anfrage-Span fort. Fehlt der Header oder ist er ungültig, startet es einen neuen Root. Logs, Issues, Aktionen und Metriken, die innerhalb dieses Anfragebereichs erfasst werden, tragen den Trace der Anfrage. Die Instrumentierung für ausgehende Aufrufe schreibt einen traceparent-Header nur an die Ziele, die Sie konfigurieren, zum Beispiel über tracePropagationTargets. Senden Sie Trace-Kontext nur an vertrauenswürdige, instrumentierte Dienste. Eine Trace-ID korreliert Operationen. Sie ist keine Authentifizierung. Auch eine Queue-Nachricht kann Trace-Kontext tragen. Rufen Sie in Node.js in der Producer-Operation createLogBrewQueueTraceHeaders() auf, um der Nachricht einen traceparent-Header hinzuzufügen. Übergeben Sie diesen Header im Consumer als traceparent an queueOperationWithLogBrewSpan(). Siehe Queue-Tracing in JavaScript. Die Integrationen für Anfragen und ausgehende Aufrufe in Node.js und Python zeichnen in Spans weder Anfrage- oder Antwort-Bodys noch Query-Strings, beliebige Header oder den rohen traceparent-Wert auf. Benennen Sie Spans nach Routen-Templates, nicht nach konkreten URLs. Die Integrationen für Ihre Laufzeitumgebung beschreibt der Leitfaden zur SDK-Integration.

​
Erfassungs-Spans

LogBrew speichert jedes neue Log, Issue, jede Aktion und jede Metrik mit einer Trace-ID. Verweist ein Signal in derselben Übermittlung auf keinen Span, fügt LogBrew dafür einen Erfassungs-Span hinzu: Die span_id des Signals kennzeichnet dann seinen Erfassungs-Span. Hatte das Signal keinen Trace-Kontext, erstellt LogBrew dafür eine neue Trace-ID. Dieser Trace zeigt, dass LogBrew das Signal gespeichert hat. Er zeigt keinen Anfragepfad. Lesen Sie die Erfassungs-Spans in einem Trace nicht als eine einzige Anfrage. Erfassungs-Spans zählen in span_count und error_span_count mit. Deshalb kann ein Fehler-Log dazu führen, dass --status error einen Trace auswählt, in dem keine Operation der Anwendung fehlgeschlagen ist. Lesen Sie die operation jedes Fehler-Span, bevor Sie einen Schluss ziehen.

​
Trace lesen

Verwenden Sie eine exakte Trace-ID aus einem Log, einem Issue oder einer Trace-Liste:
--status error wählt Traces mit mindestens einem Fehler-Span aus. --status ok wählt Traces ohne Fehler-Span aus. --min-duration-ms 500 wählt Traces aus, die 500 Millisekunden oder länger gelaufen sind. Lesen Sie zuerst die Dauer des Root-Span. Untersuchen Sie dann die längsten Child-Spans und die Fehlerstatus. Behalten Sie Projekt, Dienst, Umgebung und Release im Blick, damit ein Trace aus Staging nicht als Beleg für die Produktionsumgebung gilt. Ein Trace zeigt eine einzelne Ausführung, keine Leistungs-Baseline. Bevor Sie eine Leistungsänderung vorschlagen, vergleichen Sie mehrere Traces mit dem Verlauf der zugehörigen Metrik.

​
Trace-Zusammenfassung

GET /api/telemetry/traces/{trace_id}/summary liefert eine Zusammenfassung ohne Span-Attribute: Hat root_span.parent_span_id einen Wert, liegt der echte Root-Span nicht im Trace. Lesen Sie root_span dann nicht als Beginn der Anfrage.

​
Trace erklären

logbrew explain trace liefert eine Trace-Untersuchung:
analysis.causality ist evidence_only. Die Analyse beweist keine Grundursache. Die CLI fordert Antwortversion 3 an. Darin hat jedes zugehörige Issue, jede Aktion und jede Metrik zusätzlich ihre exakte span_id. Um einen Span mit seinem übergeordneten Span, seinen Child-Spans und den Grenzen zwischen Diensten zu untersuchen, führen Sie Folgendes aus:
topology.parent_chain_status zeigt, ob die Kette übergeordneter Spans vollständig ist:

​
Fehlender Trace-Kontext

Nicht jedes Ereignis hat einen Trace seiner Anfrage. Lesen Sie den Zustand des Trace: not_linked ist kein Fehler. Auch ein Trace mit available kann zeigen, dass das Ereignis keinen Anfragekontext hatte. Hat der Erfassungs-Span des Ereignisses keine parent_span_id, war beim Erfassen des Ereignisses kein Span aktiv. Hintergrundarbeit außerhalb eines Anfragebereichs führt oft zu diesem Ergebnis. So finden Sie eine fehlende Beziehung:
  1. Lesen Sie Projekt, Dienst, Umgebung, Release und Zeitpunkt des Ereignisses.
  2. Prüfen Sie, ob die Arbeit innerhalb einer instrumentierten Anfrage oder Operation gelaufen ist.
  3. Prüfen Sie, ob die Client- und Server-Integrationen den Kontext über diese Grenze weitergeben.
  4. Erfassen Sie nach der Korrektur der Instrumentierung ein neues Ereignis, und lesen Sie es.
Eine neue SDK-Version fügt früher gesendeten Ereignissen keinen Trace-Kontext hinzu. Verknüpfen Sie ein Ereignis nicht über Zeitstempel, Route, Nachricht oder Release mit einem Trace.

​
Tracing für ein Projekt planen

Beginnen Sie mit einer wichtigen Anfrage oder einem wichtigen Job, zum Beispiel dem Checkout. Instrumentieren Sie jeweils eine Grenze:
  1. Erstellen Sie einen Span für die eingehende Anfrage oder die Hintergrundoperation.
  2. Fügen Sie Child-Spans für wichtige ausgehende Aufrufe hinzu.
  3. Setzen Sie W3C Trace Context über vertrauenswürdige Dienstgrenzen fort.
  4. Senden Sie ein sicheres Log innerhalb des aktiven Span.
  5. Lesen Sie dieses Log, öffnen Sie seine Trace-ID, und prüfen Sie Root, Child-Spans, Dienst, Umgebung, Release, Status und Dauer.
Fügen Sie die nächste Grenze erst hinzu, wenn diese Prüfung erfolgreich ist. Ein gemeinsamer Trace zeigt eine Korrelation. Er beweist nicht, dass ein Span ein Issue verursacht hat. Um Span-Namen zu prüfen, führen Sie logbrew traces --project "<project_id>" --pagination cursor --json aus. Das Objekt naming_quality zählt die Traces auf dieser Seite mit einem generischen Root-Namen (generic_name_traces) oder einer nicht zugeordneten Route (unmatched_route_traces). Muss die Benennung verbessert werden, ist naming_quality.next_action.code gleich improve_trace_naming.