TOP-KT-011 - Logging en tracing
Beschrijving
Koppeltaal genereert informatie in het kader van een taak die toegekend wordt en/of activiteiten die plaats vindt door een participant, gegevensuitwisselingen tussen (verschillende) applicaties en logs met storingen en/of problemen in de context van Koppeltaal. Al deze informatie stelt zorgaanbieders, toezichthouders en cliënten/patiënten in staat om verschillende handelingen te kunnen volgen en naderhand te kunnen controleren, dat dit op een juiste manier gelogd en beheerd wordt.
Overwegingen
Verantwoordelijkheden
De logging binnen Koppeltaal vereist aandacht, met name omdat de logging in een architectuur waar verschillende systemen samenwerken de sleutel vormt tot goed begrip van (fout-) situaties. In Koppeltaal vervult het logging verschillende functies, waar het onderscheid wordt gemaakt tussen de volgende:
Toegangslog, wie heeft wat gedaan. Deze is vereiste voor de NEN-7513 norm, hier valt ook het starten en ontvangen van een launch onder.
Ketenlog, hoe tussen applicaties gebeurtenissen aan elkaar gekoppeld kunnen worden, dit geldt specifiek bij de launch en bij de abonnementen.
Verwerkingslog, dit log geeft aan welke problemen er zich hebben voorgedaan tijdens het verwerken van resources.
Het applicatielog, de logmeldingen van de applicatie. Deze vallen buiten de scope van Koppeltaal en zijn de verantwoordelijkheid van de applicatieleveranciers zelf.
Aangezien alle FHIR resources door de FHIR resource service verwerkt worden, wordt er in Koppeltaal voor gekozen de logging voor het grootste deel door de FHIR resource service te laten uitvoeren. Hiermee worden de applicatieleveranciers ontzorgt en worden inconsistenties en fouten voorkomen.
NEN-7513 en traceerbaarheid
Koppeltaal 2.0 moet voldoen aan de NEN-7513 norm rond traceerbaarheid, dit betekent dat van alle acties op de FHIR resources moet worden bijgehouden wie wat op welk moment heeft gelezen, geüpdatet, aangemaakt of verwijderd, zijnde de gebeurtenissen waarbij persoonlijke gezondheidsinformatie is verwerkt. Koppeltaal Logging moet het mogelijk maken "achteraf onweerlegbaar vast te stellen welke activiteiten waar en wanneer hebben plaatsgevonden in de gehele Koppeltaal keten". De NEN-7513 specificeert het detailniveau waarmee acties worden gelogd die bij een gebeurtenis plaatsvinden. Als er bijvoorbeeld gegevens zijn toegevoegd in een patiëntdossier zal dat als feit worden gelogd.
FHIR AuditEvent en de FHIR resource service
Het FHIR AuditEvent voldoet aan de eisen die er binnen Koppeltaal bestaan rond logging. Verder vinden veruit de meeste interacties plaats op de FHIR resource service. Daarom is er een mapping gemaakt tussen de NEN-7513 en het FHIR AuditEvent. Verder is ervoor gekozen om de FHIR resource service verantwoordelijk te maken voor het aanmaken van het merendeel van de log events, met uitzondering van de volgende events:
Het starten van een launch
Het ontvangen van een launch
Het melden van een verwerkingsprobeem van een specifieke resource.
Het authenticeren van een gebruiker buiten de Koppeltaal-authenticatieketen (Application User Authentication, zie de gelijknamige paragraaf — een SHOULD voor de applicatie).
Naast de FHIR resource service en de applicaties legt de Koppeltaalvoorziening zelf twee groepen events vast: de User-Authentication-events rond de launch (introspectie van het HTI launch token, de /authorize-call en de IdP-stappen — zie de paragraaf User Authentication) en de AuditEvents van de opschoning-lifecycle (zie de paragraaf AuditEvents voor de opschoning-lifecycle en TOP-KT-028 - Opschoning patiëntgegevens). Deze events zijn voor leveranciers vooral informatief; zij vormen het bewijsanker voor patiëntbetrokkenheid en daarmee voor de bewaartermijn.
Als leverancier is het dus goed om in de gaten te houden dat er situaties zijn waarin vereist wordt dat log entries worden aangemaakt. Specifiek het melden van niet goed verwerkte resources en problemen bij de launch worden verwerkt in TOP-KT-012 - Foutafhandeling en Statuscodes.
Relatie AuditEvent en _history
In het FHIR AuditEvent worden geen gegevens opgeslagen waarop de gebeurtenis betrekking heeft, echter, er wordt een relatie gelegd met de betrokken versies van de resources waarop de gebeurtenis betrekking heeft.
Ketenlogging
Koppeltaal maakt gebruik van drie headers in elk request die het mogelijk maken een keten van AuditEvents te kunnen creëren die verschillende gebeurtenissen over systemen kunnen vastleggen, namelijk de X-Request-id, X-Trace-id en X-Correlation-id. Deze doen zich met name voor in de volgende situaties:
Een launch
Bij notificaties van abonnementen.
De waarden in de headers zorgen ervoor dat de verschillende events die voortkomen uit dezelfde gebeurtenis gekoppeld kunnen worden.
Toepassing, restricties en eisen
Vastgelegde events
In de tabel hieronder wordt aangegeven welke events in Koppeltaal worden vastgelegd, wie er voor verantwoordelijk is en waar deze events worden beschreven.
Gebeurtenis | Verantwoordelijkheid | Beschreven in |
|---|---|---|
Alle normale interacties met de FHIR Resource Service | FHIR resource service | |
Alle foutmeldingen die voortkomen op de FHIR Resource Service | FHIR resource service | AuditEvent op outcome. |
Het starten en stoppen van applicatie(instanties). | Applicatie | |
Het starten van een launch | Applicatie | |
Het ontvangen van een launch | Applicatie | |
Authenticatie van patiënt /naaste aan de applicatiezijde (buiten keten) (SHOULD) | Applicatie | Tabel AuditEvent Applicatie User Authentication |
Het verzenden van een notificatie van een abonnement | FHIR resource service | |
Het ontvangen van een notificatie van een abonnement | Applicatie | |
Problemen met de verwerking van de gegevens | Applicatie | |
Problemen met het ontvangen van de launch | Applicatie | |
Authenticatie van een gebruiker in de keten (introspectie HTI launch token, | Autorisatieservice (Koppeltaalvoorziening) | User Authentication |
Statusovergangen van het opschoonproces (aankondiging, hold, unhold, grace-reset, afbreken, definitieve verwijdering) | Koppeltaalvoorziening | AuditEvents voor de opschoning-lifecycle |
Tracing en ketenlogging
De tracing wordt door middel van een drietal HTTP headers mogelijk gemaakt.
De X-Request-Id kan het beste gezien worden als een unieke request ID voor alle requests die in koppeltaal plaatsvinden. In asynchrone en/of notificaties kan er een hiërarchie van requests gemaakt worden door steeds een nieuw request ID voor elk request te maken, en de X-Correlation-Id is een unieke identifiër en wordt gecreëerd en ongewijzigd meegegeven met de response van de request. De X-Trace-id is ook een unieke identifier die aan een request wordt gegeven, deze wijkt af in hoe deze wordt doorgegeven; deze waarde moet, indien gevuld, ongewijzigd doorgegeven worden.
Deze headers worden hieronder in meer detail besproken.
X-Request-Id
De waarde van dit veld is globaal uniek en heeft een string waarde. Om globaal uniek te zijn wordt aangeraden een uuid v4 te gebruiken.
De X-Request-Id is uniek voor elk request, onafhankelijk of onderdeel is van een groter geheel.
Indien de waarde ontbreekt: in het request mag de ontvangende partij deze vullen met een waarde, elk request MOET uiteindelijk een waarde krijgen.
Implementatie uitvoerder: altijd een nieuwe waarde.
Implementatie ontvanger: opslaan indien er andere requests uit voortkomen, vullen met een eigen gegenereerde UUID v4 waarde indien ontbreekt of niet voldoet aan het UUID v4 formaat (zie LOG - Eisen (en aanbevelingen) voor logging, eis #7). De ontvanger MOET een nieuwe waarde genereren wanneer de X-Request-Id ontbreekt of ongeldig is. Loggen in het AuditEvent indien van toepassing. Teruggeven in het response als X-Request-Id header.
Mapping op AuditEvent: extension.request-id
X-Correlation-Id
De waarde van dit veld is globaal uniek en heeft een string waarde. Om globaal uniek te zijn wordt aangeraden een uuid v4 te gebruiken.
De X-Correlation-Id verwijst naar de X-Request-Id van het direct triggerende request Dit is het request dat causaal verantwoordelijk is voor het huidige request. Voorbeelden:
Een request dat voortkomt uit een notification gebruikt de
X-Request-Idvan die notification alsX-Correlation-IdEen request dat voortkomt uit de verwerking van een resource (bijv. een Patient ophalen omdat de Task een Patient referentie bevat) gebruikt de
X-Request-Idvan het resource-fetch request alsX-Correlation-IdEen request dat voortkomt uit de response van een ander request gebruikt de X-Request-Id van dat request als X-Correlation-Id
Parallelle requests die door dezelfde resource response worden getriggerd
(bijv. zowel Patient als ActivityDefinition ophalen na een Task response) gebruiken beide de X-Request-Id van dat resource-fetch request als X-Correlation-Id
Indien ontbreekt: leeg laten
Implementatie uitvoerder: leeg laten indien er geen bovenliggend request is, vullen met X-Request-Id van het direct triggerende request.
Implementatie ontvanger: loggen in het AuditEvent indien van toepassing. Indien de server een andere X-Request-Id heeft toegekend dan de waarde uit het inkomende request (bijv. omdat de inkomende waarde ongeldig was), dan MOET de server de oorspronkelijke X-Request-Id uit het request teruggeven als X-Correlation-Id response header, zodat de client de relatie tussen het oorspronkelijke request-id en het nieuwe server-assigned id kan herleiden.
Mapping op AuditEvent: extension.correlation-id
X-Trace-id
De waarde van dit veld is globaal uniek en heeft een string waarde. Om globaal uniek te zijn wordt aangeraden een uuid v4 te gebruiken.
De X-Trace-Id kan in verschillende requests met dezelfde waarde voorkomen om aan te geven dat deze requests aan elkaar gerelateerd zijn.
Indien de waarde ontbreekt: de ontvangende partij MAG een nieuwe X-Trace-Id genereren om een nieuwe trace context te starten. Het veld MAG ook leeg gelaten worden.
Implementatie uitvoerder: vullen met de X-Trace-Id waarde van het bovenliggende request indien aanwezig, anders leeg laten.
Implementatie ontvanger: opslaan indien er andere requests uit voortkomen. Indien de X-Trace-Id ontbreekt MAG een nieuwe waarde gegenereerd worden of leeg gelaten worden. Loggen in het AuditEvent indien van toepassing. Teruggeven als X-Trace-Id response header, zodat de aanvrager de trace context kan voortzetten. De ontvanger MOET de X-Trace-Id als response header teruggeven in het HTTP response. Dit stelt de aanvrager in staat om te verifiëren dat de ontvanger dezelfde trace context heeft gebruikt en om deze voort te zetten in eventuele vervolgacties.
Mapping op AuditEvent: extension.trace-id
X-Trace-id en de launch
In het geval van een launch wordt de waarde van de X-Trace-id gelijk gesteld aan de waarde van het HTI.jti veld. Deze wordt gebruikt voor het aanmaken van de relevante resources betrokken in de launch, waaronder het AuditEvent. Bij het AuditEvent wordt ook de waarde van extension.trace-id gevuld met de waarde van HTI.jti. De applicatie die die launch initieert vult voor de X-Trace-id en de waarde van het HTI.jti veld, of omgekeerd. Zolang beide maar gelijk zijn.
De ontvangende partij gebruikt de waarde van HTI.jti van het launch token voor bij de interactie met de FHIR resource service in de context van de launch en gebruikt voor de waarde van X-Trace-id de waarde van het HTI.jti veld. Ook hier geldt dat het betrokken AuditEvent de extension.trace-id gelijk heeft aan de waarde van HTI.jti. Zo wordt het mogelijk door middel van het HTI.jti veld de AuditEvents te correleren tussen applicaties.
Het AuditEvent
Binnen Koppeltaal onderscheiden we verschillende gebeurtenissen of activiteiten(event types) die gelogd worden. Voor de beschrijving en type van de verschillende velden zie de AuditEvent pagina.
Het AuditEvent is in principe een write once entiteit en wordt met een HTTP POST aangemaakt. De FHIR AuditEvent resource mag NOOIT aangepast of verwijderd worden met HTTP PUT, PATCH of DELETE. Het formaat van de FHIR AuditEvent resource wordt in XML of JSON formaat aangeleverd. Verder gelden alle andere eisen en beperkingen rond het aanmaken van resources.
Read
Veld | Waarde |
|---|---|
Extension velden | De volgende extension velden worden gebruikt:
|
Event type | Read |
FHIR AuditEvent voor Koppeltaal | RESTful operatie |
verantwoordelijke partij | FHIR Resource Provider |
| {
"system": "http://terminology.hl7.org/CodeSystem/audit-event-type"
"code": "rest"
"display": "RESTful Operation"
} |
| {
"system": "http://hl7.org/fhir/restful-interaction"
"code": "read"
"display": "read"
} |
|
|
| Indicatie van het resultaat van de gebeurtenis van het type AuditEventOutcome,
|
| Een beschrijving van het resultaat van de de gebeurtenis in het geval dat outcome == 0. Deze beschrijving van het resultaat is optioneel. De beschrijving van de fout in het geval de outcome <> 0. Voor de correcte weergave van de foutmelding wordt verwezen naar: |
| De referentie naar de applicatie die de actie uitvoert {
"reference": "Device/<id|client_id>"
} |