Wanneer een bewerking via een HTTP-request, een queue en een of meer externe services loopt, zijn de bijbehorende logs verspreid over verschillende processen. Zonder een gemeenschappelijk gegeven moet je bij het onderzoeken van een incident zoeken op tijdstip, gebruiker of inhoud. Die criteria kunnen ambigu of gevoelig zijn. Met een correlatie-ID in PHP kun je gebeurtenissen rond dezelfde bewerking groeperen en het verloop ervan reconstrueren.
Om goed te werken, moet de ID een duidelijke oorsprong hebben, expliciet worden doorgegeven over asynchrone grenzen heen en consistent in de logs verschijnen. Het is geen complete observability-oplossing en ook geen credential: de ID helpt gebeurtenissen aan elkaar te relateren, maar verklaart op zichzelf niet wat er misging en bepaalt niet wie bevoegd is.
Wat het oplost en wat erbuiten valt
Een correlatie-ID is een ondoorzichtige waarde die aan een request of bewerking is gekoppeld. Door de ID op te nemen in de applicatielogs, kun je berichten vinden die in verschillende componenten zijn geproduceerd en dezelfde waarde bevatten. Zo kun je bijvoorbeeld de ontvangst van een request koppelen aan het aanmaken van een job, het verwerken ervan en het antwoord van een externe API.
Dit maakt diagnoses eenvoudiger wanneer logs gecentraliseerd zijn en op velden kunnen worden doorzocht. Het garandeert echter niet dat alle componenten de ID correct hebben vastgelegd en meet geen duur, volume of geaggregeerde fouten. Metrics zijn geschikt voor trends en alerts; distributed traces tonen relaties en tijdsverloop tussen componenten; logs leveren gebeurtenissen en context. Het zijn aanvullende signalen.
Verwar correlatie ook niet met authenticatie, autorisatie of de identiteit van de gebruiker. Alleen kennis van een ID zou geen toegang tot gegevens mogen geven en geen bewerking mogen laten uitvoeren. Als de waarde in een URL of een systeem van derden terechtkomt, kan deze zichtbaar zijn voor meer mensen dan bedoeld.
Bepalen waar de ID wordt gegenereerd en hoe deze wordt gevalideerd
In een applicatie is de HTTP-middleware die het request ontvangt doorgaans het aangewezen punt om de context te starten. De middleware kan een binnenkomende ID accepteren om de continuïteit met een proxy of eerdere service te behouden, of een nieuwe ID genereren als er geen is. Het beleid moet expliciet zijn: alle externe waarden vertrouwen kan leiden tot onjuist gevormde of buitensporig lange invoer, of invoer die bedoeld is om logs te vervuilen.
Voor openbaar verkeer is een veilige optie om altijd een interne ID te genereren en, als de binnenkomende waarde behouden moet blijven, deze als niet-vertrouwde data te behandelen en strikt te valideren. Een alternatief is om de waarde uit de header alleen te accepteren van vertrouwde componenten, op basis van regels die aan de perimeter zijn ingesteld. De keuze hangt af van de architectuur en van wie de service kan aanroepen.
Het formaat moet eenvoudig te valideren zijn en compatibel met de systemen die de ID doorgeven. Je kunt een willekeurige waarde genereren met een cryptografische bron van het systeem, zoals random_bytes(), en deze coderen met een beperkte tekenset. Bouw de ID liever niet op uit tijdstempels, IP-adressen of persoonsgegevens. Een unieke ID hoeft geen bedrijfsinformatie prijs te geven.
$correlationId = bin2hex(random_bytes(16));
Dit voorbeeld genereert een willekeurige hexadecimale waarde; het schrijft geen universeel formaat voor. Stel een maximale lengte en toegestane tekens vast, evenals de header die de componenten gebruiken, bijvoorbeeld X-Correlation-ID. Als het platform al een tracingstandaard gebruikt, maak dan niet zonder noodzaak een parallel mechanisme: logcorrelatie en tracecontext kunnen naast elkaar bestaan, maar zijn geen identieke concepten.
De context over elke grens doorgeven
Valideer of genereer de ID aan het begin van het request in de middleware en voeg deze toe aan de loggingcontext. Als je de ID in een response aan de client terugstuurt, zorg er dan voor dat er geen aanvullende informatie wordt blootgegeven en dat het vertrouwensbeleid duidelijk is. De rest van de applicatie moet de context via een expliciete dependency ontvangen en niet afhankelijk zijn van moeilijk testbare globale variabelen.
Geef de ID binnen het PHP-proces door aan services die relevante gebeurtenissen loggen. Neem deze voor asynchrone jobs op in de berichtmetadata of in een daarvoor bestemd veld van de payload, volgens de conventies van het queuesysteem. Herstel bij het verwerken van het bericht de context voordat de job wordt uitgevoerd en wis deze na afloop. Dit is vooral belangrijk in langlopende processen waarin dezelfde worker opeenvolgende berichten verwerkt: een niet-gewiste context kan naar een andere bewerking lekken.
Geef bij het aanroepen van een externe API de waarde alleen door via een afgesproken header als de provider deze ondersteunt en delen ervan passend is. Verstuur geen onnodige interne gegevens. Leg bij integraties die headers niet behouden de ID vast samen met het lokale resultaat van de aanroep; ga er niet van uit dat het externe systeem de ID in zijn eigen logs teruggeeft.
Als een request meerdere onafhankelijke jobs oplevert, kan elke job de ID van de oorspronkelijke bewerking behouden. Als je subbewerkingen van elkaar moet onderscheiden, voeg dan voor elke subbewerking een eigen ID toe en leg de relatie vast via de tracecontext of niet-gevoelige bedrijfsvelden. Gebruik dezelfde waarde niet met verschillende betekenissen zonder dit te documenteren.
Gebruik de ID in gestructureerde logs, niet als vervanging voor observability
Leg de ID vast als een gestructureerd veld, bijvoorbeeld correlation_id, in plaats van deze alleen in een tekstuele zin op te nemen. Zo kan een logplatform gebeurtenissen filteren en groeperen zonder afhankelijk te zijn van benaderende zoekopdrachten. Hanteer een uniforme conventie voor de applicatie, workers en integraties, en controleer of de serializer het veld niet weglaat.
Neem de ID op in gebeurtenissen die nuttig zijn voor diagnoses: ontvangst van een request, aanmaak van het bericht, begin en einde van de job en het resultaat van een externe aanroep. Je hoeft de ID niet op elke regel te herhalen als het systeem per bewerking een persistente context biedt. Controleer in dat geval of de context tussen requests wordt gereset en of de logs begrijpelijk blijven wanneer een component de ID niet ondersteunt.
Gebruik de ID niet als metrieklabel met hoge cardinaliteit. Voor elk request een tijdreeks maken kan de kosten verhogen en metrics minder bruikbaar maken. Leg er ook geen tokens, wachtwoorden, betaalgegevens, volledige berichtinhoud of onnodige persoonsgegevens naast vast. Pas de regels van de organisatie voor dataminimalisatie, toegang en logbewaring toe.
Retries, uitgestelde uitvoering en fouten
Een retry van dezelfde job behoudt doorgaans de oorspronkelijke correlatie-ID: de retry maakt nog steeds deel uit van dezelfde logische bewerking. Leg een pogingnummer of een specifieke ID voor de poging vast om pogingen te onderscheiden, zonder de oorspronkelijke context te vervangen. Zo kun je zowel het volledige verloop als de oorzaak van elke uitvoering onderzoeken.
Als een job pas veel later wordt ingepland, bewaar de ID dan als persistente metadata; vertrouw niet op procesgeheugen of een HTTP-sessie die al is beëindigd. Als de job een nieuwe, zelfstandige bewerking start, bepaal dan of deze de oorspronkelijke context erft of een nieuwe krijgt, en leg de relatie tussen beide vast. Zo voorkom je dat een te breed toegepaste correlatie niet-gerelateerde taken door elkaar haalt.
Als de queue of een externe service metadata verwijdert, documenteer dan die grens en behoud de context in de component die je wel beheert. De applicatie moet bruikbaar blijven als de ID ontbreekt: genereer er een wanneer de verwerking begint of leg duidelijk vast dat de context niet beschikbaar was.
Tests en operationele controles
- Test de middleware met een ontbrekende, geldige en onjuist gevormde ID; bevestig dat het vastgestelde beleid wordt toegepast en dat de waarde binnen de grenzen blijft.
- Controleer of de ID van het request voorkomt in de logs van interne services en in de metadata van het bericht dat naar de queue wordt verstuurd.
- Verwerk een bericht in een worker en controleer of de context in de logs wordt opgenomen en vóór het volgende bericht wordt gewist.
- Simuleer een retry en bevestig dat de oorspronkelijke correlatie behouden blijft en dat je de poging kunt onderscheiden.
- Controleer de uitvoer van de externe aanroep en de foutafhandeling, zonder geheimen of gevoelige inhoud in de logs bloot te leggen.
- Controleer of dashboards en alerts niet afhankelijk zijn van het zoeken naar individuele ID's in metrics.
Bij een end-to-endcontrole volg je een testbewerking vanaf de HTTP-ingang tot en met de job en de integratie, en doorzoek je de logs op hetzelfde veld. Ontbreekt de ID in een deel van het traject, bepaal dan de exacte grens: middleware, berichtserialisatie, consumer, HTTP-client of loggerconfiguratie. Zo zie je waar de doorgifte moet worden hersteld, in plaats van lukraak extra logs toe te voegen.
De praktische keuze is om een kleine, expliciete en niet-gevoelige context te hanteren, met duidelijke regels voor vertrouwen en levenscyclus. Zo verkort een correlatie-ID in PHP de zoektijd tijdens een incident, zonder beveiligingsmaatregelen, traces, metrics of een zorgvuldig logontwerp te vervangen.
