Adds the monitoring plan and setup for the front-end shell
Continuous Integration / check (pull_request) Successful in 6m2s
Continuous Integration / deploy-test (pull_request) Skipped
Continuous Integration / deploy-production (pull_request) Canceled after 0s
Continuous Integration / lighthouse (pull_request) Canceled after 12m29s
Continuous Integration / check (pull_request) Successful in 6m2s
Continuous Integration / deploy-test (pull_request) Skipped
Continuous Integration / deploy-production (pull_request) Canceled after 0s
Continuous Integration / lighthouse (pull_request) Canceled after 12m29s
Monitoring reuses the existing Sentry organisation, the self-hosted Umami instance and UptimeRobot, with e-mail alerts. One build serves both environments; the browser picks test or production from the hostname and sends nothing on other hosts. Sentry captures errors only, loads after the page and stores no personal data. Code changes follow after approval. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,61 @@
|
||||
# Monitoring Plan — frontend-shell
|
||||
|
||||
Decisions: [monitoring-setup-plan.md](../plans/monitoring-setup-plan.md) (Q1 = A, Q2 = D, Q3 = A, Q4 = A, Q5 = A, Q6 = A + production now, Q7 = A).
|
||||
|
||||
## Overview
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
Visitor["Visitor browser"] -->|"JS errors"| Sentry["Sentry (EU), existing org"]
|
||||
Visitor -->|"page views, cookieless"| Umami["Umami on the Pi, analytics.slpsoftware.nl"]
|
||||
Uptime["UptimeRobot"] -->|"HTTP checks"| Site["andreaslop.nl and test.andreaslop.nl"]
|
||||
Sentry -->|"e-mail, new error type"| Owner["Owner"]
|
||||
Uptime -->|"e-mail, site down"| Owner
|
||||
|
||||
classDef visitor fill:#f6e05e,stroke:#c05621,stroke-width:1px,color:#000;
|
||||
classDef service fill:#e9d5ff,stroke:#6b21a8,stroke-width:1px,color:#000;
|
||||
classDef site fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
|
||||
classDef owner fill:#63b3ed,stroke:#2b6cb0,stroke-width:1px,color:#000;
|
||||
|
||||
class Visitor visitor;
|
||||
class Sentry,Umami,Uptime service;
|
||||
class Site site;
|
||||
class Owner owner;
|
||||
```
|
||||
|
||||
Text alternative: visitors' browsers send JavaScript errors to Sentry and cookieless page views to Umami; UptimeRobot checks both sites from outside; Sentry and UptimeRobot e-mail the owner.
|
||||
|
||||
## Chosen Approach (all three, reusing existing services)
|
||||
|
||||
| Area | Service | What it covers | Code needed |
|
||||
|---|---|---|---|
|
||||
| **Logging** | **Sentry** (existing EU organisation, new project `andreaslop-fotografie`) | JavaScript errors in visitors' browsers: render errors caught by `ErrorPage` and unhandled errors, tagged `test` or `production` | Yes |
|
||||
| **Dashboards: visitors** | **Umami** (existing install on the Pi, two new "websites": test and production) | Page views, referrers, devices, without cookies or personal data | Yes |
|
||||
| **Dashboards: availability** | **UptimeRobot** (existing account, new monitors) | Whether test and production respond; response time history | No |
|
||||
| **Alerting** | Sentry + UptimeRobot defaults | E-mail on a **new** type of error (Sentry) and when a site is **down** (UptimeRobot) | No |
|
||||
|
||||
## Key Decisions
|
||||
|
||||
| # | Decision | Why |
|
||||
|---|---|---|
|
||||
| M1 | **One build for both environments**: the browser picks the environment from the hostname (`andreaslop.nl` → production, `test.andreaslop.nl` → test). Any other host (localhost, Lighthouse CI, previews) sends **nothing**. | Keeps "deploy exactly what was tested" (D-pipeline). Local runs and CI never pollute the dashboards. |
|
||||
| M2 | **Sentry and Umami settings live in code** (`src/monitoring/config.ts`), not in Gitea variables. | The Sentry DSN and Umami website IDs are public by design: they end up in every visitor's browser anyway. In code they are reviewed, tested and versioned. |
|
||||
| M3 | **Sentry sends directly** to `*.ingest.de.sentry.io` (no tunnel). | Q4 = A: the IIS host serves only static files until the .NET API exists; some errors from visitors with ad-blockers are missed. Follow-up: tunnel via the API. |
|
||||
| M4 | **Sentry loads after the page**, not in the main bundle. | Keeps the performance budget: the home page on mobile already sits just above its 0.8 target. Errors are queued until Sentry is ready. |
|
||||
| M5 | **Sentry: errors only.** No performance tracing, no session replay, no personal data (`sendDefaultPii: false`, IP storage off in the project settings). | Smallest bundle, least data, simplest privacy story. |
|
||||
| M6 | **Umami: separate websites for test and production**; `data-domains` restricts counting to the right hostname, and `data-do-not-track` respects the browser's Do Not Track setting. | Test traffic never mixes with real numbers. |
|
||||
| M7 | **CSP exceptions as narrow as possible**, generated into `web.config` and the nginx config like the other headers. <ul><li>`script-src`: `https://analytics.slpsoftware.nl` (the Umami script)</li><li>`connect-src`: `https://analytics.slpsoftware.nl` and `https://o4511795618185216.ingest.de.sentry.io`</li></ul> | Nothing else is opened. |
|
||||
| M8 | **UptimeRobot**: production monitor now (it watches the current WordPress site until the DNS switch, then the new site automatically), test now, and the `/portfolio` deep-link monitors. | Q6 = A, owner: production can start now. |
|
||||
|
||||
## Explicitly Out of Scope
|
||||
- Sentry tunnel against ad-blockers: comes with the .NET API (follow-up).
|
||||
- Server-side logging (nginx, IIS): not managed by this project. nginx logs on the Pi and the hoster's IIS logs stay where they are.
|
||||
- Performance tracing, session replay, custom Umami events.
|
||||
- Alerts other than e-mail.
|
||||
|
||||
## Privacy (action item for the privacy statement page)
|
||||
The privacy statement (still a placeholder) must mention:
|
||||
- **Umami**: anonymous, cookieless visit statistics, self-hosted in the Netherlands, no personal data.
|
||||
- **Sentry**: technical error reports, sent to Sentry (EU region) without IP address or personal data.
|
||||
|
||||
Umami without cookies needs no cookie banner under the Dutch DPA's guidance for analytics that are set up privacy-friendly. Sentry error reporting falls under legitimate interest. **This is not legal advice; check it when writing the privacy statement.**
|
||||
@@ -0,0 +1,78 @@
|
||||
# Monitoring Setup — frontend-shell
|
||||
|
||||
What to do once in each service, and what changes in the code. The code changes are made on PR #4 after approval of this setup. Until the values below are filled in, the site sends nothing (safe default).
|
||||
|
||||
## 1. Sentry (logging + error e-mails)
|
||||
|
||||
### In Sentry (once)
|
||||
1. In your existing organisation, create a project: platform **React**, name `andreaslop-fotografie`.
|
||||
2. Copy the **DSN** (Settings → Client Keys). It looks like `https://<key>@o4511795618185216.ingest.de.sentry.io/<project-id>`.
|
||||
3. **Settings → Security & Privacy**: turn on **"Prevent Storing of IP Addresses"** (M5).
|
||||
4. **Alerts**: keep the default rule "A new issue is created" → e-mail to you (Q7 = A). Environments `test` and `production` appear automatically after the first event.
|
||||
|
||||
### In the code (after approval)
|
||||
| File | Change |
|
||||
|---|---|
|
||||
| `package.json` | Add `@sentry/react` (same package as SlpSoftware) |
|
||||
| `src/monitoring/config.ts` (new) | `sentryDsn` (from step 2) and `monitoringFor(hostname)` → `{ environment, umamiWebsiteId }` or `null` for unknown hosts (M1) |
|
||||
| `src/monitoring/sentry.ts` (new) | `startSentry()`: loads `@sentry/react` dynamically after the `load` event (M4); `init` with `environment`, `release` (commit SHA from the build), `sendDefaultPii: false`, no tracing or replay. `reportError(error)`: queues errors until Sentry is ready. |
|
||||
| `src/main.tsx` | Calls `startSentry()` |
|
||||
| `src/components/StatusPage/ErrorPage.tsx` | Besides `console.error`, also `reportError(error)` (BR-ERR-03 extended) |
|
||||
| `config/securityHeaders.ts` | `connect-src` + Sentry ingest host (M7); regenerated into `web.config` and nginx |
|
||||
| Workflow `check` job | Build with `VITE_RELEASE=${{ github.sha }}` so Sentry shows which release an error came from |
|
||||
|
||||
### Check after deploy
|
||||
On `https://test.andreaslop.nl`, run in the browser console:
|
||||
```js
|
||||
setTimeout(() => { throw new Error('Sentry-test vanaf test') })
|
||||
```
|
||||
The error appears in Sentry under environment `test` within a minute, and you get an e-mail for the new issue.
|
||||
|
||||
## 2. Umami (visitor dashboard)
|
||||
|
||||
### In Umami (once)
|
||||
1. Log in at `https://analytics.slpsoftware.nl`.
|
||||
2. **Settings → Websites → Add website**, twice:
|
||||
- name `Andrea Slop Fotografie`, domain `andreaslop.nl`
|
||||
- name `Andrea Slop Fotografie (test)`, domain `test.andreaslop.nl`
|
||||
3. Copy both **Website IDs** (a UUID per website).
|
||||
|
||||
### In the code (after approval)
|
||||
| File | Change |
|
||||
|---|---|
|
||||
| `src/monitoring/config.ts` | The two website IDs, one per hostname (M6) |
|
||||
| `src/components/Analytics/UmamiAnalytics.tsx` (new) | Adds `https://analytics.slpsoftware.nl/script.js` with `data-website-id`, `data-domains=<hostname>` and `data-do-not-track="true"`, only for a known hostname (M1). Same pattern as SlpSoftware's `UmamiAnalytics`. |
|
||||
| `src/components/AppShell.tsx` | Renders `UmamiAnalytics` |
|
||||
| `config/securityHeaders.ts` | `script-src` and `connect-src` + `https://analytics.slpsoftware.nl` (M7) |
|
||||
|
||||
### Check after deploy
|
||||
Open `https://test.andreaslop.nl`. In Umami, the test website shows a visitor under "Realtime". If you have Do Not Track switched on in your browser, you won't see yourself; that is expected.
|
||||
|
||||
## 3. UptimeRobot (availability + down e-mails)
|
||||
|
||||
No code needed. Create these monitors in your existing account (type **HTTP(s)**, interval 5 minutes, alert contact: your e-mail):
|
||||
|
||||
| Monitor | URL | When |
|
||||
|---|---|---|
|
||||
| Andrea Slop — test | `https://test.andreaslop.nl/` | Now |
|
||||
| Andrea Slop — test — deep link | `https://test.andreaslop.nl/portfolio` | Now (checks the SPA fallback) |
|
||||
| Andrea Slop — productie | `https://andreaslop.nl/` | **Now**. It watches the current WordPress site until the DNS switch, and the new site after that. |
|
||||
| Andrea Slop — productie — deep link | `https://andreaslop.nl/portfolio` | **After go-live**. On WordPress this URL may not exist and would give false alarms. |
|
||||
|
||||
Optional: type **Keyword** with the keyword `Andrea Slop Fotografie`. That catches an empty or wrong page that still answers 200; the word is in the static HTML of the new site.
|
||||
|
||||
## 4. Tests (part of the code changes)
|
||||
- **`monitoringFor`**: example tests for each known hostname, plus a property test that every other hostname (random strings, `localhost`, IP addresses) returns `null` (PBT-03 invariant).
|
||||
- **`UmamiAnalytics`**: no script for an unknown host; the right `data-website-id` and `data-domains` for each known host; only one script element.
|
||||
- **`reportError`**: errors before initialisation are queued and sent once Sentry is ready; nothing is sent for an unknown host.
|
||||
- **`securityHeaders`**: the production CSP contains exactly these two external hosts, in the right directives only, and no wildcards.
|
||||
- **`serverConfig`**: drift test; `web.config` and nginx contain the new CSP.
|
||||
|
||||
## 5. Values needed from you
|
||||
Fill these in after steps 1 and 2. Placeholders are fine to start with; monitoring stays off until they are set.
|
||||
|
||||
| Value | From |
|
||||
|---|---|
|
||||
| Sentry DSN | Sentry, step 1.2 |
|
||||
| Umami website ID, production | Umami, step 2.3 |
|
||||
| Umami website ID, test | Umami, step 2.3 |
|
||||
Reference in New Issue
Block a user