Dette dokument indeholder en beskrivelse af hvordan National Adviseringsservice 2 (herefter NAS2) driftes på et NSP Backend miljø.
Læseren forventes at have kendskab til Sundhedsdatastyrelsens platform NSP, samt generelt kendskab til WildFly applikation server, Docker, Docker Compose samt Ubuntu Linux operativ system.
Dato | Ansvarlig | Beskrivelse |
---|---|---|
TBD | Jacob Qvortrup | Draft udgave af driftvejledningen |
2020-10-30 | Jonas Pedersen | Tilføjet max batch størrelse ved id list oprettelse |
2020-12-14 | Jonas Pedersen | Tilføjet nye properties til pullpoint service. |
2020-12-17 | Jonas Pedersen | Tilføjet ny propery til pullpoint service og beskrevet ny statistik log. |
2021-02-10 | Tenna Rasmussen | Tilføjet beskrivelse af topic access |
Reference | Beskrivelse |
---|---|
NAS2 | National Adviseringsservice 2 |
NAS1 | National Adviseringsservice 1 |
NSP | Den nationale service platform |
Driften | NSP Leverandøren og NSP Driftleverandøren |
SDS | Sundhedsdatastyrelsen |
Installationsvejledning | NAS2 - Installationsvejledning |
Konfiguration af NAS2 sker i filerne i "compose/configuration" mappen som beskrevet i installationsvejledningen. I det følgende gennemgåes hver enkelt services konfigurationsfiler i detaljer.
Denne service konfigureres i filerne "notificationbroker.properties" og "log4j-notificationbroker.xml".
Property | Beskrivelse |
---|---|
kafka.producer.bootstrap.servers | Kommasepareret liste af Kafka servere som NAS2 skal anvende. Denne liste bør indeholde alle noderne i Kafka clusteret |
kafka.producer.client.id | Navnet som NAS2 vil fremgå med i listen af Producers på et Kafka Cluster. |
nsp.kafka.producer.component.name | Navnet på NAS2 komponenten |
nsp.kafka.producer.component.abbreviation | Kort navn på NAS2 komponenten |
nsp.kafka.producer.component.version | Versionen af NAS2 komponenten |
nsp.kafka.producer.service.name | Navnet på den service i NAS2 der anvender Kafka |
datasource.jndi | JNDI navnet på den datasource der giver adgang til NAS2 databasen. |
app.endpoint | Service endpoint (anvendes i DKS servlet) |
Alle properties der starter med "kafka.producer." vil blive givet videre til NSP Kafka Clients API'et og derved videre til Kafka Clients. Det er derved muligt at konfigurere alle aspekter af Kafka klienten som måtte være ønsket, blot ved at tilføje nye properties. Hvis f.eks. Kafka konfigurationen "abc" skulle sætte til "42" så tilføjes blot linien "kafka.producer.abc=42".
Denne fil indeholder en Log4J opsætning der følger gængs standard på NSP.
Denne service konfigureres i filerne "idlist.properties" og "log4j-idlist.xml"
Property | Beskrivelse |
---|---|
datasource.jndi | JNDI navnet på den datasource der giver adgang til NAS2 databasen. |
app.endpoint | Service endpoint (anvendes i DKS servlet) |
create.max.batch.size | Max antal entries i SQL batch update når der oprettes og opdateres id lister. |
Denne fil indeholder en Log4J opsætning der følger gængs standard på NSP.
Denne service konfigureres i filerne "subscriptionmanager.properties" og "log4j-subscriptionmanager.xml"
Property | Beskrivelse |
---|---|
kafka.consumer.bootstrap.servers | Kommasepareret liste af Kafka servere som NAS2 skal anvende. Denne liste bør indeholde alle noderne i Kafka clusteret |
kafka.consumer.client.id | Navnet som NAS2 vil fremgå med i listen af Consumers på et Kafka Cluster. |
nsp.kafka.consumer.component.name | Navnet på NAS2 komponenten |
nsp.kafka.consumer.component.abbreviation | Kort navn på NAS2 komponenten |
nsp.kafka.consumer.component.version | Versionen af NAS2 komponenten |
nsp.kafka.consumer.service.name | Navnet på den service i NAS2 der anvender Kafka |
datasource.jndi | JNDI navnet på den datasource der giver adgang til NAS2 databasen. |
app.endpoint | Service endpoint (anvendes i DKS servlet) |
pullpoint.app.endpoint | Service endpoint for pull point servicen. Anvendes til at validere korrekt format af pullpoint. |
Denne fil indeholder en Log4J opsætning der følger gængs standard på NSP.
Denne service konfigureres i filerne "pullpointfactory.properties" og "log4j-pullpointfactory.xml"
Property | Beskrivelse |
---|---|
datasource.jndi | JNDI navnet på den datasource der giver adgang til NAS2 databasen. |
app.endpoint | Service endpoint (anvendes i DKS servlet) |
pullpoint.app.endpoint | Service endpoint for pull point servicen. Anvendes til at validere korrekt format af pullpoint. |
Denne fil indeholder en Log4J opsætning der følger gængs standard på NSP.
Denne service konfigureres i filerne "pullpoint.properties" og "log4j-pullpoint.xml"
Property | Beskrivelse |
---|---|
kafka.consumer.bootstrap.servers | Kommasepareret liste af Kafka servere som NAS2 skal anvende. Denne liste bør indeholde alle noderne i Kafka clusteret |
kafka.consumer.client.id | Navnet som NAS2 vil fremgå med i listen af Consumers på et Kafka Cluster. |
nsp.kafka.consumer.component.name | Navnet på NAS2 komponenten |
nsp.kafka.consumer.component.abbreviation | Kort navn på NAS2 komponenten |
nsp.kafka.consumer.component.version | Versionen af NAS2 komponenten |
nsp.kafka.consumer.service.name | Navnet på den service i NAS2 der anvender Kafka |
datasource.jndi | JNDI navnet på den datasource der giver adgang til NAS2 databasen. |
app.endpoint | Service endpoint (anvendes i DKS servlet) |
kafka.poll.catchup.timeout | Kafka poll timeout der anvendes når en subscription er kommet for langt bagud i forhold til kafka.poll.delta.max. Format er beskrevet på https://docs.oracle.com/javase/8/docs/api/java/time/Duration.html#parse-java.lang.CharSequence- |
kafka.poll.delta.max | Maksimal offset difference mellem subscription og partitionerne i det topic der skal læses før "catch up" mode anvendes og kafka.poll.catchup.timout anvendes som timeout til poll i Kafka. |
kafka.polls.max.time | Maksimal tid der må anvendes i til poll i Kafka (sum af poll kald + iterering over resultat). Format beskrevet på https://docs.oracle.com/javase/8/docs/api/java/time/Duration.html#parse-java.lang.CharSequence- |
statistik.offset.delta.minimum | Minimum offset mellem offset i Kafka Partition og offset for subscription før der laves "offsets" statistiklog. |
Denne fil indeholder en Log4J opsætning der følger gængs standard på NSP.
Denne service konfigureres i filerne "cleanup.properties" og "log4j-cleanup.xml"
Property | Beskrivelse |
---|---|
datasource.jndi | JNDI navnet på den datasource der giver adgang til NAS2 databasen. |
age | Den maksimale alder for et abonnement før det kommer i betragtning for oprydning. Format er beskrevet på https://docs.oracle.com/javase/8/docs/api/java/time/Duration.html#parse-java.lang.CharSequence- |
Denne fil indeholder en Log4J opsætning der følger gængs standard på NSP.
Adgang til NAS2 databasen styres gennem filen "nas-ds.xml" - Denne skal matche det NSP miljø hvor komponenten afvikles i.
NAS2 skal anvender NSP Kafka Clusteret på NSP Backend miljøet. Der kræves ikke nogen særlig opsætning af Kafka i forhold til det eksisterende NSP Kafka Cluster.
I det følgende gennemgåes de manuelle aktiviteter der skal ske i databasen og i Kafka ifm driften af NAS2.
For at NAS2 skal kunne modtage adviseringer på et Topic skal dette oprettes i Kafka og i databasen. For at give tilladelse til at der kan oprettes abonnementer og afhentes adviseringer på et Topic, skal der desuden oprettes et Topic Access i databasen.
Først oprettes Kafka Topic via følgende kommando:
bin/kafka-topics.sh --create --bootstrap-server kafka-host:port --replication-factor 2 --partitions 6 --topic dk.nsp.bo.nas.fmk.MedicineCard |
Herefter mappes dette Kafka Topic til et WS-Notification Topic i databasen på følgende måde:
INSERT INTO TopicMapping (topic, internal_topic) VALUES ('http://www.dkma.dk/medicinecard/xml.schema/2012/06/01:MedicineCard', 'dk.nsp.bo.nas.fmk.MedicineCard'); |
Topic access oprettes med en identifier, der angiver adgangen til et specifikt topic. Identifier kan indeholde 'ALL', et cvr-nummer på formen 'CVR:XXXXXXXX', eller et CVR-RID, CVR-UID eller CVR-FID på formen: 'CVR:XXXXXXXX-XID:XXXXXXXX'.
Eksempler:
Topic Access oprettes i databasen på følgende måde:
INSERT INTO topic_access (topic, identifier, comment) VALUES ('http://www.dkma.dk/medicinecard/xml.schema/2012/06/01:MedicineCard', 'ALL', 'SDS-4393: topic access oprettet'); |
For at lukke for nye adviseringer til et Topic opdateres rækken i "TopicMapping" på følgende måde:
UPDATE TopicMapping SET active = false where topic ="http://www.dkma.dk/medicinecard/xml.schema/2012/06/01:MedicineCard"; |
For at slette et topic bør det først være inaktivt i en periode således at der ikke kan afleveres nye data og modtagere kan nå at afhente alle deres adviseringer. Derefter skal nedenstående udføres.
Nedenstående sletter topic fra NAS databasen.
delete from TopicMapping where topic = 'http://www.dkma.dk/medicinecard/xml.schema/2012/06/01:MedicineCard'; |
Nedenstående sletter topic i kafka.
bin/kafka-topics.sh --delete --bootstrap-server kafka-host:port --topic dk.nsp.nas.fmk.MedicineCard |
Hvis der skal ændres på hvem, der har lov til at tilgå et topic, skal det opdates i Topic Access i databasen.
Der kan være flere rækker i databasen med adgange på cvr eller cvr-Xid. For at give en ny tilladelse oprettes et nyt Topic Access på følgende måde:
INSERT INTO topic_access (topic, identifier, comment) VALUES ('http://www.dkma.dk/medicinecard/xml.schema/2012/06/01:MedicineCard', 'CVR:46837428', 'SDS-4393: ny tilladelse oprettet'); |
Hvis en adgang til et Topic skal slettes, gøres det på følgende måde:
DELETE FROM topic_access WHERE topic = 'http://www.dkma.dk/medicinecard/xml.schema/2012/06/01:MedicineCard' AND identifier = 'CVR:46837428'; |
Hvis et Topic skal ændres fra at være tilgængeligt for alle, er det vigtigt at Topic Access med identifier 'ALL' ikke længere findes i databasen.
Dette sikres ved først at slette adgang for det specifikke Topic hvor identifier = 'ALL'.
Herefter tilføjes adgang for de ønskede CVR eller eller CVR-Xid.
Hvis der opstår et behov i Kafka for at udvide antallet af partitioner for et Topic, skal der ikke foretages noget i NAS2 idet den selv opdager dette og tilpasser sig det nye antal.
Alle services i NAS udstiller en status side. På denne side fremgår servicens versionsnummer samt status for adgang til database og/eller Kafka. Status siden kan tilgås via http://NAS/SERVICE_NAME/health. SERVICE_NAME er pullpoint, pullpointfactory, idlist, notificationbroker eller subscriptionmanager. Det svarer til de 5 services der er implementeret i NAS2.
Eksempel på svar på fra status-siden.
HTTP/1.1 200 OK Connection: keep-alive X-Powered-By: Undertow/1 Server: WildFly/8 Content-Type: application/json Content-Length: 82 Date: Fri, 10 May 2019 08:06:26 GMT { "version": "1.0.0-SNAPSHOT" ,"database": "OK" ,"kafka streamer": "OK" } |
Status-siden returnerer følgende status koder afhængig af servicens status.
200: Applikationen er sund
500: Der er opstået en fejl i applikationen eller en af de services der integreres med.
Såfremt der er problemer med adgang til servicens database, vises nedenstående fejl. Bemærk at den giver en HTTP statuskode 500, og at man i body kan se, at det er NAS servicen der ikke er OK.
|
Følgende årsager kan resultere i en statuskode 500.
Hvis status-siden returnerer HTTP status 500 bør man tjekke applikationsloggen, da fejl logges her til.
Servicen kan genstartes ved at genstarte den docker container, som servicen den kører i.
Som en del af den almindelige applikationslog foretages en række logninger særligt beregnet til udtræk til statistik og ledelsesinformation.
Følgende logningspunkter til statistik er defineret:
Logningspunkt | Komponent | Eksempel på message fra applikationsloggen (formatteret så det er lettere at læse i denne vejledning) |
---|---|---|
Der logges når der oprettes et PullPoint. Hertil medtages yderligere information, så som ejeren, evt. abonnement og URL, der er tilknyttet. | PullPointFactory Service | STATISTIK: { |
Logning af alle forespørgsler til Pull Point service herunder antal af adviseringer, der medtages i svaret. Der logges også om der var tale om replay (DGWS). | PullPoint Service | STATISTIK: { |
Alle kald til Notification Broker skal ligeledes logges sådan at antal af adviseringer modtaget kan uddrages. Her vil topic også medtages. | NotificationBroker Service | STATISTIK: { |
Offsets statistik log logger information omkring subscription og offsets på subscription og offsets i Kafka. | PullPoint service | STATISTIK: { |
Der kan foretages oprydning af abonnementer i databasen. Der konfigureres hvor gamle abonnementer må være – se tidligere – og så sker oprydningen når oprydningsservicen kaldes. Kald laves på følgende URL: http://NAS/cleanup (et simpelt GET
request er tilstrækkeligt). Svaret for kaldet vil være 200 medmindre der er gået noget galt. Derudover svares der med hvor mange abonnementer, der er blevet fjernet.
Database modellen er beskrevet i NAS2 - Design og arktitekturbeskrivelse.