# Analyseerbaarheid en diagnose

Analyseerbaarheid is het vermogen om van een symptoom naar de verantwoordelijke laag en toestand te komen. racket-wiki heeft daarvoor een gunstige eenvoudige processtructuur, maar nog geen volledige observabilitylaag.

## Begin bij de grens

Classificeer een probleem eerst op basis van het eerste aantoonbaar onjuiste resultaat:

| Waarneming | Eerste controle |
| --- | --- |
| Server start of compileert niet | Racket-fout, ontbrekende `require`, migratie en configuratie |
| Request geeft 4xx/5xx | Route, sessie/rol/CSRF, requestbody en serverexception |
| Database-inhoud is onjuist | Opslagprocedure, basisversie en transactiestappen |
| API-JSON klopt maar scherm niet | `wiki.js`-state, route, DOM-id en renderfunctie |
| Alleen CMap-interactie faalt | hit-test, selectie, editorrecord, document vóór/na de handeling |
| Alleen Markdownweergave faalt | expansiestappen, Marked/EasyMDE, DOMPurify en hydratatie |
| Mail zonder STARTTLS werkt wel | TLS-context, certificaatketen, hostnaam en SMTP-capabilities |

Deze aanpak voorkomt dat opslagcode wordt aangepast om een browserregressie te maskeren, of andersom.

## Beschikbare signalen

De backend schrijft start- en setupinformatie en laat technische uitzonderingen in de serverconsole zichtbaar. De frontend schrijft gerichte CMap-diagnostiek met een component- en versieprefx. De browser Network-tab toont requestmethode, status en JSON-response. PostgreSQL kan actuele rijen, versies en constraints rechtstreeks laten zien.

De applicatie heeft daarnaast functionele diagnosebronnen:

- pagina- en CMaphistorie toont welke actor op welk moment een versie schreef;
- `action` en `summary` onderscheiden create, edit, rename, autosave, snapshot en import;
- aliases verklaren waarom een oud pagina-adres nog opent;
- bijlagebeheer toont huidige en historische referenties;
- `/api/ping` onderscheidt browserconnectiviteit van een volledig vastgelopen UI;
- SMTP-testmail is synchroon en geeft de concrete verbindings- of authenticatiefout terug.

## Reproduceerbare diagnose

Leg voor een regressie ten minste vast:

1. softwareversie en databaseschemaversie;
2. rol en route;
3. minimale handelingen vanaf een bekende toestand;
4. verwachte en werkelijke toestand;
5. relevante request/response;
6. actuele en voorgaande versie van het betrokken document;
7. console-uitvoer zonder geheimen.

Voor een CMap-probleem is een klein document met twee of drie items beter dan een productiemap met honderden nodes. Voor TLS is een zelfstandige STARTTLS-spike beter dan meteen de volledige herstelmailketen te wijzigen.

## Logregels

Een diagnostische melding bevat component, softwareversie, bewerking en veilige identifiers zoals pagina- of CMapslug. Log nooit wachtwoorden, ruwe sessietokens, CSRF-tokens, herstelcodes, SMTP-wachtwoorden of volledige databaseconfiguratie.

Gebruik consistente niveaus:

- `info` voor start, migratie, import en afgeronde beheeracties;
- `warning` voor herstelbare afwijkingen, ontbrekende optionele configuratie en overgeslagen importitems;
- `error` voor een mislukte bewerking met voldoende technische oorzaak;
- uitvoerige CMap-events alleen achter een gerichte debugschakelaar wanneer het volume toeneemt.

## Bekende blinde vlekken

Er is momenteel geen request-id die browser, handler en SQL-bewerking verbindt. Er zijn geen structurele timings per endpoint, geen connectionpoolstatistieken en geen centrale foutregistratie. De frontend-CMapdiagnostiek is bruikbaar maar relatief uitvoerig en niet voor alle subsystemen gelijkvormig.

Voeg observability incrementeel toe:

1. eerst een request-id en gestandaardiseerde foutregel;
2. daarna tijdmetingen rond trage endpoints;
3. vervolgens database- en graphmetingen wanneer echte belasting dat vereist;
4. pas dan een externe metrics- of tracingstack wanneer lokaal loggen onvoldoende blijkt.

## Analyseerbare code

Expliciete tussenwaarden, herkenbare domeinfouten en kleine contracten zijn diagnosehulpmiddelen. Een exception `version-conflict` zegt meer dan een generieke SQL-fout. Een procedure die zelf de transactiegrens bevat, maakt duidelijk of een halve opslag mogelijk is.

Gebruik geen brede `with-handlers` die een technische fout omzet in `#f` zonder context. Vang alleen een fout die op die laag betekenisvol vertaald kan worden; laat de oorspronkelijke exception anders door.

Zie [Onderhoudbaarheid](racket-wiki:onderhoudbaarheid) voor de wijzigingswerkwijze en [Testbaarheid](racket-wiki:testbaarheid) voor het omzetten van een diagnose in een regressietest.