Følgende beskriver tekniske retningslinjer for hvorledes der logges systemlog fra STARs applikationer.

Hvem, hvad, hvor?

Hvornår skal der logges?

Se beskrivelse af de generelle krav til systemlog her: Krav til logning i applikationer

Motivation for at afgive et log dokument:

• Der er et audit krav som gør at det skal logføres.

• For at understøtte overvågning af systemets generelle drift.

• Til formidling af fejlsøgnings information til udviklere.

Hvor fra skal der logges?

Der kan logges fra et hvert stykke kode, det er væsentligt at opdele det i hhv:

• Konkrete data rettelser logges i database, sammen med den data som blev rettet (data audit spor).

• Generel og generisk logging implementeret i fælleskomponenter.

• Applikations specifik logging med domænespecifik information.

Dette har en indvirkning på hvilke ting som giver mening at logge hvor fra.

Hvordan processeres logs?

Der er flere lag i processeringen.

1. Først afgives en log fra en konkret kode linje i egen eller fra et library.

2. Denne opsamles af .NET frameworket og filtreres indledende, ud fra de appsettings der er sat. (f.eks. drop debug/trace).

3. Generel berigelse af log entries, gennem fælleskomponenter. (Bruger kontekst, etc.)

4. Konvertering til Elastic Common Schema, samt yderligere manipulationer, dette sker i SeriLog frameworket.

5. Logdokumentet skrives som én linje JSON dokument til en fil på disk. (nd-json, newline defined JSON).

6. Log opsamles af elastic agenten og sendes til Logstash/Elasticsearch. (Logstash agerer ude lukkende som queue server.).

7. JSON dokument dekodes, anerkendte felter “cherry-pickes” og placeres på rod dokumentet.

8. Logs er nu søgbare i Kibana.

Hvilken information skal logges?

Ved logging er det MEGET VIGTIGT at overveje hvorfor det enkelt log dokument skal logges!

Et godt log dokument kan være afgørende for fejlsøgning og detektering af misbrug af systemerne.

Reflektions spørgsmål til vurdering af et log entry:

• Motivation for at lave log entry

  • Hvilken handling skal udføres ud fra det specifikke log entry?

  • Skal der aktiveres en alert baseret på dette log entry?

  • Er det blot noget som blev brugt i forbindelse med udviklingen af koden?

• Indholdet log entry

  • Hvilken information og felter i er der KRAV om bliver logget?

  • Hvilken information er nødvendig for at kunne overvåge driften af komponenten?

  • Hvilken information vil god ifbm. fejlsøgning?

• Kvalitet og brugbarhed
  Forestil dig tiden er gået 3 måneder og en anden udvikler læser dette log entry.

  • Hvem kommer til at søge efter dette log entry?

  • Kan det læses og forstås?

  • Mangler der nøgle information, for at det kan anvendes?

• Mængden og størrelse af logs

  • Hvor ofte vil denne log linje blive sendt?

  • Kan antallet af enkelte loglinjer reduceres?

  • Bliver samme information allerede logget andetsteds?

  • Er dette noget hvor man har brug for hver enkelte log eller ville et sampled subset over APM tracing være nok?

Specifik implementation og anvendelse

Implicit påføres der generel information på et log entry, det sker både i .NET kode, når det samles op af agenterne og til sidst under ingestion i elasticsearch. Information om dette beskrives i et følgende afsnit, de mest afgørende felter nævnes her for abstrakt reference:

• Generel metadata: Timestamp, applikations navn, silo/domæne/stack.

• Afviklings info: process, thread, pod/container, IP adresse.

• Error: message, level, severity, exception, stacktrace.

• Star log data: specifik information.

Komponenters loggings opgaver

Her beskrives der helt overordnet de forskellige komponent typer og deres karakteristik.

• Indgående kald - kun apigateway

  • Apigateway er SPOC, den skal notere audit information.

  • Log content for dem som ikke kunne routes et sted hen.

  • Requests som kan routes og successfuld sendes til servicen. Beregn hash af content, for sporbarhed.

• Applikation/service - alle de mange forskellige services

  • Den enkelte applikation logger modtagelsen af et API kald og dens content.

  • Applikationen ejer data formatet og er derfor i stand til at parse og forstå indholdet.
    Dette kan bruges til at berige contexten og det generelle logging scope in den service.

• Message queue beskeder - generisk håndterert i foundation

  • Generel metadata → Logges til felter i star specifikationen.

  • Payload renses for b64 encoded filer!

  • Payload → Arkiveres i et ikke indekseret felt.
    Kan inspiceres når man har fundet log entry, men der kan ikke søges efter indholdet.

• Batchjob - Implementeret i batchjob runner

  • Generel afviklings information for batchjobbet.
    Statistikker logges til star felter: successfulde, failed, etc.

  • Sætter batchjob afviklingsinformation på logging scope, derved beriges alle logging kald under den domænespecifikke kode.

• Udgående beskeder

  • Afsendelse af beskeder skal som minimum logges som access log, for at kunne dokumentere at det er sket.

  • TODO: Hvad er kravene til udgående beskeder? Formater osv?

Dataformater og felttyper

I .NET og elastic er der to forskellige forståelser af en data type.

• I .NET hjælper det med hvordan data opbevares i memory.

• I elasticsearch beskriver det hvordan et stykke information skal processeres og opbevares på disk.

For at bygge bro mellem de to verdener og forståelse, er der nødt til at være et typestærkt link mellem de to platforme. Derfor er der EcsStar som tjener NETOP dette formål i .NET koden!

Det bliver vedligeholdt og genereret i starcloud-elk-tofu kodebasen. Og skal være deployeret på elasticsearch, før det kan anvendes.

Elementer fra gl version af dokumentationen

Dette skal reviews og ryddes op.

Best practices

1. Alle data ind og ud af hver applikation/system logges (excl. databasetrafik), væsentlige forretningshændelser logges.

2. Opslag på borgere påføres om muligt CPR som identifikation for så enkelt som muligt at kunne samle log om tilgang til en borger ved revision.

3. Alle logninger skal foretages som et asynkron kald af performance hensyn.

4. Alle Log4Net levels understøttes, dog skal ’Debug' level som udgangspunkt kun benyttes i test-miljøer og skal kunne slås fra via konfigurationsfil.

5. Log skal opbevares i 1/2 år jf .Systemforvalter. Der skal tages stilling til database-partitionering/arkivering ( ikke et absolut krav )

6. Store request og response beskeder klippes.

7. Vedhæftninger/dokumenter logges ikke.

8. Der skal logges oplysninger om den kaldende bruger/myndighed, input parameter til service kald samt start og slut tidspunkt for request.

Logningsniveauer

Følgende er beskrivelse af de enkelte logningsniveauer og hvad der logges under disse:

• error: systemet er fejlramt, brugerne bliver sikkert ramt (snart) og rettelse kræver formentlig menneskelig indgriben. Der kan trigges alarmer ud fra "error" logninger, dvs. at hvis en servicetekniker skal vækkes så log på "error" niveau.

• warn: en uventet teknisk eller forretningshændelse er opstået, brugere bliver muligvis berørt, men der er ikke behov for menneskelig indblanding. Servicetekniker skal ikke tilkaldes, men supporten bør kigge disse igennem.

• info: det normale loglevel som anvendes hvis vi ønsker at se hvad der er sket, det kan være system-lifecycle events (system start, stop), "session" lifecycle events (login, logout, etc.) osv. Væsentlige snitfladehændelser kan også placeres her, f.eks. service, api og måske databasekald. Normale forretningsexceptions kan også logges her som f.eks. inputvalideringsfejl, login-fejl osv. En hver anden hændelse som du ønsker skal logges i produktion placeres her.

Disse anvendes normalt kun på test- og udviklingsmiljøer:

• debug: alt det andet som ikke skal logges under info. Det kan være hændelser som er hjælpsomme for at se kald ned igennem kodestakken. Det kan også være logning på indgang/udgang af komplekse metoder.

• trace: bruges sjældent, det er detaljerede trace logninger, der f.eks. bruges under udvikling til logning af hele objekthierarkier og kaldestak, eller et trace der gentages i et loop osv.

Teknikken

Logkomponenten Log4net benyttes til logning, via asynkron database-connector. Har applikationen adgang til DFDG Foundation, skal logkomponenten herfra anvendes.