Correlatie en Tracing

Context

Op deze pagina worden de 2 aspecten i.v.m. het correleren van gebruikersacties en de achterliggende acties in het VHP gedocumenteerd. Deze aspecten zijn als volgt:

• Elke raadpleging of wijziging van informatie in het VHP moet kunnen worden gecorreleerd met de achterliggende gebruiker (of systeem) die de actie uitvoert. Dit stelt ons in staat om specifieke acties te traceren, vanaf het initiële verzoek van de eindgebruiker tot aan de uiteindelijke verwerking in het VHP.

• Technische tracing tussen de acties die gebeuren in een extern systeem en hun gevolgen in het VHP. Dit omvat het registreren van technische gebeurtenissen en hun impact binnen het platform, wat cruciaal is voor debugging en prestatieoptimalisatie.

Functionele Correlatie

Probleemstelling

Voor UI-aansluiters kan het VHP de acties en gevolgen koppelen aan de natuurlijke persoon die is ingelogd in de UI. Voor API-aansluiters kunnen de acties en gevolgen echter alleen gekoppeld worden aan de API-client en niet aan de achterliggende natuurlijke persoon die is ingelogd in de applicatie van de aansluiter.

Open

Correlatie headers

Om dit probleem op te lossen, introduceren we de X-Correlation-Id en X-Request-Id headers voor alle API-endpoints.

• De X-Correlation-Id header stelt de aansluiter in staat om de acties van de ingelogde gebruiker, die uit meerdere HTTP-requests kan bestaan, te koppelen aan een unieke identifier. Achteraf kan deze identifier worden gebruikt om de acties van de ingelogde gebruiker te linken met de overeenkomstige acties in het VHP, waardoor de auditlog compleet en sluitend is.

• De X-Request-Id header maakt het mogelijk om een specifieke HTTP-request te koppelen aan een unieke identifier. Deze identifier kan worden gebruikt om specifieke HTTP-requesten te debuggen en te achterhalen wat er precies is gebeurd, zonder dat een specifiek tijdstip nodig is.

Het VHP zal zowel de X-Correlation-Id als de X-Request-Id koppelen aan de HTTP-request van de API-client, wat zorgt voor een volledige traceerbaarheid en correlatie van acties.

Open

Als beide systemen de correlatie id in hun auditlog vastleggen, kan deze worden gebruikt om de actie in de applicatie van de aansluiter te koppelen aan de bijbehorende actie in het VHP.

Uniekheid

Voor correlatiedoeleinden is het essentieel dat zowel de X-Correlation-Id als de X-Request-Id header uniek zijn gedurende de levensduur van een API-aansluiting. We raden aan dat clients deze vereiste implementeren door UUID versie 4 (random) te gebruiken als waarde voor beide headers.

Technische tracing (optioneel)

Voor technische tracing maken we gebruik van de standaarden zoals gedefinieerd in de W3C Trace Context-specificatie. Deze standaarden stellen ons in staat om trace-informatie effectief te beheren en te delen tussen verschillende systemen.

Bij elke request kunnen de traceparent en tracestate headers worden meegestuurd.

• traceparent: Bevat de trace id en andere relevante tracing-informatie die helpt bij het volgen van de flow van een request door verschillende systemen en services.

• tracestate: Biedt extra informatie die door verschillende systemen kan worden gebruikt om context te bieden aan de trace id. Dit kan nuttig zijn voor het toevoegen van systeem-specifieke metadata aan de trace.

Door deze headers in elke request op te nemen, kunnen we een consistente en gedetailleerde trace van de requestflow waarborgen. Dit ondersteunt efficiëntere troubleshooting en draagt bij aan prestatieoptimalisatie.