Wenn ein Vorgang einen HTTP-Request, eine Queue und einen oder mehrere externe Dienste durchläuft, verteilen sich seine Logs auf verschiedene Prozesse. Ohne ein gemeinsames Merkmal muss man bei der Untersuchung eines Vorfalls nach Zeit, Benutzer oder Inhalt suchen – Kriterien, die mehrdeutig oder sensibel sein können. Eine Korrelations-ID in PHP ermöglicht es, die zu einem Vorgang gehörenden Ereignisse zusammenzufassen und seinen Ablauf nachzuvollziehen.
Damit das funktioniert, muss es eine definierte Quelle für die ID geben, sie muss explizit über asynchrone Grenzen hinweg übertragen werden und konsistent in den Logs erscheinen. Sie ist weder eine vollständige Observability-Lösung noch ein Zugangsschlüssel: Sie dient dazu, Ereignisse miteinander zu verknüpfen, erklärt aber nicht von selbst, was fehlgeschlagen ist oder wer dazu berechtigt ist.
Was sie leistet – und was nicht
Eine Korrelations-ID ist ein undurchsichtiger Wert, der einem Request oder Vorgang zugeordnet ist. Wird sie in die Anwendungslogs aufgenommen, lassen sich damit Meldungen aus verschiedenen Komponenten finden, die denselben Wert enthalten. So kann beispielsweise der Eingang eines Requests mit dem Einreihen eines Jobs, dessen Verarbeitung und der Antwort einer externen API verknüpft werden.
Das verbessert die Diagnose, wenn die Logs zentralisiert sind und sich nach Feldern abfragen lassen. Es garantiert jedoch nicht, dass alle Komponenten die ID korrekt protokolliert haben, und erfasst weder Dauer noch Umfang oder aggregierte Fehler. Metriken dienen zur Beobachtung von Trends und für Alerts; verteilte Traces zeigen Beziehungen und Zeitabläufe zwischen Komponenten; Logs liefern Ereignisse und Kontext. Diese Signale ergänzen einander.
Korrelation darf auch nicht mit Authentifizierung, Autorisierung oder der Identität eines Benutzers verwechselt werden. Die Kenntnis einer ID sollte weder den Zugriff auf Daten noch die Ausführung eines Vorgangs ermöglichen. Wird der Wert in einer URL oder einem Drittanbietersystem offengelegt, kann er für mehr Personen sichtbar sein als vorgesehen.
Festlegen, wo die ID erzeugt und wie sie validiert wird
In einer Anwendung ist die HTTP-Middleware, die den Request entgegennimmt, üblicherweise der Einstiegspunkt für den Kontext. Sie kann eine eingehende ID übernehmen, um die Kontinuität mit einem Proxy oder einem vorherigen Dienst zu wahren, oder eine neue erzeugen, wenn keine vorhanden ist. Die Richtlinie muss explizit sein: Allen externen Werten zu vertrauen, kann fehlerhafte oder übermäßig lange Eingaben zulassen oder Eingaben, die Logs gezielt verunreinigen sollen.
Für öffentlichen Traffic ist es eine sichere Möglichkeit, immer eine interne ID zu erzeugen und einen eingehenden Wert, falls er erhalten bleiben muss, als nicht vertrauenswürdige Daten zu behandeln und streng zu validieren. Eine weitere Möglichkeit ist, den Wert aus dem Header nur von vertrauenswürdigen Komponenten zu akzeptieren und die Regeln dafür am Netzwerkrand festzulegen. Die Wahl hängt von der Architektur und davon ab, wer den Dienst aufrufen kann.
Das Format sollte sich leicht validieren lassen und mit den Systemen kompatibel sein, die es übertragen. Verwendet werden kann ein Zufallswert, der mit einer kryptografischen Zufallsquelle des Systems wie random_bytes() erzeugt und mit einem begrenzten Zeichensatz kodiert wird. Er sollte nicht aus Zeitstempeln, IP-Adressen oder personenbezogenen Daten zusammengesetzt werden. Eine eindeutige ID muss keine Geschäftsinformationen preisgeben.
$correlationId = bin2hex(random_bytes(16));
Dieses Beispiel erzeugt einen zufälligen hexadezimalen Wert; es schreibt kein universelles Format vor. Lege eine maximale Länge, zulässige Zeichen und den Header fest, den die Komponenten verwenden, zum Beispiel X-Correlation-ID. Hat die Plattform bereits einen Trace-Standard eingeführt, solltest du nicht ohne Not einen parallelen Mechanismus schaffen: Log-Korrelation und Trace-Kontext können nebeneinander bestehen, sind aber keine identischen Konzepte.
Den Kontext über jede Grenze hinweg weitergeben
Validiere oder erstelle die ID zu Beginn des Requests in der Middleware und füge sie dem Logging-Kontext hinzu. Wenn sie in einer Antwort an den Client zurückgegeben wird, achte darauf, dass dadurch keine zusätzlichen Informationen offengelegt werden und die Vertrauensrichtlinie klar ist. Der übrige Teil der Anwendung sollte den Kontext über eine explizite Abhängigkeit erhalten und nicht von schwer testbaren globalen Variablen abhängen.
Gib die ID innerhalb des PHP-Prozesses an Dienste weiter, die relevante Ereignisse protokollieren. Nimm sie bei asynchronen Jobs in die Nachrichtenmetadaten oder – entsprechend den Konventionen des Queue-Systems – in ein eigenes Payload-Feld auf. Stelle beim Verarbeiten der Nachricht den Kontext wieder her, bevor du den Job ausführst, und lösche ihn nach Abschluss. Das ist besonders bei langlebigen Prozessen wichtig, in denen derselbe Worker nacheinander mehrere Nachrichten bearbeitet: Ein nicht bereinigter Kontext kann in einen anderen Vorgang übergehen.
Übermittle den Wert bei Aufrufen externer APIs nur dann in einem vereinbarten Header, wenn der Anbieter dies unterstützt und die Weitergabe angemessen ist. Sende keine unnötigen internen Daten. Bei Integrationen, die Header nicht beibehalten, protokolliere die ID zusammen mit dem lokalen Ergebnis des Aufrufs. Gehe nicht davon aus, dass das entfernte System sie in seinen eigenen Logs zurückgibt.
Erzeugt ein Request mehrere unabhängige Jobs, kann jeder davon die ID des ursprünglichen Vorgangs beibehalten. Müssen dagegen Teilvorgänge unterschieden werden, füge für jeden eine eigene ID hinzu und stelle die Beziehung über den Trace-Kontext oder nicht sensible Geschäftsfelder her. Verwende denselben Wert nicht ohne Dokumentation für unterschiedliche Bedeutungen.
In strukturierten Logs verwenden – nicht als Ersatz für Observability
Protokolliere die ID als strukturiertes Feld, zum Beispiel correlation_id, statt sie nur in einen Text einzufügen. So kann eine Logging-Plattform Ereignisse filtern und gruppieren, ohne auf ungenaue Suchanfragen angewiesen zu sein. Verwende einheitliche Konventionen für Anwendung, Worker und Integrationen und prüfe, ob der Serializer das Feld übernimmt.
Nimm die ID in für die Diagnose nützliche Ereignisse auf: Eingang des Requests, Erzeugung der Nachricht, Beginn und Ende des Jobs sowie Ergebnis eines externen Aufrufs. Sie muss nicht in jeder Zeile wiederholt werden, wenn das System pro Vorgang einen persistenten Kontext bereitstellt. Prüfe in diesem Fall, dass der Kontext zwischen Requests zurückgesetzt wird und die Logs auch dann verständlich bleiben, wenn eine Komponente ihn nicht unterstützt.
Verwende die ID nicht als Label für Metriken mit hoher Kardinalität. Eine Zeitreihe pro Request kann die Kosten erhöhen und die Metriken wenig nützlich machen. Protokolliere daneben auch keine Tokens, Passwörter, Zahlungsdaten, vollständigen Nachrichteninhalte oder unnötigen personenbezogenen Informationen. Halte die Vorgaben der Organisation zu Minimierung, Zugriff und Aufbewahrung von Logs ein.
Wiederholungsversuche, verzögerte Ausführung und Fehler
Bei einem erneuten Versuch desselben Jobs bleibt die ursprüngliche Korrelations-ID üblicherweise erhalten: Der Versuch gehört weiterhin zum selben logischen Vorgang. Um einzelne Versuche zu unterscheiden, protokolliere eine Versuchsnummer oder eine eigene ID für den jeweiligen Versuch, ohne den ursprünglichen Kontext zu ersetzen. So lässt sich sowohl der gesamte Ablauf als auch die Ursache jeder Ausführung untersuchen.
Wird ein Job erst wesentlich später ausgeführt, bewahre die ID als persistente Metainformation auf; verlasse dich nicht auf den Prozessspeicher oder eine bereits beendete HTTP-Sitzung. Startet der Job einen neuen, eigenständigen Vorgang, lege fest, ob er den Ursprungskontext übernimmt oder eine neue ID erhält, und protokolliere die Beziehung zwischen beiden. So verhinderst du, dass eine zu weit gefasste Korrelation nicht zusammengehörende Aufgaben vermischt.
Verwirft die Queue oder ein externer Dienst Metadaten, dokumentiere diese Grenze und bewahre den Kontext in der Komponente auf, die du kontrollierst. Die Anwendung muss auch ohne ID betriebsfähig bleiben: Erzeuge beim Eintritt in den Prozess eine ID oder protokolliere klar, dass kein Kontext verfügbar war.
Tests und betriebliche Prüfungen
- Teste die Middleware mit einer fehlenden, gültigen und fehlerhaften ID. Prüfe, ob sie die festgelegte Richtlinie anwendet und der Wert die Grenzwerte nicht überschreitet.
- Prüfe, ob die Request-ID in den Logs der internen Dienste und in den Metadaten der an die Queue gesendeten Nachricht erscheint.
- Verarbeite eine Nachricht in einem Worker und prüfe, ob der Kontext in die Logs aufgenommen und vor der nächsten Nachricht gelöscht wird.
- Simuliere einen erneuten Versuch und bestätige, dass die ursprüngliche Korrelation erhalten bleibt und der einzelne Versuch unterschieden werden kann.
- Prüfe die Ausgabe des externen Aufrufs und die Fehlerbehandlung, ohne Geheimnisse oder sensible Inhalte in den Logs offenzulegen.
- Stelle sicher, dass Dashboards und Alerts nicht davon abhängen, einzelne IDs in Metriken zu suchen.
Bei einer Ende-zu-Ende-Prüfung wird ein Testvorgang vom HTTP-Eingang über den Job bis zur Integration verfolgt. Dazu werden die Logs anhand desselben Feldes abgefragt. Fehlt die ID an einer Stelle, ermittle die genaue Grenze: Middleware, Nachrichtenserialisierung, Consumer, HTTP-Client oder Logger-Konfiguration. Diese Beobachtung zeigt, wo die Weitergabe korrigiert werden muss, statt wahllos zusätzliche Logs einzuführen.
Praktisch bedeutet das, einen kleinen, expliziten und nicht sensiblen Kontext mit klaren Regeln für Vertrauen und Lebenszyklus beizubehalten. So verkürzt eine Korrelations-ID in PHP bei einem Vorfall die Suchzeit, ohne Sicherheitskontrollen, Traces, Metriken oder eine durchdachte Logging-Architektur zu ersetzen.
