Observability

Orimora liefert alles mit, um es wie einen Produktionsdienst zu betreiben: einen Prometheus-Metrics-Endpoint, Health-Probes für deinen Orchestrator, optionales Error-Tracking an ein Sentry-kompatibles Backend und eine Correlation-ID auf jeder Anfrage und Logzeile zur Nachverfolgung. Alles ist standardmäßig aus und wird per Umgebungsvariable aktiviert — die vollständige Tabelle in der Konfiguration.

Überblick

Bereich	Mechanismus	Aktiviert durch
Metriken	GET /api/metrics (Prometheus)	METRICS_TOKEN
Liveness	GET /api/live	immer an
Readiness	GET /api/ready	immer an
Error-Tracking	Sentry-kompatibler Ingest	SENTRY_DSN
Request-Tracing	X-Correlation-Id-Header + Logs	immer an

Prometheus-Metriken

GET /api/metrics liefert Metriken im Prometheus-Text-Format. Der Endpoint ist deaktiviert, bis du METRICS_TOKEN setzt, und verlangt dann genau dieses Token als Bearer-Credential:

curl -s -H "Authorization: Bearer $METRICS_TOKEN" \
  https://dein-orimora.example.com/api/metrics

Ohne Header (oder mit falschem Token) antwortet der Endpoint mit 401; ist METRICS_TOKEN nicht gesetzt, mit 404. Die Antwort wird nie gecacht.

Achtung

Behandle METRICS_TOKEN wie ein Passwort und scrape über TLS. Der Endpoint legt Routennamen und Traffic-Muster offen. Erzeuge eines mit openssl rand -hex 32.

Exponierte Metriken

Zusätzlich zu den Node.js-/Prozess-Standardmetriken von prom-client (process_*, nodejs_* — CPU, Heap, Event-Loop-Lag, offene Handles) sendet Orimora:

Metrik	Typ	Labels	Bedeutung
http_requests_total	Counter	route, method, status	HTTP-Anfragen gesamt
http_request_duration_seconds	Histogram	route, method	Latenzverteilung der Anfragen
auth_attempts_total	Counter	method, outcome	Anmeldeversuche (Magic-Link/SSO/MFA), Erfolg/Fehler
rate_limit_blocks_total	Counter	bucket	Von einem Rate-Limiter abgewiesene Anfragen
audit_events_total	Counter	action, outcome	Protokollierte Audit-Ereignisse

Diese decken die Golden Signals (Traffic, Latenz, Fehler) plus sicherheitsrelevante Zähler ab, auf die du alarmieren willst — z. B. einen Anstieg bei auth_attempts_total{outcome="failure"} oder rate_limit_blocks_total.

Scrape-Konfiguration

scrape_configs:
    - job_name: orimora
      metrics_path: /api/metrics
      scheme: https
      authorization:
          type: Bearer
          credentials: <METRICS_TOKEN>
      static_configs:
          - targets: ['dein-orimora.example.com']

Start-Alerts

groups:
    - name: orimora
      rules:
          - alert: OrimoraHighAuthFailures
            expr: rate(auth_attempts_total{outcome="failure"}[5m]) > 1
            for: 10m
          - alert: OrimoraHighErrorRate
            expr: rate(http_requests_total{status=~"5.."}[5m]) > 0.05
            for: 10m
          - alert: OrimoraSlowRequests
            expr: histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m])) > 1
            for: 15m

Health-Probes

Zwei Endpoints steuern die Container-Orchestrierung; beide sind immer verfügbar und brauchen kein Token:

• GET /api/live — reine Liveness. Antwortet mit 200, solange der Prozess läuft. Nutze ihn, um zu entscheiden, ob der Container neu gestartet wird. Er greift weder auf die Datenbank noch auf Redis zu.
• GET /api/ready — Readiness. Prüft Datenbank und Redis und antwortet nur mit 200, wenn beide erreichbar sind, sonst 503. Nutze ihn, um zu entscheiden, ob Traffic geroutet wird.

Der mitgelieferte Docker-Health-Check nutzt /api/ready. (/api/health bleibt als abwärtskompatibler Alias.) Die Compose-Verdrahtung in der Bereitstellung.

# Kubernetes
livenessProbe:
    httpGet: { path: /api/live, port: 3000 }
readinessProbe:
    httpGet: { path: /api/ready, port: 3000 }

Error-Tracking

Setze SENTRY_DSN, um unerwartete 5xx-Serverfehler und SSO-Authentifizierungsfehler an ein beliebiges Sentry-kompatibles Backend weiterzuleiten — sentry.io, ein selbst gehostetes Sentry oder GlitchTip funktionieren alle, nur der DSN ändert sich (kein Vendor-Lock-in). Reguläre 4xx-Antworten werden nie gesendet.

• SENTRY_ENVIRONMENT — Standard NODE_ENV; trennt Staging und Produktion.
• SENTRY_RELEASE — z. B. ein Git-SHA; gruppiert Issues nach ausgerollter Version.

Hinweis

Payloads werden bereinigt, bevor sie den Prozess verlassen: E-Mail-Adressen, Bearer-/JWT-Tokens, schema://user:pass@host-Credentials und token-förmige Strings werden geschwärzt. Lass SENTRY_DSN leer, um Error-Tracking ganz zu deaktivieren.

Correlation-IDs für Requests

Jede Anfrage erhält eine Correlation-ID. Trägt die eingehende Anfrage einen X-Correlation-Id-Header, wird er übernommen, sonst wird einer erzeugt. Die ID wird:

• in der Antwort als X-Correlation-Id zurückgegeben und
• an jede strukturierte Logzeile angehängt, die während der Bearbeitung entsteht.

Ist Error-Tracking aktiv, hängt dieselbe ID am erfassten Ereignis — du kannst also von einer Logzeile oder HTTP-Antwort direkt zum passenden Fehler springen. Ein vorgelagerter Load-Balancer oder Gateway, der X-Correlation-Id injiziert, ermöglicht Ende-zu-Ende-Tracing über Dienste hinweg.

Siehe auch

• Konfiguration — die vollständige Referenz der Umgebungsvariablen
• Bereitstellung — Health-Check-Verdrahtung für Docker Compose
• Audit-Export (SIEM) — den Audit-Log an dein SIEM streamen
• Sicherheit & Passkeys — Härtung der Authentifizierung