Eine Request-ID durchgängig mitführen: Edge, Logs, nachgelagerte Aufrufe und die Antwort

Ziel

Eine einzelne Anfrage über sämtliche Logs des Systems hinweg auffindbar machen, vom Reverse Proxy bis zum letzten nachgelagerten Dienst, mithilfe einer einzigen Kennung, die auch in der Antwort erscheint, welche die nutzende Person erhalten hat.

Voraussetzungen

Ein Reverse Proxy oder Gateway vor der Anwendung, strukturiertes Logging mit einem festen Feldsatz pro Eintrag sowie eine Möglichkeit, anfragebezogenen Zustand in der Anwendung zu halten (Thread-Local, contextvars.ContextVar in Python, ein Kontextobjekt in Go).

Schritte

1. Die Kennung in der äussersten Komponente erzeugen, die man selbst kontrolliert. nginx stellt $request_id bereit, dokumentiert als eindeutige Kennung aus 16 zufälligen Bytes in Hexadezimalform; sie ins Access-Log schreiben und stromaufwärts mit proxy_set_header X-Request-ID $request_id; weitergeben.
2. In der Anwendung den Header beim Eintreffen der Anfrage lesen. Einen mitgelieferten Wert nur nach Prüfung von Länge und Zeichensatz akzeptieren; andernfalls einen neuen erzeugen. Im anfragebezogenen Kontext speichern. In Python ist ein zu Beginn der Anfrage gesetzter ContextVar für Code und für aus diesem Kontext erzeugte asynchrone Tasks sichtbar, sodass keine Funktion einen zusätzlichen Parameter benötigt.
3. Die Kennung über den Filter oder Processor der Logging-Bibliothek jedem Logeintrag hinzufügen, als festen Feldnamen (request_id), den sich alle Dienste teilen.
4. Sie bei jedem ausgehenden HTTP-Aufruf weiterreichen, in Nachrichten-Header für eingereihte Arbeit und in den Auftragsdatensatz für Hintergrundaufgaben, damit die konsumierende Seite sie vor dem Loggen wiederherstellt.
5. Sie in der Antwort als X-Request-ID zurückgeben und auf Fehlerseiten sowie in API-Fehlerkörpern ausgeben, damit eine nutzende Person oder ein Teammitglied im Support sie zitieren kann.
6. Falls Tracing im Einsatz ist, die W3C-traceparent-Trace-ID (32 Hexadezimalzeichen) als Request-Kennung verwenden, statt eine zweite zu erfinden; dann teilen sich Logs, Traces und Antwort einen einzigen Schlüssel.
7. Mit einer einzelnen Anfrage testen: die Kennung aus der Antwort entnehmen und bestätigen, dass sie im Proxy-Log, im Log jedes Dienstes und im Log der Queue-konsumierenden Seite enthalten ist.

Erwartetes Ergebnis

Mit einer Kennung aus einer Fehlermeldung liefert eine einzige Suche die geordneten Logzeilen dieser Anfrage über alle Komponenten hinweg, und eine fehlende Komponente wird sofort als Lücke sichtbar.

Grenzen und Prüfbasis

Die Kennung dient ausschliesslich der Korrelation: Sie ist kein Session-Token, darf nicht zur Autorisierung verwendet werden, und ein vom Client gelieferter Wert ist nicht vertrauenswürdige Eingabe. Anfragen, die in viele nachgelagerte Aufrufe verzweigen, teilen sich eine Kennung; die Reihenfolge je Aufruf ergibt sich aus Zeitstempeln oder aus Spans. Wiederholungen verwenden die Kennung absichtlich erneut, wodurch doppelte Arbeit sichtbar wird.