Logging en Verantwoording

Van elk MCP-verzoek wordt vastgelegd wat er is aangeroepen, hoe lang het duurde, hoeveel gegevens erbij betrokken waren en waar het vandaan kwam. Dat logboek is geen bijproduct. Het is de reden dat een antwoord achteraf te verantwoorden is.

Wat wordt vastgelegd

Per aanroep: het adres waarop hij binnenkwam, de naam van het gereedschap, de tijdsduur van de aanroep en van de aanroep naar het bronplatform afzonderlijk, het aantal treffers, het aantal opgehaalde documenten, de omvang in bytes en het ingekorte IP-adres van de aanvrager.

Vanaf 1.3.10 wordt een IP-adres ingekort voordat het ergens terechtkomt. Bij IPv4 vervallen de laatste 16 bits, bij IPv6 blijft alleen het begin van 32 bits over. Wat overblijft wijst een netwerk aan en geen bezoeker. Een e-mailadres dat in een vastlegging terechtkomt, bijvoorbeeld omdat iemand ernaar zocht, wordt vervangen door een onomkeerbare waarde uit een bereik van 65.536 mogelijkheden. Dat geldt voor het logboek, de fouttabel, het tracebestand en de melding naar een externe dienst. Tot 1.3.9 stond het hele adres in die vastleggingen; die oudere regels blijven staan zoals zij zijn geschreven en verdwijnen vanzelf met hun bewaartermijn.

Vanaf 1.3.54 wordt ook de organisatie vastgelegd die de client noemt. Een client kan bij elk verzoek de kop x-organisation meesturen, bijvoorbeeld x-organisation: Gemeente Delft. Die kop is optioneel en komt maar af en toe mee. De naam erin kiest de client zelf en niemand controleert die. De kop geeft ook geen rechten: de MCP-adressen kennen geen authenticatie, en een aanroep zonder kop wordt precies zo behandeld als een aanroep met kop. De naam van de kop is precies x-organisation, met een s. Een kop met een z wordt niet gelezen; de waarde komt dan nergens terecht en de aanroep gaat gewoon door. De waarde wordt op één regel gezet en na 120 tekens afgekapt, en staat daarna in het logboek naast het browserkenmerk. Die twee zeggen iets anders: het browserkenmerk zegt welk programma belde, de organisatie zegt voor wie. Waar de waarde te zien is, staat bij Opvragingen, Overzicht en Dashboard.

Twee dingen worden bewust niet ingekort. Het browserkenmerk, want dat beschrijft een programma en geen persoon. En de gebruikersnaam bij een fout, want dat is een account van deze installatie.

Niet vastgelegd: de inhoud van het gesprek tussen de gebruiker en de assistent. Die inhoud bereikt BesluitBron niet. Wat BesluitBron ziet, is de aanroep die de assistent doet, met de parameters die daarbij worden meegegeven.

Waar het terug te zien is

Het verkeer van de assistent loopt via het verzoeklogboek:

flowchart TD
    X["ToolExecutor"] --> L["McpRequestLog"]
    L --> J[("Tabel bbn_mcp_log<br/>in de database")]
    L --> RB["Ringbuffer<br/>in het geheugen"]
    J --> LOGP["Logboekpagina<br/>per connector"]
    J --> ANA["Analyse<br/>per gereedschap"]
    RB --> HUB["SignalR"] --> DASH["Dashboard<br/>live"]
    RB --> TOOL["list_platform_calls<br/>voor de assistent"]

Wat de server zelf doet, loopt langs een tweede weg:

flowchart TD
    S["De server zelf"] --> TJ[("Tracebestand<br/>één bestand per dag")]
    TJ --> TRP["Tracepagina<br/>te lezen en te downloaden"]

Vier ingangen, elk voor een andere vraag:

• list_platform_calls beantwoordt "waarop is dít antwoord gebaseerd". De assistent kan dit zelf opvragen, tijdens het gesprek;
• de logboekpagina van de beheerconsole beantwoordt "wat is er de afgelopen dagen gevraagd", filterbaar per connector;
• het dashboard beantwoordt "wat gebeurt er nu", en toont de aanroepen terwijl zij binnenkomen;
• de tracepagina beantwoordt "wat heeft de server werkelijk gedaan". Die pagina toont niet alleen de aanroep van de assistent. Zij toont ook elke aanroep naar een bronplatform die daarachter zat, live of uit de buffer, en elke fout met haar stapel.

De eerste drie gaan over het verkeer van de assistent. De trace gaat over het gedrag van de dienst. De trace is daarmee de ingang wanneer een gereedschap een verkeerd antwoord gaf en het verzoeklogboek niet verklaart waarom. Het tracebestand is als geheel te downloaden en wordt daarbij niet gefilterd, want een trace die onderweg is bewerkt, is geen bewijs meer.

Foutmeldingen

Meldingen dragen een code van de vorm bbn<gebied><nummer>, bijvoorbeeld bbnsrv005 voor een configuratie waarin alle bronnen waren uitgezet. Die codes zijn stabiel. Zij zijn bedoeld om te noemen in een melding aan de beheerder of in een vraag aan de leverancier, en worden niet hernummerd.

De veldnamen in het tracebestand en de kolomnamen van het verzoeklogboek liggen om dezelfde reden vast. Bestaande tracebestanden, oude logbestanden en de overzichten daarover zijn erop gebouwd.

Vanaf 1.3.58 krijgt elke fout een regel in het tracebestand, met code bbnerr005 en het verzoek-id erbij. Tot 1.3.57 stond daar alleen een regel als het opslaan van de fout zelf misging, dus juist bij een storing in de database was er niets. Het niveau volgt de soort fout: Error bij een 5xx, Warning bij een 4xx en Debug bij een verzoek dat als aanval is beoordeeld. Zie Trace.

Bewaren

Het logboek staat in de tabel bbn_mcp_log. Een database is daarvoor nodig, en vanaf versie 1.3.73 is dat geen keuze meer: een installatie zonder database start niet en zegt bij het starten wat er ontbreekt. Tot en met versie 1.3.72 kon het ook zonder, en werd het logboek dan per dag in een apart bestand onder de gegevensmap geschreven. Die bestanden gaan niet verloren: zij worden bij de eerste start met een database eenmalig ingelezen en daarna verplaatst naar een submap. Zolang zij er staan, worden zij ook opgeruimd volgens dezelfde bewaartermijn, en een verzoek over persoonsgegevens leest ze mee. Het tracebestand blijft een bestand, in een eigen map ernaast, en volgt dezelfde afweging. Zie Uitrol en Beheer en, voor de afweging die daarbij hoort, Openbaarheid en Persoonsgegevens.

De dienst ruimt zelf op: het logboek na negentig dagen, het tracebestand na dertig, de fouttabel na negentig en de uitvoerbestanden na zeven. Dat zijn de termijnen van de beheerder en niet die van de bezoeker. Het logboek laat zien of de koppeling wordt gebruikt en waar zij faalt, en daarvoor is een kwartaal nodig om een patroon te zien. Het tracebestand dient om een storing te herkennen die zich pas over weken aftekent. Wie het anders wil, past BesluitBron:Log:RetentionDays, BesluitBron:Trace:RetentionDays, BesluitBron:ErrorHandling:RetentionDays en BesluitBron:Export:RetentionDays aan; nul of lager bewaart alles.

Vanaf 1.3.10 gebeurt dat opruimen elke dag, ook wanneer de server maanden achtereen draait. Tot 1.3.9 ruimde de dienst alleen op bij het starten, en de regels in de database ruimde zij helemaal niet op. Een installatie die niet werd herstart, bewaarde daardoor alles. Hoe vaak er wordt opgeruimd, staat in BesluitBron:Retention:IntervalHours; standaard elke 24 uur. Elke ronde schrijft in het tracebestand wat er is verwijderd, met code bbnret001.

De fouttabel kreeg met 1.3.10 ook een termijn, van negentig dagen. De knop "Nu verwijderen" op het scherm "Fouten" blijft bestaan, voor wie een bepaalde periode eerder wil opruimen, zie Beheerconsole.