Indledning
Nærværende dokument udgør driftsvejledningen for Yderindlæseren. Yderindlæseren er en stamdataindlæser som vedligeholder register over ydere og deres tilknyttede personer (kaldet yder personer).
Yderindlæseren er en webapplikation der deployer på en Wildfly applikationsserver.
Distributionen af Yderindlæseren foregår som et Docker image der er bygget på NSP platform Docker imaget (registry.nspop.dk/platform/nsp)
Monitoreringssnitflader
Alle Yderindlæsere overvåges via en simpel statusservice. (Se evt. https://www.nspop.dk/display/public/web/Husregler+for+udvikling+til+NSP#HusreglerforudviklingtilNSP-Snitfladetilmonitorering(gl4.4)).
Denne statusservice bliver overvåget ved at den polles hver 10. sekund for en ny status (200 ok og 500 fejl pr default HTTP). Ved 500 er det tegn på, at en supporter skal igang med at kigge på problemet.
curl -v http://localhost:8080/yderindlaeser/status
Dette kan gøres ved at kigge i log filer og i databasens tabeller. Se længere nede i dette dokument under statusservice, for de forskellige typer af status.
Generelle overvågningssnitflader
Ingen - ud over den beskrevne statusservice.
Service snitflader
Ingen - de data der indlæses i registret via Yderindlæseren stilles til rådighed via SKRS, men Yderindlæseren selv udstiller ikke nogen services.
Hvordan agerer Yderindlæseren
Det overordnede flow i Yderindlæseren er som vist denne figur:
Datakilden er Praksys, som med jævne mellemrum, leverer et fuldt udtræk af yder data til en sftp server (interaktion 2. Lever udtræk i figuren)
Yderindlæseren poller en SFTP server for nye filer af typen .xml (interaktion 3. Hent udtræk i figuren). Når der dukker en fil op, hentes den ind til Yderindlæseren og slettes fra SFTP serveren.
Fra den interne placering, læses udtrækket (interaktion 4. Læser udtræk i figuren). Derved tjekkes den modtagne fil for format og konsistens og derefter påbegyndes indlæsningen af de data der findes i den modtagne fil.
Yderindlæseren vil indlæse så meget som muligt af de modtagne data, mens data som det ikke er muligt at indlæse logges til fejlbehandling.
Data indlæses både som enkeltstående rækker i Yder registerdatabasen (interaktion 5. Opdater register i figuren) og som Yderevents (interaktion 6. Skriv events i figuren), hvor den enkelte event samler en Yder med dens relaterede entiteter, i en event tabel.
Efter endt håndtering vil data, enten som enkeltrækker eller som events kunne hentes via SKRS grænsefladen.
Til sidst ved successfuld håndtering skrives en tom ".done" fil til intern folder. Ved kritisk fejl skrive en ".fail" fil. Denne fil sendes til SFTP lokation og anses som ekstern kvittering på endt håndtering.
Statusservice
Statusservice vil svare med en http 200 når alt er ok, men vil svare med en http 500 når der er opstået en fejl under behandling af en fil eller der er en ekstern afhængighed der kan tilgås.
Se iøvrigt også Fejlhåndtering fælles for alle stamdataindlæsere
Svar ved ok
Når alt er ok svarer statusservicen med http 200 og viser denne information
{
"DataSetLog":"OK",
"SFTP YDER_EXTERNAL":"OK",
"SFTP YDER":"OK",
"Database":"OK",
"version":"1.1.3-SNAPSHOT",
"Processing":"Dataprocessering OK"
}
Svar ved fejl i behandling af fil
Ved fejl under behandlingen af en fil, vil statusservicen svare en http 500 og melde fejl indtil fejlen er afhjulpet gennem modtagelsen af en fil der ikke indeholder fejl.
Den modtagne fil fejler delvist
Hvis den modtagne fil indeholder fejl i enkelte entiteter, f.eks. et felt i en Yder der er for langt, vil disse fejl blive registreret.
Svaret fra statusservicen vil her vise informationen som følger, og http status vil være 500.
{
"DataSetLog":"Der er fejlede linjer i DatasetLog tabellen",
"SFTP YDER_EXTERNAL":"OK",
"SFTP YDER":"OK",
"Database":"OK",
"version":"1.2.2-SNAPSHOT",
"Processing":"Dataprocessering OK"
}
Dette indhold fortæller at der er fejl i forbindelse med indlæsning af datasettet (Elementet DataSetLog)
Man kan herefter se i yder databasen for at få præciseset hvilken fejl det drejer sig om.
select * from YDS_datasetlog; +-----+--------------------------------------+---------+----------------------------------------------------------------+-----------------+---------------------+ | PID | DataSetUUID | LogType | LogMessage | DataSetLocation | LogTime | +-----+--------------------------------------+---------+----------------------------------------------------------------+-----------------+---------------------+ | 1 | e4c3abf3-c52e-42a8-bd20-a3855a05880b | NULL | Value of field YdernrYder (0000001) exceeds the maxlength of 6 | 6 | 2023-12-20 07:50:41 | +-----+--------------------------------------+---------+----------------------------------------------------------------+-----------------+---------------------+
Man kan finde de præcise linier der vedrører en given fil, ved at udføre følgende sql, hvor filename er det aktuelle filnavn:
select * from YDS_datasetlog where DataSetUUID = (select UUID from YDS_dataset where FileName = "filename");
Aktion
Der skal tages kontakt til Praksys, der er dataleverandør, for at få dem til at levere en fil der ikke indeholder fejl.
Når denne fil er indlæst kan de relaterede linier i YDS_datasetlog slettes manuelt. Så længe der er linier i YDS_datasetlog vil statusservicen svarer 500 i http status.
Den modtagne fil fejler som helhed
Hvis den modtagne fil ikke er i det forventede format eller dens kontrol felter ikke stemmer med indholdet, så vil hele filen fejle og der vil ikke blive indlæst data fra filen.
Her vil statusservicen melde en fejl som følger, og http status vil være 500.
{
"DataSetLog":"OK",
"SFTP YDER_EXTERNAL":"OK",
"SFTP YDER":"OK",
"Database":"OK",
"version":"1.2.2-SNAPSHOT",
"Processing":"Fejl i processering af filen: testfil1.xml. Genindlæs ved at placere filen i input folderen. Fejlens stacktrace kan ses på exception endpointet"
}
Dette indhold fortæller at der er fejl i forbindelse med processering af data (Elementet Processing)
Som angivet i status beskeden kan man herefter kalde et andet endpoint, for at få mere information om fejlen, der er opstået:
curl -v http://localhost:8080/yderindlaeser/exception dk.nsp.sdm.common.route.components.ProcessingException: Fejl i input-filen: Antal linier: 1, matcher ikke antal poster i footer: 4 at dk.nsp.sdm.yder.service.impl.YderEventParser.doSumValidation(YderEventParser.java:102) at dk.nsp.sdm.yder.service.impl.YderEventParser.doDatasetStructureValidation(YderEventParser.java:61) at dk.nsp.sdm.common.route.components.DatasetValidator.doValidation(DatasetValidator.java:64) at dk.nsp.sdm.common.route.components.DatasetValidator.access$100(DatasetValidator.java:16) at dk.nsp.sdm.common.route.components.DatasetValidator$1.process(DatasetValidator.java:40) at org.apache.camel.processor.DelegateSyncProcessor.process(DelegateSyncProcessor.java:63) at org.apache.camel.processor.RedeliveryErrorHandler.process(RedeliveryErrorHandler.java:548) at org.apache.camel.processor.CamelInternalProcessor.process(CamelInternalProcessor.java:201) at org.apache.camel.processor.Pipeline.process(Pipeline.java:138) at org.apache.camel.processor.Pipeline.process(Pipeline.java:101) at org.apache.camel.processor.FilterProcessor.process(FilterProcessor.java:57) at org.apache.camel.processor.RedeliveryErrorHandler.process(RedeliveryErrorHandler.java:548) at org.apache.camel.processor.CamelInternalProcessor.process(CamelInternalProcessor.java:201) at org.apache.camel.processor.CamelInternalProcessor.process(CamelInternalProcessor.java:201) at org.apache.camel.component.direct.DirectProducer.process(DirectProducer.java:76) at org.apache.camel.processor.SendProcessor.process(SendProcessor.java:148) at org.apache.camel.processor.RedeliveryErrorHandler.process(RedeliveryErrorHandler.java:548) at org.apache.camel.processor.CamelInternalProcessor.process(CamelInternalProcessor.java:201) at org.apache.camel.processor.Pipeline.process(Pipeline.java:138) at org.apache.camel.processor.Pipeline.process(Pipeline.java:101) at org.apache.camel.processor.CamelInternalProcessor.process(CamelInternalProcessor.java:201) at org.apache.camel.component.file.GenericFileConsumer.processExchange(GenericFileConsumer.java:454) at org.apache.camel.component.file.GenericFileConsumer.processBatch(GenericFileConsumer.java:223) at org.apache.camel.component.file.GenericFileConsumer.poll(GenericFileConsumer.java:187) at org.apache.camel.impl.ScheduledPollConsumer.doRun(ScheduledPollConsumer.java:174) at org.apache.camel.impl.ScheduledPollConsumer.run(ScheduledPollConsumer.java:101) at java.util.concurrent.Executors$RunnableAdapter.call(Executors.java:511) at java.util.concurrent.FutureTask.runAndReset(FutureTask.java:308) at java.util.concurrent.ScheduledThreadPoolExecutor$ScheduledFutureTask.access$301(ScheduledThreadPoolExecutor.java:180) at java.util.concurrent.ScheduledThreadPoolExecutor$ScheduledFutureTask.run(ScheduledThreadPoolExecutor.java:294) at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1149) at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:624) at java.lang.Thread.run(Thread.java:748)
Aktion
Man skal have undersøgt, hvad der er sket.
Der skal højst sandsynligvis tages kontakt til Praksys, der er dataleverandør, for at få dem til at levere en fil der ikke indeholder fejl.
Når der er modtaget en fil uden fejl skal yder indlæseren genstartet. Så længe der en en alvorlig fejl sket, indlæses ikke yderligere filer.
Svar når ekstern afhængighed kan ikke tilgås
Der er 3 eksterne afhængigheder til Yderindlæseren som kan give anledning til fejl hvis de ikke er tilgængelige for Yderindlæseren. I alle tilfælde vil statusservicen svare http 500 og vise en beskrivelsen af fejlen.
Manglende adgang til Yder databasen
Hvis Yder databasen ikke er tilgængelig vil statusservicen melde en fejl som:
{
"DataSetLog":"OK",
"SFTP YDER_EXTERNAL":"OK",
"SFTP YDER":"OK",
"Database":<TBD - SDS-6802>,
"version":"1.1.3-SNAPSHOT",
"Processing":"Dataprocessering OK"
}
Aktion
Der skal tages kontakt til NSP Drift for at undersøge hvorfor databasen ikke er tilgængelig.
Manglende adgang til Praksys SFTP eller Ekstern levering SFTP
Hvis Praksys eller Ekstern levering SFTP serveren ikke er tilgængelig vil statusservicen melde en fejl som
{
"DataSetLog":"OK",
"SFTP YDER_EXTERNAL":"OK",
"SFTP YDER":"Unable to connect to (S)FTP (sftp:foo@ydersftp:22/praksys) due to java.net.NoRouteToHostException: No route to host (Host unreachable)",
"Database":"OK",
"version":"1.2.2-SNAPSHOT",
"Processing":"Dataprocessering OK"
}
Aktion
Der skal tages kontakt til NSP Drift for at undersøge hvorfor SFTP serveren ikke er tilgængelig
Yderindlæseren går ned
I tilfælde af at docker containeren der kører Yderindlæseren går ned, kan følgende trin følges for at sikre at evt. data der var under behandling bliver færdigbehandlet.
Yderindlæseren er designet til at en stamdata fil kan genkøres uden at de register data der vedligeholdes bliver korrupte, så de beskrevne trin går kun ud på at få yderindlæseren til at genbehandle en evt. afbrudt fil indlæsning.
Som beskrevet i Yderindlæser - Installationsvejledning er Yderindlæserens docker container startet med hhv. et volume-mount der bibeholder indholdet af den interne input folder /tmp/yder/input og et volume-mount der bibeholder indholdet af den interne backup folder /tmp/yder/input/.done efter docker containeren er stoppet.
Derfor vil disse volumemounts indeholde evt. filer der var under behandling da docker containeren stoppede eller som er lagt i backup mens docker containeren kørte.
Yderindlæseren er opdelt i en producerende del, som parser og splitter stamdata filen, og en konsumerende del, som skriver de splittede data til databasen.
Når Yderindlæserens producerende del er igang med at behandle en fil, vil /tmp/yder/input folderen indeholde den fil der er under behandling, f.eks. A23.D210309.XML samt en låse fil med navnet A23.D210309.XML.camelLock. Filen A23.D210309.XML.camelLock fortæller Yderindlæseren, at filen med navnet uden .camelLock, er under indlæsning og der derfor ikke skal tages fat i denne fil.
Når Yderindlæserens producerende del er færdig, vil datafilen bliver kopieret til en backup lokation og filen med endelsen .camelLock slettes.
Hvis der var en fil under behandling af den producerende del, når Yderindlæserens docker container går ned, så vil der i volume-mountet for /tmp/yder/input ligge en fil med endelsen .camelLock.
Når docker containeren med Yderindlæseren er startet igen, kan filen med endelsen .camelLock slettes hvilket vil få Yderindlæseren til at tage fat i stamdata filen og indlæsningen af filen vil gentages.
Hvis Yderindlæserens docker container går ned mens en fil under behandling er kommet igennem den producerende del og der kun udestår den konsumerende dels behandling af de splittede data, så vil filen være flyttet til backup folderen, og den vil derfor ligge i denne folder efter docker containeren er stoppet.
Det er her nødvendigt at kigge i databasen for at afgøre om der var filer i behandling da docker containeren gik ned.
Dette gøres ved at udføre SQL forespørgslen
select * from YDS_dataset where status not like "%Completed%";
mod Yderindlæserens database.
Hvis denne forespørgsel returnerer en eller flere rækker, findes den række hvor DataReceived kolonnen er umiddelbart før tidspunktet hvor Yderindlæserens docker container gik ned, og FileName + UUID kolonnen i samme række vil fortælle hvilken fil i backup folderen der ikke blev afsluttet. Filen fra backupfolderen kan dernæst flyttes til input folderen så indlæsningen kan genoptages.
Beskrivelse af logs
Yderindlæseren skriver til 4 forskellige log filer, der alle er placeret lokalt i Docker containeren i Wildfly standard log folderen: /pack/wildfly8/standalone/log
NSP SLA log
Denne log ligger i filen nsputil-sla.log og indeholder NSP SLA logninger på formen
20-12-2023 09:35:24,817 [Camel (camel-1) thread #4 - file:///tmp/yder/input] INFO dk.sdsd.nsp.slalogdata - LogPoint="DataProcessController" LogPointUniqId="DataProcessController" StartTime="2023-12-20 09:35:24.817" EndTime="2023-12-20 09:35:24.817" Duration="31 microseconds" MessageId="6955145c-7fd3-4250-acc0-f751756a5acc" RequestSize=0 ReplySize=0 Result=OK ClientIP="<empty>" SOAPOperation="DataSet received" SOAPEndpoint="<empty>" SOAPAction="<empty>" TargetSOAPOperation="<empty>" TargetSOAPEndpoint="<empty>" GenericCallParms(1)= { ("Input","with4Ydere_and6Persons.xml") }
20-12-2023 09:35:25,923 [Camel (camel-1) thread #1 - AggregateTimeoutChecker] INFO dk.sdsd.nsp.slalogdata - LogPoint="DataProcessController" LogPointUniqId="DataProcessController" StartTime="2023-12-20 09:35:25.923" EndTime="2023-12-20 09:35:25.923" Duration="20 microseconds" MessageId="6955145c-7fd3-4250-acc0-f751756a5acc" RequestSize=0 ReplySize=0 Result=OK ClientIP="<empty>" SOAPOperation="DataSet completed" SOAPEndpoint="<empty>" SOAPAction="<empty>" TargetSOAPOperation="<empty>" TargetSOAPEndpoint="<empty>" GenericCallParms(2)= { ("ErrorLines","0") , ("Input","with4Ydere_and6Persons.xml") }
Audit log
Denne log ligger i filen yderAudit.log og indeholder overordnet logning af Yderindlæserens aktivitet
timestamp="2023-12-20 09:35:24,769" priority="INFO" class="FETCHROUTE_ROUTE_ID" message="Fetching file with4Ydere_and6Persons.xml"
timestamp="2023-12-20 09:35:24,818" priority="INFO" class="dk.nsp.sdm.common.route.components.DataProcessController" message="The file with4Ydere_and6Persons.xml has been received"
timestamp="2023-12-20 09:35:25,019" priority="INFO" class="dk.nsp.sdm.common.route.components.DeleteFilter" message="Uuid: 6955145c-7fd3-4250-acc0-f751756a5acc. DeleteEvents: 0"
timestamp="2023-12-20 09:35:25,019" priority="INFO" class="dk.nsp.sdm.common.route.components.DuplicateFilter" message="Uuid: 6955145c-7fd3-4250-acc0-f751756a5acc. DuplicateEvents: 0"
timestamp="2023-12-20 09:35:25,923" priority="INFO" class="dk.nsp.sdm.common.route.components.DataProcessStatistics" message="Uuid: 6955145c-7fd3-4250-acc0-f751756a5acc. PersistedEvents: {Written Yder=4, Updated Yder=0, Deleted Yder=0, Written Yder Persons=6, Updated Yder Persons=0, Deleted Yder Persons=0}"
timestamp="2023-12-20 09:35:25,923" priority="INFO" class="dk.nsp.sdm.common.route.components.DataProcessController" message="Uuid: 6955145c-7fd3-4250-acc0-f751756a5acc. Total processing Time: PT1.923S"
timestamp="2023-12-20 09:35:25,924" priority="INFO" class="dk.nsp.sdm.common.route.components.DataProcessController" message="Uuid: 6955145c-7fd3-4250-acc0-f751756a5acc. The file: with4Ydere_and6Persons.xml has been completed with status: COMPLETED"
timestamp="2023-12-20 09:35:25,924" priority="INFO" class="dk.nsp.sdm.common.route.components.DatasetReader" message="EndEvent skal kvitteres. Sætter filnavn med .done og tomt filindhold i body"
timestamp="2023-12-20 09:35:26,301" priority="INFO" class="DISTRIBUTE_CONFIRM_ROUTE_ID" message="Sending file with4Ydere_and6Persons.xml.done"
Application log
Denne log ligger i filen yderApplication.log og indeholder detaljeret logning af Yderindlæserens aktivitet. For endnu mere logning aktiveres debug log.
timestamp="2023-12-20 09:35:24,818" priority="INFO" class="dk.nsp.sdm.common.route.components.DataProcessController" message="The file with4Ydere_and6Persons.xml has been received"
timestamp="2023-12-20 09:35:25,019" priority="INFO" class="dk.nsp.sdm.common.route.components.DeleteFilter" message="Uuid: 6955145c-7fd3-4250-acc0-f751756a5acc. DeleteEvents: 0"
timestamp="2023-12-20 09:35:25,019" priority="INFO" class="dk.nsp.sdm.common.route.components.DuplicateFilter" message="Uuid: 6955145c-7fd3-4250-acc0-f751756a5acc. DuplicateEvents: 0"
timestamp="2023-12-20 09:35:25,923" priority="INFO" class="dk.nsp.sdm.common.route.components.DataProcessStatistics" message="Uuid: 6955145c-7fd3-4250-acc0-f751756a5acc. PersistedEvents: {Written Yder=4, Updated Yder=0, Deleted Yder=0, Written Yder Persons=6, Updated Yder Persons=0, Deleted Yder Persons=0}"
timestamp="2023-12-20 09:35:25,923" priority="INFO" class="dk.nsp.sdm.common.route.components.DataProcessController" message="Uuid: 6955145c-7fd3-4250-acc0-f751756a5acc. Total processing Time: PT1.923S"
timestamp="2023-12-20 09:35:25,924" priority="INFO" class="dk.nsp.sdm.common.route.components.DataProcessController" message="Uuid: 6955145c-7fd3-4250-acc0-f751756a5acc. The file: with4Ydere_and6Persons.xml has been completed with status: COMPLETED"
timestamp="2023-12-20 09:35:25,924" priority="INFO" class="dk.nsp.sdm.common.route.components.DatasetReader" message="EndEvent skal kvitteres. Sætter filnavn med .done og tomt filindhold i body"
timestamp="2023-12-20 09:35:26,301" priority="INFO" class="DISTRIBUTE_CONFIRM_ROUTE_ID" message="Sending file with4Ydere_and6Persons.xml.done"