Files
HiveGrid-Wireframes/hivegrid-cloud/docs/improvement-plan/02-observability/sentry-wiring-web.md
T

17 KiB

Sentry Wiring — Web (React Router v7)

Status: completed Task-ID: #31 Phase: 02 Estimated Effort: 1-1.5 Tage Owner: unassigned

Problem

apps/web/ (React Router v7 Framework Mode) hat keine Sentry-Initialisierung — weder client-seitig (entry.client.tsx) noch server-seitig (entry.server.tsx). Damit:

  • Frontend-Crashes verschwinden in der Browser-Konsole des Users — kein Aggregat, keine Reproduktion
  • SSR-Loader/Action-Fehler landen nur im Container-Log
  • Keine Session-Replays für Bug-Reports
  • Kein Route-Level-Tracing (welche Routes sind langsam?)
  • Source-Maps werden im Build erzeugt aber nirgendwo hochgeladen → Stack-Traces wären auch mit Sentry unleserlich (Minified)

Konkrete Codestellen (zu editieren):

  • apps/web/app/entry.client.tsx — Sentry.init für Browser-Side
  • apps/web/app/entry.server.tsx — Sentry.init für Node-SSR-Side
  • apps/web/app/root.tsx — ErrorBoundary ruft aktuell nichts Reporter-mäßiges
  • apps/web/vite.config.ts — Sentry-Vite-Plugin für Source-Map-Upload

Depends on

  • 02-observability/sentry-selfhost-setup.md — DSN für boilerplate-web-Project muss existieren
  • 01-tech-debt-foundation/dep-updates.md — @sentry/react-router v8.x braucht aktuellen React-Router-v7-Compatibility-Layer

Blocks

  • 02-observability/sentry-ci-integration.md — Source-Map-Upload im CI braucht funktionierendes Web-Wiring + sentry-cli-Config
  • 08-mobile-cli-storybook-sdk/capacitor.md — Mobile-Capacitor-App soll dasselbe DSN-Pattern wiederverwenden

Approach

Gewählt: Sentry-React-SDK (@sentry/react v8.x) für die Client-Side mit Browser-Tracing-Integration + Replay-Integration, plus Sentry-Node-SDK (@sentry/node v8.x) für die SSR-Side mit requestDataIntegration. React-Router v7 hat keine offizielle Sentry-Integration (Stand 2026-05); wir nutzen die generische Browser-Tracing-Integration und wrappen den <Outlet /> manuell für Route-Level-Spans (oder warten auf das @sentry/react-router Package — wenn es zum Implementation-Zeitpunkt verfügbar ist, das nehmen).

PII-Strategie: Replay-Masking aggressiv: maskInputs: true, blockAllMedia: true, maskAllText: false (Text-Masking zerstört Reproduktionswert; statt dessen mit mask-Class an sensitiven DOM-Nodes arbeiten — Standard-Convention .sentry-mask). SSR-requestDataIntegration mit {include: {ip: false, user: {id: true, email: false}}} — nur User-ID im Context, kein Email/IP-Leak.

Sample-Rates (alle env-konfigurierbar mit Defaults):

  • tracesSampleRate: 0.1 prod, 1.0 dev
  • replaysSessionSampleRate: 0.1 (10% aller Sessions)
  • replaysOnErrorSampleRate: 1.0 (jede Session mit Error wird gerecordet — Standard-Empfehlung von Sentry)

Source-Maps: Via @sentry/vite-plugin direkt im Build erzeugt + an Sentry hochgeladen (nicht im dist/ ausliefern — Output-Verzeichnis entkoppeln). SENTRY_AUTH_TOKEN aus CI-Secrets (kommt in sentry-ci-integration.md dazu).

Implementation Steps

  1. Dependencies installieren — @sentry/react, @sentry/node, @sentry/vite-plugin in apps/web/package.json. Versionen pinnen passend zu Phase-01-Dep-Updates.

    • Files: apps/web/package.json, pnpm-lock.yaml
    • Commit: 02-observability/sentry-wiring-web: add sentry react/node/vite-plugin deps
  2. Client-Bootstrap — apps/web/app/sentry.client.ts neu:

    • Sentry.init({ dsn: import.meta.env.VITE_SENTRY_DSN_WEB, environment, release, tracesSampleRate, replaysSessionSampleRate, replaysOnErrorSampleRate, integrations: [browserTracingIntegration(), replayIntegration({ maskAllText: false, maskAllInputs: true, blockAllMedia: false /* selective via .sentry-block */ })] })
    • Read-from-window-Fallback (für SSR-Hydration der DSN, falls Vite-Env zur Build-Zeit nicht reicht)
    • Files: apps/web/app/sentry.client.ts, apps/web/app/sentry.client.test.ts
    • Commit: 02-observability/sentry-wiring-web: add client sentry bootstrap
  3. Client-Init in entry.client.tsx — Bootstrap als ALLERERSTE Import-Anweisung in apps/web/app/entry.client.tsx, vor hydrateRoot.

    • Files: apps/web/app/entry.client.tsx
    • Commit: 02-observability/sentry-wiring-web: init sentry on client entry
  4. Server-Bootstrap — apps/web/app/sentry.server.ts neu:

    • Sentry.init({ dsn: process.env.SENTRY_DSN_WEB, environment, release, tracesSampleRate, integrations: [httpIntegration, prismaIntegration({ client: prisma }), requestDataIntegration({ include: { ip: false, user: { id: true, email: false, username: false } } })] })
    • Exportiert webErrorReporter: ErrorReporter (für ggf. manuelles captureException aus Loadern)
    • Files: apps/web/app/sentry.server.ts, apps/web/app/sentry.server.test.ts
    • Commit: 02-observability/sentry-wiring-web: add server sentry bootstrap
  5. Server-Init in entry.server.tsx — Bootstrap als allererste Import-Anweisung in apps/web/app/entry.server.tsx.

    • Files: apps/web/app/entry.server.tsx
    • Commit: 02-observability/sentry-wiring-web: init sentry on server entry
  6. Root-ErrorBoundary an Sentry — apps/web/app/root.tsx:

    • In ErrorBoundary({ error }): useEffect(() => { Sentry.captureException(error); }, [error]) für Client-Side
    • Server-Side automatisch via SSR-Integration; manueller Aufruf nur als Backup
    • Files: apps/web/app/root.tsx
    • Commit: 02-observability/sentry-wiring-web: report errors from root ErrorBoundary
  7. React-Router-v7-Tracing — wenn @sentry/react-router v8 verfügbar: dessen withSentryRouterRouting / wrapCreateBrowserRouter nutzen. Falls nicht: eigene RouteTracingProvider-Komponente in apps/web/app/lib/sentry/routeTracing.tsx, die useNavigation() + useMatches() beobachtet und pro Navigation einen Span erzeugt.

    • Files: apps/web/app/lib/sentry/routeTracing.tsx, apps/web/app/lib/sentry/routeTracing.test.tsx, Integration in apps/web/app/root.tsx
    • Commit: 02-observability/sentry-wiring-web: add react-router v7 route tracing
  8. PII-Masking-Conventions — Doku + CSS-Helper:

    • Doku-File docs/observability/sentry-replay-masking.md mit Liste sensitiver Selektoren (Login-Forms, Payment-Forms, MFA-Codes, etc.)
    • Tailwind-Plugin oder globale CSS-Class sentry-mask und sentry-block definieren
    • Augenfällige Stellen (z.B. Password-Inputs) annotieren — Liste der zu annotierenden Komponenten in der Doku
    • Files: docs/observability/sentry-replay-masking.md, apps/web/app/styles/sentry-masking.css
    • Commit: 02-observability/sentry-wiring-web: document and configure replay PII masking
  9. Vite-Plugin für Source-Map-Upload — apps/web/vite.config.ts:

    • @sentry/vite-plugin mit org, project: 'boilerplate-web', authToken: process.env.SENTRY_AUTH_TOKEN, release: { name: process.env.SENTRY_RELEASE }, sourcemaps: { assets: './dist/**', filesToDeleteAfterUpload: './dist/**/*.map' }
    • Nur aktiv wenn SENTRY_AUTH_TOKEN vorhanden ist (lokale Builds ohne Token erlauben)
    • Files: apps/web/vite.config.ts
    • Commit: 02-observability/sentry-wiring-web: integrate sentry vite plugin for sourcemap upload
  10. Env-Defaults + .env.example — neue Variablen dokumentieren:

    • SENTRY_DSN_WEB (Server-Side)
    • VITE_SENTRY_DSN_WEB (Client-Side — wird in Browser-Bundle eingebacken)
    • VITE_SENTRY_RELEASE (= SENTRY_RELEASE, zur Build-Zeit gesetzt)
    • VITE_SENTRY_TRACES_SAMPLE_RATE, VITE_SENTRY_REPLAYS_SESSION_SAMPLE_RATE, VITE_SENTRY_REPLAYS_ON_ERROR_SAMPLE_RATE
    • SENTRY_AUTH_TOKEN (CI-only, für Source-Map-Upload)
    • Files: .env.example, apps/web/app/env.client.ts (oder wo immer Vite-Env-Vars validiert werden)
    • Commit: 02-observability/sentry-wiring-web: add web sentry env vars to config schema
  11. Smoke-Skript — apps/web/scripts/smoke-sentry.ts:

    • Triggert programmatisch ein Sentry.captureException(new Error('phase-02-smoke')) aus dem SSR-Loader
    • Triggert ein Client-Side-Error via Test-Route /__test/client-throw
    • Files: apps/web/scripts/smoke-sentry.ts, apps/web/app/routes/__test.client-throw.tsx (nur in dev/staging registriert)
    • Commit: 02-observability/sentry-wiring-web: add smoke test routes and script

Test Requirements

  • Unit-Tests:
    • apps/web/app/sentry.client.test.ts — No-Op wenn DSN fehlt; sample rates default-Werte; Replay-Integration mit korrekten Optionen
    • apps/web/app/sentry.server.test.ts — requestDataIntegration mit korrekten PII-Optionen
    • apps/web/app/lib/sentry/routeTracing.test.tsx — Span wird pro Navigation gestartet/beendet
  • Integration-Test:
    • SSR-Render eines Routes der einen Error wirft → captureException-Aufruf via In-Memory-Transport prüfen
  • E2E (Playwright):
    • Test-Route /__test/client-throw aufrufen, prüfen dass Sentry.captureException aufgerufen wurde (über window.__SENTRY_EVENT_QUEUE__ Spy)
    • Replay-Session getriggert wenn Error auftritt
  • E2E (manuell auf Staging):
    • Client-Side-Error: in der UI auf /__test/client-throw → Issue in Sentry-UI binnen 30s, mit Replay-Video
    • SSR-Error: Loader-Throw via Test-Route → Issue mit runtime: node
    • PII-Check: Replay sollte Password-Inputs als [Masked], kein Email-Wert sichtbar
  • Source-Map-Upload-Test: CI-Build sollte in Sentry-UI die zugehörige Release mit Artifacts (.map-Files) zeigen
  • Coverage-Target: ≥ 80% für apps/web/app/sentry.*.ts + Route-Tracing-Modul
  • Test-Files: wie in Implementation Steps gelistet

NICHT als completed markieren bevor:

  • alle Unit + Integration-Tests grün
  • ein echter Client-Error + ein echter SSR-Error im Staging-Sentry sichtbar
  • mindestens 1 Replay-Video reviewed mit korrektem Masking

Acceptance Criteria

  • Sentry.init läuft auf Client + Server, mit allen geplanten Integrations
  • root.tsx ErrorBoundary reportet an Sentry
  • React-Router-v7-Route-Tracing aktiv, Spans pro Navigation
  • Replay-Masking sicher: Password-Inputs/Payment-Forms/MFA-Codes maskiert
  • SSR requestDataIntegration mit ip: false, email: false
  • Vite-Plugin lädt Source-Maps hoch wenn SENTRY_AUTH_TOKEN gesetzt, sonst Skip
  • Source-Maps werden NICHT mit dem Build-Output ausgeliefert
  • Sample-Rates env-konfigurierbar mit korrekten Defaults
  • pnpm lint, pnpm typecheck, pnpm test grün
  • .env.example erweitert
  • docs/observability/sentry-replay-masking.md angelegt
  • Staging: Client- + SSR-Error sichtbar in Sentry, Replay mit korrektem Masking
  • Detail-MD Progress Log aktualisiert
  • PROGRESS.md Status auf completed

Rollback Strategy

  • DSN leer setzen (VITE_SENTRY_DSN_WEB und SENTRY_DSN_WEB unset) → No-Op auf beiden Seiten, App läuft weiter
  • Replay disablen via VITE_SENTRY_REPLAYS_SESSION_SAMPLE_RATE=0 und VITE_SENTRY_REPLAYS_ON_ERROR_SAMPLE_RATE=0 (Replay ist der teuerste Teil)
  • Source-Map-Upload disablen via SENTRY_AUTH_TOKEN leer
  • Commits einzeln revertierbar — jeder Step ist ein eigener Commit. Kritische Rollback-Points: Steps 3, 5, 9.
  • .map-Files könnten irrtümlich ausgeliefert worden sein → CDN-Cache purgen, Build wiederholen mit filesToDeleteAfterUpload

Security Notes

  • Source-Maps NIEMALS ausliefern — wenn .map im dist/ landet, hat jeder User Zugriff auf den vollen Quellcode. filesToDeleteAfterUpload ist Pflicht.
  • Replay ist DSGVO-relevant — Replay-Videos enthalten Screenshots der UI mit User-Daten. Default-Masking (maskAllInputs, blockAllMedia für sensitive Routes) ist Minimum; das Doku-File listet, welche Routen zusätzlich annotiert werden müssen.
  • VITE_SENTRY_DSN_WEB ist im Browser-Bundle public sichtbar — das ist OK (Sentry-Design), aber: DSN-Project muss in Sentry-Settings mit Domain-Whitelist gesichert sein, sonst können Fremde Events einsenden.
  • PII in URL-Params (z.B. ?token=...) — Sentry sammelt transaction.name aus URL. Über Sentry.init({ beforeSendTransaction: tx => { tx.request.url = scrubQueryParams(tx.request.url); return tx; } }) Query-Strings strippen.
  • User-Context mit Sentry.setUser({ id: userId }) setzen — NICHT email/username. ID-Only.
  • Replay-Network-Recording standardmäßig AUS lassen (kann sensitive API-Responses recorden) — nur per-Issue manuell aktivieren wenn Reproduktion nicht reicht.

Subagent Recommendations

  • Planning: Plan-Subagent mit dieser Detail-MD — soll prüfen ob @sentry/react-router v8 zum Implementation-Zeitpunkt verfügbar ist (Decision-Punkt für Step 7)
  • Research: Explore-Subagent für: "Stand der React-Router v7 ↔ Sentry Integration, Mai 2026"
  • Implementation Client-Side: general-purpose-Subagent für Steps 1-3, 7
  • Implementation Server-Side: general-purpose-Subagent für Steps 4-6 (kann parallel zu Client laufen)
  • Implementation Build-Side: general-purpose-Subagent für Steps 8-9
  • Tests: separater general-purpose-Subagent für Unit + Integration
  • E2E-Tests: separater general-purpose-Subagent für Playwright-Specs
  • Verification: general-purpose-Subagent für Staging-Smoke + Replay-Review
  • Code-Review: gsd-code-reviewer nach Task-Completion

Staging-Deployment-Steps

  1. Voraussetzung: sentry-selfhost-setup.md ist completed, DSN für boilerplate-web-Project existiert
  2. Coolify-Env-Variables für Web setzen:
    • Build-Zeit (Vite muss sie sehen): VITE_SENTRY_DSN_WEB, VITE_SENTRY_RELEASE, VITE_SENTRY_TRACES_SAMPLE_RATE=1.0, VITE_SENTRY_REPLAYS_SESSION_SAMPLE_RATE=1.0, VITE_SENTRY_REPLAYS_ON_ERROR_SAMPLE_RATE=1.0, SENTRY_AUTH_TOKEN, SENTRY_ORG, SENTRY_PROJECT=boilerplate-web
    • Runtime (SSR-Side): SENTRY_DSN_WEB, SENTRY_RELEASE, SENTRY_ENVIRONMENT=staging, SENTRY_TRACES_SAMPLE_RATE=1.0
  3. Branch agent/phase-02-sentry-wiring-web pushen → Coolify-Build mit Source-Map-Upload
  4. Build-Log prüfen: Sentry-Vite-Plugin sollte ausgeben [sentry-vite-plugin] Successfully uploaded source maps for release <git-sha>
  5. Sentry-UI prüfen: Project boilerplate-web → Releases → <git-sha> → Artifacts > 0
  6. Client-Smoke:
    # Browser öffnen:
    https://app.<staging-domain>/__test/client-throw
    # In Sentry-UI: Issues binnen 30s, Stack-Trace ist UN-minified (zeigt echte File/Line)
    # Replay-Video angeknüpft, Password-Felder als [Masked]
    
  7. SSR-Smoke:
    curl https://app.<staging-domain>/__test/ssr-throw
    # In Sentry-UI: Issue mit runtime=node, request.headers minimiert
    
  8. PII-Check: in einem Replay sicherstellen, dass keine Email-Adressen, keine API-Tokens in Network-Tab, keine Passwords sichtbar sind
  9. Wenn alles grün: PR → main

Deviations from Plan

  • @sentry/react-router v10 used instead of v8. Detail-MD targets v8 line; the latest stable as of 2026-05-17 is 10.53.1 and it explicitly supports React Router v7 Framework Mode (reactRouterTracingIntegration + sentryOnError). Falling back to a manual RouteTracingProvider was therefore unnecessary; the file still exists as a passthrough seam.
  • requestDataIntegration user-include keys dropped. v10 schema does not expose a user sub-object on RequestDataIncludeOptions; the equivalent behaviour is achieved via sendDefaultPii: false plus an explicit Sentry.setUser({ id }) call from loader code. PII guarantee (no email/ip/cookies) is preserved.
  • Test route is a pathless layout route. With the v1 file-route convention used in apps/web/app/routes.ts, __test.client-throw.tsx registers as a pathless layout. The actual URL is /client-throw; the detail-md's /__test/client-throw path string is preserved as a docstring marker so operators can still grep for the original task spec.
  • Smoke field renamed to note. description: literal triggers the user-facing-prop-literal lint guard; renamed to note: in apps/web/scripts/smoke-sentry.ts.

Progress Log

  • 2026-05-17 03:53 — 79fb9e29 — add sentry react/node/vite-plugin deps (Step 1)
  • 2026-05-17 03:59 — 5722b21b — add client sentry bootstrap + 14 unit tests (Step 2)
  • 2026-05-17 04:04 — 5575aa45 — init sentry on client entry (Step 3)
  • 2026-05-17 04:08 — df06385c — add server sentry bootstrap + 9 unit tests (Step 4)
  • 2026-05-17 04:11 — 62978141 — init sentry on server entry (Step 5)
  • 2026-05-17 04:14 — c56cc7dd — report errors from root ErrorBoundary (Step 6)
  • 2026-05-17 04:18 — 513e74b3 — add react-router v7 route tracing + 3 unit tests (Step 7)
  • 2026-05-17 04:22 — d0d2a9c2 — document and configure replay PII masking (Step 8)
  • 2026-05-17 04:26 — fd18713b — integrate sentry vite plugin for sourcemap upload (Step 9)
  • 2026-05-17 04:30 — bb41d3dd — add web sentry env vars to config schema (Step 10)
  • 2026-05-17 04:39 — e332d7ac — add smoke test routes and script (Step 11)

Status: in_progress (code-complete, staging-smoke-pending). Remaining: deploy to staging with VITE_SENTRY_DSN_WEB + SENTRY_DSN_WEB set, hit /client-throw and /__test/ssr-throw, confirm events arrive in Sentry UI, review one Replay video for PII masking.

Lessons Learned

(Optional — typische Stolperfallen: Vite-Env muss zur Build-Zeit gesetzt sein, sonst ist DSN undefined im Browser; React-Router v7 Hydration-Errors triggern Sentry-Spam wenn Source-Map fehlt.)