SlpSoftware/aidlc-docs/features/react-frontend/operations/monitoring/monitoring-setup.md

Monitoring Setup Instructions

Concrete setup steps for the approaches chosen in monitoring-plan.md: Logging and Dashboards (no Alerting).

Logging

What to log

• Uncaught JavaScript errors / exceptions (the app already has an ErrorBoundary component from Code Generation — this is the natural hook point).
• Broken/failed navigation (e.g. an unexpected router error).
• No user PII, form input, or sensitive data should ever be logged — this is a public marketing site, but keep this discipline regardless.

Destination — decided: Sentry free tier + console

Both the console and Sentry are now active (original Question 3 resolved as a combination):

Console (always on)

• Errors already surface via console.error inside ErrorBoundary.componentDidCatch — unchanged, zero cost, useful for local/manual debugging.

Sentry free tier (implemented)

• @sentry/react is a dependency; src/main.tsx calls Sentry.init({ ... }) at startup, but only when a DSN is present — if not configured, Sentry is silently skipped and only console-logging remains active (safe default, no crash on missing config).
• ErrorBoundary.componentDidCatch calls Sentry.captureException(error, { extra: { componentStack: info.componentStack } }) in addition to console.error.
• Tracing/performance is also enabled (Sentry's recommended default alongside error monitoring, per the official React SDK setup guide): tanstackRouterBrowserTracingIntegration(router) is wired up so route navigations are captured as transactions, with tracesSampleRate: 1.0 (capture all — appropriate for a low-traffic marketing site; lower this if traffic grows significantly).
• Environment/release tagging: environment is set to import.meta.env.VITE_APP_ENV ('test' / 'production', set at build time — see below), falling back to import.meta.env.MODE for local development (pnpm dev → 'development'). This fallback is needed because vite build runs in production mode by default regardless of target environment, so MODE alone cannot distinguish a test build from a production build. release is set to the app version from package.json (injected at build time via vite.config.ts's define: { __APP_VERSION__ }), so events in Sentry can be filtered/grouped per environment and per shipped version.
• The DSN is injected at build time via Vite's import.meta.env.VITE_SENTRY_DSN (typed in src/vite-env.d.ts). It is not a secret (Sentry DSNs are safe to expose client-side), so it is passed as a Gitea Actions repository variable (vars.VITE_SENTRY_DSN, not a secret) to the Build step in continuous_integration.yaml.
• Local development DSN: for pnpm dev, Vite automatically loads a .env.local file (already covered by .gitignore's *.local rule, so it is never committed). Copy .env.example to .env.local and set VITE_SENTRY_DSN there to enable Sentry locally — a separate Sentry project/DSN is recommended so local test noise doesn't mix with the test-environment data. Omitting .env.local (or leaving the value empty) simply disables Sentry locally, falling back to console-only logging.
• Manual follow-up required: create a free Sentry project (https://sentry.io) for this app, copy its DSN, and set it as the VITE_SENTRY_DSN repository variable in Gitea (Repository Settings → Actions → Variables). Until that variable is set, the build still succeeds and the site still works — Sentry reporting simply stays inactive.
• Free tier limits (error volume, retention) are typically sufficient for a low-traffic marketing site.
• Not (yet) implemented, by explicit choice: automatic source map upload (via @sentry/vite-plugin), which the official Sentry setup guide also recommends so stack traces show real source code instead of minified code. This requires a Sentry auth token/org/project as a new Gitea secret; deliberately left out of scope for now — revisit if readable production stack traces become a priority.
• Ad-blocker mitigation via a Sentry "tunnel" (all environments, including local): requests straight to *.ingest.<region>.sentry.io are commonly blocked client-side by ad-blockers/privacy extensions (ERR_BLOCKED_BY_CLIENT), because they resemble third-party tracking. To avoid this, Sentry.init() always sets tunnel: '/sentry-tunnel'. In deployed (test/production) environments, the reverse-proxy Pi (nginx/reverse-proxy-nginx.conf.example) forwards that path server-side to Sentry's envelope endpoint, so the browser only ever talks to the first-party domain (e.g. test.slpsoftware.nl). Locally (pnpm dev), the equivalent route is provided by Vite's own dev-server proxy (server.proxy in vite.config.ts), so no ad-blocker whitelisting/disabling is needed anymore for local testing either. This relies on full control over the reverse-proxy's nginx config, which is the case here (self-hosted on the user's own Raspberry Pi's) — it would not work on a third-party/shared host without reverse-proxy access. Important: the org-/project-id hardcoded in both the nginx location /sentry-tunnel block and the Vite server.proxy target must match whatever VITE_SENTRY_DSN/.env.local DSN is actually configured; update all together if the Sentry project/DSN ever changes.

Log level strategy: only errors are logged (no verbose/info-level client logging) — this is a static site with no meaningful "business events" beyond page views, which are covered by analytics (see Dashboards below), not logging.

Temporary manual test tool: SentryTestButton

• src/components/SentryTestButton.tsx renders a "Break the world" button, mounted globally via RootLayout.tsx, used to manually verify that errors, logs (Sentry.logger.info), and metrics (Sentry.metrics.count) actually arrive in Sentry end-to-end.
• Visibility: only shown during local development (pnpm dev, via Vite's import.meta.env.DEV). It is hidden in every build (test and production alike), so the test environment always runs a production-equivalent build that can be tested as-is.
• Visual feedback: clicking the button immediately shows a green confirmation toast ("Test error verzonden naar Sentry ✅", role="status") that auto-hides after 4 seconds, so the user gets clear confirmation that the test action fired — without this, the resulting uncaught error/blank state gave no indication anything happened. The actual log/metric/throw (handleSentryTestErrorClick) is fired on the next tick (setTimeout(..., 0)) so the toast has a chance to render/paint first.
• Sentry.logger.* requires enableLogs: true in Sentry.init() (src/main.tsx) — added specifically to support this test button (and any future structured logging).
• The thrown error is intentionally uncaught: React error boundaries do not catch errors thrown from event handlers (only render/lifecycle errors), so this relies on Sentry's own global window.onerror handler, exactly like the official Sentry test snippet.
• This is a temporary verification tool, not a permanent feature — remove SentryTestButton (and its usage in RootLayout.tsx) once Sentry has been confirmed to receive test errors/logs/metrics end-to-end.

Dashboards

Website analytics — decided: self-hosted Umami

Decided: self-hosted Umami, running via Podman on the webserver Pi (Pi Main, 192.168.1.103:3001 — note: not the default 3000, since Gitea already occupies that port on the same Pi), reachable for the dashboard itself via analytics.slpsoftware.nl (reverse-proxied + SSL via certbot, same pattern as test.slpsoftware.nl). Chosen over GA4 for privacy-friendliness (typically no cookie banner needed) and full self-hosted control, and over a hosted Umami/Plausible plan to avoid recurring cost.

• Full step-by-step setup: operations/monitoring/umami-setup.md (Podman/compose files, systemd auto-start, reverse proxy + SSL, website registration).
• Example config: operations/deployment/umami/podman-compose.yml.example + .env.example; operations/deployment/nginx/analytics-nginx.conf.example.
• The tracking script is injected client-side by src/components/UmamiAnalytics.tsx, gated on two build-time variables (VITE_UMAMI_SCRIPT_URL, VITE_UMAMI_WEBSITE_ID), wired into continuous_integration.yaml's Build step as Gitea repository variables, not secrets (same pattern as VITE_SENTRY_DSN). It never loads during local development (pnpm dev), even if those variables happen to be set, so local testing never pollutes visitor analytics.
• Key metrics to surface: unique visitors, page views per route (Home, Packages, etc. — see frontend-components.md), and referral sources.

Uptime dashboard — decided: UptimeRobot

Decided: UptimeRobot (free tier: up to 50 monitors, 5-minute check interval, optional e-mail notification on downtime — opportunistic, not a designed alerting feature per monitoring-plan.md). Chosen over Better Uptime for its long-standing free tier and simplicity for a single low-traffic site.

Setup:

1. Create a free UptimeRobot account (https://uptimerobot.com).
2. Register test.slpsoftware.nl as an HTTP(S) monitor now (checking for a 200 response); add the production URL once hosting is finalized (see operations/deployment/deployment-plan.md "Open Item") — still an open follow-up.
3. Optional: publish a public status page if desired for transparency to visitors.
4. Key metric to surface: uptime percentage / current status.

No application code changes are needed for UptimeRobot — it works purely by polling the public URL from the outside, entirely independent of the site's own codebase.

Summary Table

Concern	Approach	Status
Client-side errors	Logging (console + Sentry free tier, incl. tracing, environment/release tags, and an ad-blocker-proof tunnel)	Implemented and confirmed working end-to-end (errors, logs, and metrics received) locally and on the test environment; the VITE_SENTRY_DSN Gitea repository variable still needs to be created by the user for the test/production build to report to Sentry (local already works via .env.local)
Visitor/usage insight	Analytics dashboard (self-hosted Umami)	Tool decided; deployment (Podman on Pi Main + analytics.slpsoftware.nl) is a manual follow-up, see umami-setup.md
Site reachability	Uptime dashboard (UptimeRobot)	Tool decided; account creation + production URL are manual follow-ups
Alerting	Out of scope	Not configured
Shared infrastructure reuse	Out of scope	None exists yet