77 lines
4.5 KiB
Markdown
77 lines
4.5 KiB
Markdown
# 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.
|