# 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 |