added glitchtip using sentry sdk

docs/ops/monitoring-glitchtip.md

@@ -0,0 +1,104 @@
+---
+title: GlitchTip (Error Monitoring)
+sidebar_label: GlitchTip
+---
+
+GlitchTip 5.2 is our Sentry-compatible error and performance monitoring stack. It lives at **https://logsder.fotospiel.app** and accepts the standard Sentry SDKs (Laravel + React). This page explains how to wire the DSNs, roll it out in Docker/Dokploy, and how to sanity-check events. Keep PII out of breadcrumbs and context; log only what is needed to debug.
+
+## 1) Environment variables
+
+Set these in `.env` (never commit) and ensure they are passed through Docker (`docker-compose.dokploy.yml` already forwards them):
+
+```
+SENTRY_LARAVEL_DSN=https://<key>@logsder.fotospiel.app/<project-id>
+SENTRY_ENVIRONMENT=production
+SENTRY_TRACES_SAMPLE_RATE=0.05   # adjust per env
+SENTRY_PROFILES_SAMPLE_RATE=0.02 # optional profiling
+SENTRY_RELEASE=$(git rev-parse --short HEAD)
+
+VITE_SENTRY_DSN=https://<key>@logsder.fotospiel.app/<project-id>
+VITE_SENTRY_ENV=production
+VITE_SENTRY_RELEASE=$(git rev-parse --short HEAD)
+```
+
+Notes:
+
+- DSN is Sentry-format; projects are created in GlitchTip UI. Use per-environment DSNs when possible.
+- Keep sampling conservative in production to avoid noise and cost.
+- If you do **not** want PII, set `SENTRY_SEND_DEFAULT_PII=false` in Laravel config (or handle in `config/sentry.php`).
+
+## 2) Backend (Laravel 12, PHP 8.3)
+
+1. Install SDK: `composer require sentry/sentry-laravel`.
+2. (Optional) Publish config: `php artisan vendor:publish --provider="Sentry\\Laravel\\ServiceProvider" --tag="config"` → tweak `config/sentry.php` (environment, sample rates, PII).
+3. Context enrichment (recommended):
+   - In `app/Exceptions/Handler.php`, set user (`id`, `email`) and tenant/event IDs on the Sentry scope.
+   - Drop noisy 4xx exceptions via `shouldReport` or by ignoring `HttpException` with status < 500.
+4. Health check: run `php artisan sentry:test` (sends a test event).
+5. Queue/CLI: the DSN is forwarded to workers via the shared env anchor, so job failures also report.
+
+## 3) Frontend (React 19 / Vite 7 PWAs)
+
+1. Install SDKs: `npm i @sentry/react @sentry/vite-plugin @sentry/tracing`.
+2. Initialize in each app entry (`resources/js/guest/...` and `resources/js/admin/...`):
+
+```ts
+import * as Sentry from '@sentry/react';
+
+Sentry.init({
+  dsn: import.meta.env.VITE_SENTRY_DSN,
+  environment: import.meta.env.VITE_SENTRY_ENV,
+  release: import.meta.env.VITE_SENTRY_RELEASE,
+  tracesSampleRate: 0.05,
+});
+```
+
+Wrap the root in `<Sentry.ErrorBoundary>` with a user-friendly fallback.
+
+3. (Optional) Vite plugin for source maps:
+
+```ts
+import { sentryVitePlugin } from '@sentry/vite-plugin';
+
+export default defineConfig({
+  plugins: [
+    react(),
+    sentryVitePlugin({
+      org: 'glitchtip',
+      project: 'fotospiel-web',
+      authToken: process.env.SENTRY_AUTH_TOKEN,
+      url: 'https://logsder.fotospiel.app', // GlitchTip base
+    }),
+  ],
+});
+```
+
+If you skip source map upload, events still work; stack traces will be minified.
+
+## 4) Docker/Dokploy wiring
+
+- `docker-compose.dokploy.yml` now forwards `SENTRY_*` and `VITE_SENTRY_*` to `app`, workers, scheduler, and docs-build.
+- Ensure the build container that runs `npm run build` sees `VITE_SENTRY_*` (set in Dokploy env UI or `.env` loaded by Dokploy).
+- Redeploy stack after setting envs; no other container changes needed.
+
+## 5) Rollout / validation checklist
+
+1. Set env vars for the target environment (`production`, `staging`).
+2. Deploy containers.
+3. Trigger test events:
+   - Backend: `php artisan sentry:test`.
+   - Frontend: throw a test error from console (`Sentry.captureException(new Error('GlitchTip smoke test')))`.
+4. Verify events arrive in GlitchTip project at `https://logsder.fotospiel.app`.
+5. Tune `tracesSampleRate`/`profilesSampleRate` after a day of traffic.
+
+## 6) Hygiene & PII guardrails
+
+- Do not attach raw request bodies or tokens. Scrub secrets in Sentry beforeSend hooks if added.
+- Limit user context to non-sensitive identifiers (user id/email) and tenant/event IDs.
+- Avoid logging photo metadata or guest names in breadcrumbs.
+
+## 7) Troubleshooting
+
+- No events: check DSN matches project and env vars are present in container (`printenv | grep SENTRY`).
+- Minified stack traces: upload source maps via the Vite plugin or disable code splitting for critical bundles.
+- High volume: drop sampling (`tracesSampleRate`, `profilesSampleRate`) and add ignore rules for expected 4xx.