feat(superadmin): migrate internal docs from docusaurus to guava kb
This commit is contained in:
Codex Agent
@@ -0,0 +1,145 @@
|
||||
---
|
||||
title: Monitoring & Observability
|
||||
---
|
||||
|
||||
Dieses Dokument sammelt die wichtigsten Monitoring‑Punkte der Plattform und soll helfen, die richtigen Dashboards und Alerts aufzubauen.
|
||||
|
||||
## 1. Was sollte überwacht werden?
|
||||
|
||||
- **Verfügbarkeit**
|
||||
- HTTP‑Checks auf zentrale Endpunkte (Landing, Join‑Token‑Flows, Guest Upload, Tenant Admin Login).
|
||||
- Public‑API‑Checks (`/api/v1/events/{token}`, Galerie, Upload‑Endpoints).
|
||||
- **Queues**
|
||||
- Länge und Durchsatz der Queues `default`, `media-storage`, `media-security`, `notifications`.
|
||||
- Age/Time‑in‑Queue, Anzahl der Failed Jobs.
|
||||
- **Storage**
|
||||
- Füllstand der Hot‑Storage‑Volumes/Buckets.
|
||||
- Anzahlen/Status in `event_media_assets` (z.B. viele `pending` oder `failed`).
|
||||
- **Fehler-Raten**
|
||||
- HTTP 5xx/4xx spitzenweise, gruppiert nach Route/Service.
|
||||
- Applikations‑Logs mit Error/Warning‑Level.
|
||||
- **Billing & Webhooks**
|
||||
- Fehlgeschlagene Lemon Squeezy/RevenueCat‑Webhooks.
|
||||
- Differenz zwischen erwarteten und verarbeiteten Zahlungen (optional).
|
||||
|
||||
## 2. Werkzeuge & Quellen
|
||||
|
||||
- **Horizon**
|
||||
- Live‑Überblick über Laravel‑Queues.
|
||||
- Alerts, wenn eine Queue zu lange Backlog aufbaut.
|
||||
- **Docker/Dokploy**
|
||||
- Container‑Health (Restart‑Loops, Ressourcennutzung).
|
||||
- Service‑Healthchecks.
|
||||
- **Logs**
|
||||
- Laravel‑Logs (`storage/logs/*.log`), ggf. via Promtail/Loki oder ELK zentralisiert.
|
||||
- Spezifische Channels (z.B. `storage-jobs`, `notifications`, `billing`).
|
||||
- **Metriken**
|
||||
- Falls vorhanden: Prometheus/Grafana‑Dashboards für App‑/DB‑/Redis‑Metriken.
|
||||
|
||||
> TODO: Wenn konkrete Dashboards in Grafana o.Ä. existieren, füge hier Screenshots/Links und eine kurze Erklärung der Panels ein.
|
||||
|
||||
## 3. Alarmierung & Schwellenwerte
|
||||
|
||||
Konkrete Schwellenwerte hängen von Traffic und Infrastruktur ab, aber folgende Muster haben sich bewährt:
|
||||
|
||||
- **Queues**
|
||||
- `default`:
|
||||
- Warnung: > 100 Jobs oder ältester Job > 5 Minuten.
|
||||
- Kritisch: > 300 Jobs oder ältester Job > 15 Minuten.
|
||||
- `media-storage`:
|
||||
- Warnung: > 200 Jobs oder ältester Job > 10 Minuten.
|
||||
- Kritisch: > 500 Jobs oder ältester Job > 30 Minuten.
|
||||
- `media-security`:
|
||||
- Warnung: > 50 Jobs oder ältester Job > 5 Minuten.
|
||||
- Kritisch: > 150 Jobs oder ältester Job > 15 Minuten.
|
||||
- `notifications`:
|
||||
- Warnung: > 100 Jobs dauerhaft im Backlog.
|
||||
- Kritisch: wenn die Queue dauerhaft wächst, während Events live laufen.
|
||||
- **Uploads**
|
||||
- Fehlerquote bei Upload‑Endpoints:
|
||||
- Warnung: 2–5 % Fehler (HTTP 4xx/5xx) über 5‑minütiges Fenster.
|
||||
- Kritisch: > 5–10 % Fehler in 5 Minuten.
|
||||
- Anzahl „hängender“ Uploads:
|
||||
- Warnung, wenn `storage:check-upload-queues` für denselben Event wiederholt Alarm schlägt (z.B. mehr als 5 benachrichtigte Events in 10 Minuten).
|
||||
- **Public API**
|
||||
- Latenz für `GET /api/v1/events/{token}` und `/photos`:
|
||||
- Warnung: P95 > 500 ms über 5 Minuten.
|
||||
- Kritisch: P95 > 1–2 s über 5 Minuten.
|
||||
- Fehlerraten für diese Endpoints:
|
||||
- Warnung: > 2 % 5xx über 5 Minuten.
|
||||
- Kritisch: > 5 % 5xx über 5 Minuten.
|
||||
- **Billing**
|
||||
- Failed Webhooks:
|
||||
- Warnung: mehr als N (z.B. 5–10) fehlgeschlagene Webhooks pro 10 Minuten.
|
||||
- Kritisch: schneller Anstieg oder > 20 % Fehleranteil.
|
||||
- Differenz zwischen erwarteten und verarbeiteten Zahlungen:
|
||||
- Regelmäßige Reports (z.B. täglich) statt harter Alerts, aber auffällige Abweichungen sollten ein Incident auslösen.
|
||||
|
||||
## 4. Betriebliche Nutzung
|
||||
|
||||
- **Daily Checks**
|
||||
- Horizon Queue‑Dashboard kurz prüfen.
|
||||
- Logs auf neue Fehler‑/Warnmuster scannen.
|
||||
- **Bei Incidents**
|
||||
- Monitoring‑Daten helfen, Ursache und zeitlichen Verlauf zu rekonstruieren (siehe `docs/ops/incidents-major.md`).
|
||||
|
||||
## 5. Zusammenspiel mit bestehenden Kommandos
|
||||
|
||||
Einige Artisan‑Kommandos sind explizit für Monitoring/Health gedacht. Sie sollten in Cron/Scheduler oder externe Checks integriert werden:
|
||||
|
||||
- `storage:monitor` (falls vorhanden)
|
||||
- Aggregiert Storage‑Auslastung und Queue‑Health basierend auf `config/storage-monitor.php`.
|
||||
- Kann Alerts per Mail/Log triggern, wenn Schwellwerte überschritten werden.
|
||||
- `storage:check-upload-queues`
|
||||
- Überprüft, ob Upload‑bezogene Queues im erwarteten Rahmen liegen und triggert Gast‑Alerts bei Problemen (siehe `docs/ops/guest-notification-ops.md`).
|
||||
- `storage:archive-pending`
|
||||
- Kein klassisches Monitoring‑Kommando, aber relevant, um zu prüfen, ob Archivierungsjobs hinterherhinken (z.B. viele alte `hot`‑Assets).
|
||||
|
||||
Diese Kommandos sind kein Ersatz für echtes Monitoring, liefern aber wertvolle Signale, die in Dashboards und Alerts einfließen können.
|
||||
|
||||
## 6. Beispiele für Metrik- und Alert-Definitionen
|
||||
|
||||
Nachfolgend beispielhafte Formulierungen, wie Alerts unabhängig vom verwendeten Monitoring‑System aussehen könnten.
|
||||
|
||||
### 6.1 Queue-Backlog Alert (Pseudocode)
|
||||
|
||||
**Ziel**: Meldung, wenn `media-storage` zu lange Backlog aufbaut.
|
||||
|
||||
- Bedingung:
|
||||
- `queue_length("media-storage") > 500` **OR**
|
||||
- `oldest_job_age("media-storage") > 30min`
|
||||
- Dauer:
|
||||
- 2 aufeinanderfolgende Messintervalle (z.B. 2×5 Minuten).
|
||||
- Aktion:
|
||||
- Alarm an On‑Call + Hinweis auf `docs/ops/media-storage-spec.md` und `docs/ops/dr-storage-issues.md`.
|
||||
|
||||
### 6.2 Upload-Error-Rate Alert
|
||||
|
||||
**Ziel**: Upload‑Probleme für Gäste früh erkennen.
|
||||
|
||||
- Bedingung:
|
||||
- Anteil `5xx` oder „applikationsspezifische Fehlercodes“ bei `POST /api/v1/events/*/upload` > 5 % in 5 Minuten.
|
||||
- Aktion:
|
||||
- Alarm an On‑Call, Link zum Public‑API‑Incident‑Playbook und Storage‑Runbook.
|
||||
|
||||
### 6.3 Public-API-Latenz Alert
|
||||
|
||||
**Ziel**: Langsame Galerien / Token‑Aufrufe frühzeitig sehen.
|
||||
|
||||
- Bedingung:
|
||||
- `P95(latency(GET /api/v1/events/*)) > 1000ms` über 5 Minuten.
|
||||
- Aktion:
|
||||
- Alarm an On‑Call, eventuell automatische Skalierung oder Untersuchung (DB/Redis‑Last).
|
||||
|
||||
### 6.4 Billing-Webhook Alert
|
||||
|
||||
**Ziel**: Fehler bei Lemon Squeezy/RevenueCat‑Webhook‑Verarbeitung erkennen.
|
||||
|
||||
- Bedingung:
|
||||
- Mehr als 10 fehlgeschlagene Webhook‑Verarbeitungen innerhalb von 10 Minuten, oder Verhältnis `failed/success` > 0,2.
|
||||
- Aktion:
|
||||
- Alarm an On‑Call + Finance/Billing‑Verantwortliche, Verweis auf `docs/ops/billing-ops.md`.
|
||||
|
||||
Diese Beispiele sollen helfen, konkrete Regeln in eurem Monitoring‑Tool zu definieren. Die genauen Zahlen sollten anhand realer Traffic‑Muster feinjustiert werden.
|
||||
|
||||
Dieses Dokument ist bewusst technologie‑agnostisch formuliert – die konkrete Implementierung (Prometheus, Grafana, Loki, ELK, SaaS‑Monitoring) sollte hier nachgezogen und mit Beispielen ergänzt werden.
|
||||
@@ -0,0 +1,104 @@
|
||||
---
|
||||
title: GlitchTip (Error Monitoring)
|
||||
---
|
||||
|
||||
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`).
|
||||
- For source map uploads via the Vite plugin, also set: `SENTRY_AUTH_TOKEN`, `SENTRY_ORG`, `SENTRY_PROJECT`, `SENTRY_URL=https://logsder.fotospiel.app`.
|
||||
|
||||
## 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 build-time asset steps.
|
||||
- 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.
|
||||
40
docs/superadmin-kb/de/10-monitoring-diagramme/03-diagrams.md
Normal file
40
docs/superadmin-kb/de/10-monitoring-diagramme/03-diagrams.md
Normal file
@@ -0,0 +1,40 @@
|
||||
---
|
||||
title: Architekturdiagramme
|
||||
---
|
||||
|
||||
Diese Seite bündelt einfache Diagramme für zentrale Plattform‑Flows. Sie sind absichtlich high‑level gehalten und sollen neuen Operatoren einen schnellen Überblick geben.
|
||||
|
||||
## 1. Medien‑Pipeline (Mermaid)
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
Guest[Guest PWA] -->|Foto upload| API[Laravel API]
|
||||
API -->|Validierung & DB| DB[(DB: events,\nevent_media_assets)]
|
||||
API -->|Datei schreiben| HotStorage[(Hot Storage\n/var/www/storage)]
|
||||
|
||||
HotStorage --> QueueMedia[Queue: media-storage]
|
||||
QueueMedia --> WorkerMedia[Worker: media-storage-worker]
|
||||
WorkerMedia --> Archive[(Archive Storage\nz.B. S3/Wasabi)]
|
||||
|
||||
WorkerMedia --> Thumbs[Job: Thumbnails]
|
||||
Thumbs --> HotStorage
|
||||
|
||||
DB --> PublicAPI[Public API]
|
||||
PublicAPI --> Guest
|
||||
```
|
||||
|
||||
## 2. Checkout & Billing (Mermaid)
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
Tenant[Browser Tenant-Admin] -->|Paket wählen| App[Laravel App]
|
||||
App -->|CheckoutSession anlegen| DB[(DB: checkout_sessions,\n tenant_packages)]
|
||||
App -->|Redirect| LemonSqueezy[Lemon Squeezy Checkout]
|
||||
|
||||
LemonSqueezy -->|Zahlung erfolgreich| Webhook[Lemon Squeezy Webhook Endpoint]
|
||||
Webhook -->|Event verarbeiten| BillingService[CheckoutWebhookService]
|
||||
BillingService -->|TenantPackage aktualisieren| DB
|
||||
|
||||
DB --> App
|
||||
App --> Tenant
|
||||
```
|
||||
Reference in New Issue
Block a user