Dieses Dokument beschreibt den lokalen Observability-Stack für die Entwicklung mit Docker Compose.

Der Stack ist Teil der offiziellen Runtime-Profile local-keycloak und local-builder. Für den operativen Einstieg zuerst ./runtime-profile-betrieb.md lesen; dieses Dokument bleibt die Detailreferenz für Monitoring-Konfiguration und Troubleshooting.

Architektur-Referenz: Logging Architecture

Der Stack besteht aus:

• Prometheus (Metriken)
• Loki (Logs)
• Grafana (Dashboards)
• OpenTelemetry Collector (OTLP Hub)
• Promtail (Container-Log-Sammlung)

Alle Services sind lokal gebunden (localhost) und nutzen eine 7-Tage-Retention.

1. Optional: .env anlegen (siehe .env.example), z. B.:
   • GF_SECURITY_ADMIN_PASSWORD=dev-admin
2. Start:
   • Kombiniertes Setup: docker compose -f docker-compose.yml -f docker-compose.monitoring.yml up -d
3. Health-Checks:
   • Prometheus: http://localhost:9090/-/healthy
   • Loki: http://localhost:3100/ready
   • Grafana: http://localhost:3001/api/health
   • OTEL Collector: http://localhost:13133/healthz
   • Promtail: http://localhost:3101/ready

• Grafana: http://localhost:3001
  • User: admin
  • Passwort: .env → GF_SECURITY_ADMIN_PASSWORD

Die Dashboards werden beim Start automatisch aus dem Repo geladen:

• dev/monitoring/grafana/dashboards/development-overview.json
• dev/monitoring/grafana/dashboards/application-logs.json
• dev/monitoring/grafana/dashboards/multi-tenancy-test.json

Das Logging-Modell unterscheidet zwei feste Betriebsmodi:

• Development: Console und lokale Dev-Konsole sind aktiv; OTEL wird nur als aktiver Exportpfad genutzt, wenn das SDK erfolgreich initialisiert wurde.
• Production: Console und Dev-Konsole sind aus; OTEL ist verpflichtender Exportpfad.

Beispiel für die Initialisierung:

import { startOtelSdk } from '@sva/monitoring-client';

await startOtelSdk({
  serviceName: 'sva-studio-backend',
  environment: process.env.NODE_ENV ?? 'development',
  otlpEndpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT
});

Hinweis fuer lokale Entwicklung:

• Ohne laufenden Monitoring-Stack bleibt die App funktionsfaehig.
• Console und Dev-Konsole liefern weiterhin lokale Diagnose.
• Fuer einen bewusst schlanken lokalen Lauf kann OTEL via ENABLE_OTEL=false deaktiviert werden.
• Die lokale Dev-Konsole liest redaktierte Server-Logs nur in Development; in Production gibt es dafuer keinen aktiven UI- oder Serverpfad.

Custom Metrics (Business Events):

import { recordBusinessEvent } from '@sva/monitoring-client';

recordBusinessEvent('content.published', {
  workspace_id: 'local-dev',
  component: 'cms'
});

Erlaubte Labels:

• workspace_id (mandatory)
• component
• environment
• level

Verbotene Labels (PII / High Cardinality):

• user_id, session_id, email, request_id, token, authorization, api_key, secret, ip

• Token, Passwörter und Secrets werden redacted.
• E-Mails werden maskiert.
• Request-/User-/Session-IDs werden als Payload geführt, nicht als Labels.

PromQL:

• Requests/s: sum(rate(http_requests_total[5m])) by (job)
• CPU: sum(rate(process_cpu_seconds_total[5m])) by (job)

LogQL:

• Alle Logs: {component=~".+"}
• Errors (5m): sum(count_over_time({level="error"}[5m]))
• Logs je Workspace: sum(count_over_time({workspace_id=~".+"}[5m])) by (workspace_id)

• OTLP/HTTP v1
• Prometheus Remote Scrape
• Loki Push API v1

• Alle Ports sind an localhost gebunden.
• Keine externen Ingresses.
• PII-Redaction aktiv.
• Label-Whitelist enforced.

Für den Monitoring-Stack existiert ein dedizierter CI-Lauf:

• Script: scripts/ci/monitoring-stack-ci.sh
• Workflow: .github/workflows/monitoring-stack-ci.yml

Der CI-Lauf prüft:

• Docker-Compose Validierung + Service-Health
• Label-Schema in Loki (required + forbidden labels)
• Export von Basis-Metriken nach artifacts/monitoring/*.json

Port-Konflikte

• Prüfen, ob Ports 3001/3100/9090/4317/4318 belegt sind.

Hoher RAM-Verbrauch

• Prüfen, ob Docker Desktop ausreichend RAM hat (>= 4 GB empfohlen).

Grafana zeigt keine Daten

• Datasources prüfen (Prometheus/Loki erreichbar?)
• Health-Checks abrufen.

Loki meldet „entry too far behind“

• Ursache: Promtail liest alte Container-Logs mit Zeitstempeln außerhalb des akzeptierten Loki-Fensters.
• Aktuelle Schutzmaßnahme: drop-Stage in dev/monitoring/promtail/promtail-config.yml mit older_than: 1h.
• Wirkung: Alte Backfill-Zeilen werden vor dem Push verworfen; neue Logs werden normal ingestiert.

Install

• docker compose -f docker-compose.yml -f docker-compose.monitoring.yml up -d

Update/Rollback

• Update: docker compose pull && docker compose up -d
• Rollback: docker compose down und docker compose up -d mit vorherigem Image-Tag

Backup/Restore

• Prometheus/Loki nutzen lokale Volumes.
• Sicherung: docker volume inspect + docker run --rm -v <volume>:/data -v $PWD:/backup alpine tar -czf /backup/<name>.tgz /data
• Restore: docker run --rm -v <volume>:/data -v $PWD:/backup alpine tar -xzf /backup/<name>.tgz -C /

• Tastatur-Navigation über Grafana-UI möglich.
• Kontrast über Grafana Theme Settings anpassen.
• Live-Tail kann pausiert werden (Barrierefreiheit).