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.MODE (e.g. production) and 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.
• 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.

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.

Dashboards

Website analytics

Pick one (all have generous free tiers suitable for a small marketing site):

Option	Notes
Plausible / Umami	Privacy-friendly, lightweight, no cookie banner typically required; self-hosted or low-cost hosted tier
Google Analytics (GA4) / Search Console	Free, widely known, but heavier script and involves third-party data sharing (cookie/consent implications)

Setup (once a tool is picked):

1. Create an account/site entry with the chosen provider and obtain the tracking snippet or <script> tag.
2. Add the snippet to index.html (or load it conditionally in src/main.tsx) — this is a documentation/config task, not something the current codebase needs restructuring for.
3. Key metrics to surface: unique visitors, page views per route (Home, Packages, etc. — see frontend-components.md), and referral sources.

Uptime dashboard

Pick one:

Option	Notes
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)
Better Uptime	Free tier available; similar capability, nicer public status page option

Setup (once a tool is picked):

1. Register the production URL (once hosting is finalized — see operations/deployment/deployment-plan.md "Open Item") as an HTTP(S) monitor, checking for a 200 response.
2. Optional: publish a public status page if desired for transparency to visitors.
3. Key metric to surface: uptime percentage / current status.

Summary Table

Concern	Approach	Status
Client-side errors	Logging (console + Sentry free tier)	Implemented; VITE_SENTRY_DSN Gitea variable still needs to be created by the user
Visitor/usage insight	Analytics dashboard (Plausible/Umami/GA4)	Tool selection open item
Site reachability	Uptime dashboard (UptimeRobot/Better Uptime)	Tool selection + production URL open item
Alerting	Out of scope	Not configured
Shared infrastructure reuse	Out of scope	None exists yet