Langsame Zugriffe mit der Performance-Diagnose finden

Ermitteln Sie, welche HTTP-Routengruppen langsam sind und wie stark Datenbankzugriffe dazu beitragen. Die priorisierte, datensparsame Messung dient anschließend 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:

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:

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

Für automatisierte Auswertungen verwenden Sie JSON:

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

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 Betriebsendpunkt lautet /api/v1/system/metrics. Er enthält keine konkreten Request-Pfade, Query-Strings, SQL-Texte, Identitäts- oder Tenant-Labels. Dazu gehören auch die Datenbankpool-Zähler und die installationsweiten Queue-Metriken für Tiefe, Alter, Durchsatz und Fehler.

Mandantenbezogene oder credential-nahe Serien liegen getrennt unter /api/v1/system/metrics/restricted. Für den Abruf sind der System-Mandant und der zusätzliche Scope system_observability_restricted:read erforderlich. Nur die technische Diagnose-Rolle sollte diesen Scope erhalten. Beide Endpunkte benötigen eigene Collector-Ziele, Zugangsmittel und Speicherpfade. Ein Collector darf die getrennten Datenebenen nicht nachträglich zusammenführen.

Bei nucleus-ingress liegen die beiden Ebenen unter /api/control-plane/metrics und /api/control-plane/metrics/restricted. Jeder Pfad verwendet einen eigenen dateibasierten Bearer-Token. Der allgemeine Control-Plane-Token gilt dort nicht. Ohne konfigurierte Token-Datei antwortet der jeweilige Pfad mit 404, bei einem falschen Token mit 401. Identische Token oder nicht lesbare Dateien verhindern den Prozessstart.

Daten sparsam aufbewahren

Hochaufgelöste Betriebsmetriken dürfen höchstens 30 Tage gespeichert werden, eingeschränkte Mandantenserien höchstens 14 Tage. Diese Grenzen setzt der externe Metrikspeicher um; Workspace hält selbst keine Zeitreihen vor. Dashboards und Alerts dürfen nur die Metrikfamilien und festen Labels verwenden, die der jeweilige Endpunkt liefert. Rohpfade, Abfragewerte, Hosts, Identitäten, Request-IDs, SQL, Tabellen- oder Spaltennamen, freie Fehlertexte, User-Agent-Werte und Secrets gehören weder in Labels noch in Annotationen.

Grafana Alloy kann beide Prometheus-Endpunkte getrennt erfassen und intern in OpenTelemetry- oder Remote-Write-Pipelines überführen. Solange deren Attribute nicht denselben Metadatenvertrag erfüllen, darf keine generische HTTP-Autoinstrumentierung aktiviert werden.

Kapazität belastbar nachweisen

Ein einzelner erfolgreicher Lastlauf oder eine beobachtete Mandantenzahl ist noch kein Kapazitätsnachweis. Jeder Nachweis muss mindestens an Produkt-, Infrastruktur- und Lastgeneratorrevision, Testumgebung, Lastprofil, synthetische Kohortengröße, Messfenster und Guardrails gebunden sein. Pflichtszenarien sind Baseline und homogene Rampe. Hinzu kommen gemischte Last, Noisy Neighbor, Hintergrundimport sowie Backup und Restore.

Während einer freigegebenen synthetischen Lastphase erfasst nucli die Anwendungswerte in festen Abständen:

nucli --tenant system performance capacity \
  --window 30m --interval 5s \
  --installation shopcloud-capacity-environment-01 \
  --infrastructure-source /pfad/zum/infra-worktree \
  --infrastructure-repository ssh://git.example.invalid/shopcloud/infrastructure \
  --load-generator-source /pfad/zum/generator-worktree \
  --load-generator-repository ssh://git.example.invalid/shopcloud/load-generator \
  --load-profile-version mixed-v1 \
  --load-profile-file /pfad/zu/mixed-v1.json \
  --stage 20 --json

Beide Quellpfade müssen saubere, getrennte Checkouts eines festen Commits sein; ein Branch-Checkout wird abgelehnt. Während der Messung dürfen diese Checkouts nicht verändert oder durch andere Prozesse verwendet werden. Ihre normalisierte Origin-Identität muss mit der jeweils ausdrücklich angegebenen Repository-Identität übereinstimmen. nucli ermittelt Repository und Commit vor dem Lauf selbst und bindet nach dem letzten Snapshot einen zweiten sauberen Stand. Diese Vor-/Nachprüfung erkennt keine zwischenzeitliche Änderung, die vor der Abschlussprüfung vollständig zurückgenommen wurde; deshalb ist der feste, exklusiv verwendete Commit-Checkout eine Voraussetzung. Die Profilversion stammt aus der strikt gelesenen JSON-Datei; ihr Inhalt wird über einen SHA-256-Digest gebunden.

Das Messintervall muss mindestens fünf Sekunden betragen. Ein Fenster ist auf 24 Stunden und 20.000 Samples begrenzt. Über den gesamten Lauf werden höchstens 4.096 verschiedene HTTP-Serienidentitäten akzeptiert, einschließlich bereits verschwundener Serien. Wird eine dieser Grenzen überschritten, bricht die Messung ab, statt unvollständige Werte zu verdichten.

Der Bericht enthält die HTTP-Auswertung, gesampelte Pool-Maxima, Deltas der Pool-Wartezähler sowie Maxima und Deltas der registrierten Queues. Dazu kommen Anzahl, Durchschnitt und P95 der Queue-Verarbeitungsdauer. Fehlt in einem Snapshot ein Pflichtsignal oder wurde kein Anwendungsverkehr außerhalb des Metrikabrufs beobachtet, lautet der Status incomplete; unknown nennt die Lücke.

Der technische Bericht im Schema nucleus-capacity-sample/v2 bleibt bei Operations. Er enthält Messwerte, Provenienz, Vollständigkeitsstatus und unbekannte Pflichtwerte, aber keine freigegebenen Guardrails und keine Bestanden-/Nicht-bestanden-Entscheidung. Ein späterer Producer für den Commercial-Vertrag handoff/v1 darf nur freigegebene Aggregate übernehmen; Rohsamples und Mandantenkennungen gehören nicht in diese Übergabe. Dieser Producer sowie die Freigabe von Lastprofilen und Guardrails sind noch nicht Teil dieses Werkzeugs.

Erst ein nachgelagerter, freigegebener Validator kann entscheiden, ob alle Pflichtwerte ihre Guardrails erfüllen. unknown darf dabei nie als Erfolg gelten. Als sichere technische Dichte dürfen höchstens 70 Prozent der letzten vollständig bestandenen Stufe angesetzt werden. Commercial erhält nur den aggregierten, revisionsgebundenen Nachweis aus mindestens zehn synthetischen Mandanten, keine Rohserien oder Mandantenkennungen. Preise, Pakete und SLA-Grenzen werden daraus nicht automatisch abgeleitet.

Weitere allgemeine Diagnosewege finden Sie unter Diagnose und Readiness.