Outlook-plugin log-events

Alle gestructureerde log-events die de Outlook-plugin-flow produceert, in tabellen per fase. Bedoeld als referentie voor dashboards, alerting-regels en troubleshooting. Voor de bredere context, zie Explanation: Outlook-plugin.

Token-refresh (exactService.refreshOutlookToken)

Elke refresh-poging eindigt in precies één event. Naam codeert het resultaat zodat aggregaties direct werken. Alle events bevatten minimaal exactUserId; warn-events bevatten daarnaast een gesaniteerde err-bag (zonder refresh_token in de payload).

Event Level Wanneer Vervolg-actie
exact.outlook.refresh.success info Nieuwe access + refresh-tokens opgeslagen, refreshFailureCount gereset —
exact.outlook.refresh.stale info updateAfterRefresh faalde op optimistic-lock (een andere refresher won) On-demand caller leest fresh doc opnieuw
exact.outlook.refresh.race_lost info Exact gaf invalid_grant maar lastRefreshedAt is opgeschoven (race-loss, geen revoke) On-demand caller leest fresh doc opnieuw
exact.outlook.refresh.rate_limited info Exact weigerde refresh met access_denied / not expired; token nog geldig Geen counter-bump, geen revoke; cron tick na expiry slaagt
exact.outlook.refresh.invalid_grant warn refresh_token permanent kapot (invalid_grant zonder race-bewijs) Doc wordt direct revoked
exact.outlook.refresh.reauth_required warn Exact gaf unauthorized_client / "Old refresh token used.": ons refresh_token is verweesd (state-divergence, zie #2274) Geen revoke (doc blijft voor audit); reauthRequiredAt wordt gezet zodat de doc uit findExpiringSoon valt en de cron ‘m niet meer probeert. Eenmalig per stuck doc; alleen re-OAuth herstelt het
exact.outlook.refresh.transient warn Onverwachte/5xx-fout, geen rate-limit en geen invalid_grant refreshFailureCount +1
exact.outlook.refresh.threshold_revoked warn refreshFailureCount raakte REVOKE_THRESHOLD (30) door de huidige transient-bump Volgt direct na transient; doc is nu revoked

Alert-aanwijzingen

  • Wel alerten: invalid_grant (verhoogt revoke-rate), threshold_revoked (auto-revoke; gebruiker is uit).
  • Niet alerten: success, stale, race_lost, rate_limited zijn verwachte staten in een gezonde flow.
  • Voorzichtig alerten: transient is normaal bij Exact-rate-limits of korte downtime; pas alerts op een spike of een sustained-rate, niet op enkele events.
  • reauth_required: sinds de reauthRequiredAt-fix eenmalig per stuck gebruiker (daarvoor een eindeloze loop, ~1x/min). Alert op het aantal distinct exactUserId per dag, niet op herhalingen; meerdere users tegelijk wijst op een Exact-breed incident.

Background crons

Refresh-cron (refresh-outlook-exact-tokens, elke minuut)

Event Level Inhoud
outlook.exact.refresh.batch info { processed, refreshed, invalidGrant, transient, stale, rateLimited, reauthRequired } — aggregatie van de minuut-tick

Capacity-monitoring (hoeveel docs heeft de cron deze minuut behandeld). Niet bedoeld voor alerting; zet alerts op de individuele events hierboven.

Cleanup-cron (cleanup-outlook-exact-tokens, dagelijks 03:30)

Event Level Inhoud
outlook.exact.cleanup info { revokedStale, deletedOld } — count van revokeStale (>60d ongebruikt) en deleteOldRevoked (>90d revoked)

Sessie-events

Geen dedicated events; sessie-acties (session/refresh, session/recover, session/revoke) loggen via errorLoggerService.trail bij errors. Successful responses worden niet apart gelogd om log-volume beheersbaar te houden.

Initialisatie en lifecycle (server-side)

Event Level Wanneer
exact.handleCallback.error trail OAuth-callback faalde (Exact code-exchange, /current/Me, of doc-upsert)
exact.refreshAccessToken.error trail Plugin-flow’s refresh gooide een uitzondering die door de buitenste try/catch werd opgevangen

errorLoggerService.trail schrijft naar de error-tracking pipeline (Sentry/Errsole), niet naar de gewone Pino-logger.

Client-side console-events

De plugin loggt op enkele kritieke plekken via console.error zodat een gebruiker via DevTools (Outlook → “Inspect taakvenster”) problemen kan herkennen.

Event-string Plek Wanneer
Error loading current item loadCurrentItem catch Office.js gooit tijdens read van het Outlook-item
searchContact error searchContact catch Plugin-API call faalde (auth, server, network)
Archive error archiveBtn flow Archiveer-call faalde
loadDocumentTypes error loadDocumentTypes catch Document-types kon niet worden geladen

Geen gestructureerde formats; bedoeld puur voor handmatige debug.

Hoe een event leest

Elk event komt door in Loki/Grafana met de tenant- en gebruiker-context die op het request hangt. Bij een refresh-event zoek je doorgaans op:

{app="tapster-api"} |= "exact.outlook.refresh" | json

Filter daarna op exactUserId om een specifieke gebruiker te volgen, of op kind voor type-aggregatie.

Gerelateerd