Langsame Zugriffe mit der Performance-Diagnose finden

Diese Betriebsanleitung zeigt Ihnen, welche HTTP-Routengruppen langsam sind und wie stark Datenbankzugriffe dazu beitragen. Nach Abschluss besitzen Sie eine priorisierte, datensparsame Messung als Ausgangspunkt für eine gezielte Optimierung.

Voraussetzungen

Sie benötigen einen gültigen nucli-Alias für den System-Mandanten und den Scope system_diagnostics:read. Prüfen Sie den Kontext vor der Messung:

bash

nucli --tenant system whoami --scopes

Führen Sie Messungen in Produktion oder Staging nur mit ausdrücklicher Freigabe durch. Der Befehl liest Metriken und verändert keine Produktdaten.

Routen messen

Wählen Sie ein Zeitfenster mit repräsentativem Traffic:

bash

nucli --tenant system performance routes --window 30s --min-requests 5 --limit 20

Für automatisierte Auswertungen verwenden Sie JSON:

bash

nucli --tenant system performance routes --window 2m --min-requests 20 --limit 50 --json

Der Befehl liest zu Beginn und Ende je einen kumulativen Snapshot. Er zeigt nur Routen, die im Fenster die Mindestanzahl erreichen, und sortiert zuerst nach P95-Latenz. Ein Serverneustart oder rückläufige Zähler bricht die Messung ab; starten Sie sie dann erneut.

Ausgabe einordnen

Wert	Bedeutung
`P95`	Obergrenze des Histogrammbuckets, unter der ungefähr 95 Prozent der Requests liegen
`AVG`	mittlere HTTP-Laufzeit im Messfenster
`DB AVG`	mittlere kumulierte Datenbankzeit pro Request
`DB Q/REQ`	mittlere Anzahl Datenbankabfragen pro Request
`4XX` / `5XX`	Anteil der Client- beziehungsweise Serverfehler
`TARGET`	sicheres Router-Pattern oder endliche Pfadfamilie, nie der konkrete Pfad

Ein Wert mit >= ist gedeckelt: Das Quantil lag nur im unendlichen Bucket und ist mindestens so groß wie die angezeigte höchste Grenze. Parallel laufende DB-Abfragen können zusammen mehr Zeit als die HTTP-Wandzeit ergeben.

Hohe HTTP-Zeit bei niedriger DB-Zeit deutet eher auf Anwendungslogik, externe Dienste oder große Antworten. Hohe DB-Zeit oder viele Queries lenken die Analyse auf Query-Plan, Indizes, N+1-Zugriffe oder Pool-Wartezeit. Diese Hinweise sind noch kein Beweis; optimieren Sie den konkreten Endpunkt in einer separaten, getesteten Änderung.

Prometheus ist optional

Workspace erzeugt die Metriken selbst. nucli performance routes benötigt keinen Prometheus-Server. Ein externer Prometheus-kompatibler Collector ist nur nötig, wenn Sie Zeitreihen dauerhaft speichern, Dashboards erstellen oder Alerts auslösen möchten.

Der geschützte Rohendpunkt lautet /api/v1/system/metrics. Er enthält keine konkreten Request-Pfade, Query-Strings, SQL-Texte, Identitäts- oder Tenant-Labels. Geben Sie trotzdem nur die für die Diagnose benötigten Aggregate weiter.

Weitere allgemeine Diagnosewege finden Sie unter Diagnose und Readiness.