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:

softwareversie en databaseschemaversie;
rol en route;
minimale handelingen vanaf een bekende toestand;
verwachte en werkelijke toestand;
relevante request/response;
actuele en voorgaande versie van het betrokken document;
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:

eerst een request-id en gestandaardiseerde foutregel;
daarna tijdmetingen rond trage endpoints;
vervolgens database- en graphmetingen wanneer echte belasting dat vereist;
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 voor de wijzigingswerkwijze en Testbaarheid voor het omzetten van een diagnose in een regressietest.

4.5 KiB Raw Blame History