Diagnose API

ENTWURF — Nur für interne Entwicklerteams

Diese API-Referenz ist für interne Entwicklerteams bestimmt.

Übersicht

Was es ist: Die Diagnose-API bietet Profiling- und Laufzeitstatistik-Endpunkte für Leistungsanalyse und Fehlerbehebung. Der primäre Endpunkt erzeugt Go-pprof-Profile von laufenden Grid-Modulen.

Quelle: src/grid/client/rest.go

Authentifizierung

Alle Endpunkte erfordern JWT-Cookie- oder API-Token-Authentifizierung.

Endpunkte

Methode	Pfad	Beschreibung	Authentifizierung erforderlich
POST	/internal/v1/pprof	Einen Profiling-Snapshot für ein Grid-Modul erzeugen	JWT + API-Token

---

POST /internal/v1/pprof

Ein Go-pprof-Profil von einem laufenden Grid-Modul erzeugen. Die Antwort ist eine gzip-komprimierte binäre Profildatei, die mit Standard-Go-Profiling-Tools analysiert werden kann.

Anfrage:

POST /internal/v1/pprof
Content-Type: application/json
Authorization: Bearer <token>

{
  "client": "node-uuid",
  "module": "grid.client",
  "profile": "cpu"
}

Anfragefelder:

Feld	Typ	Erforderlich	Beschreibung
client	string	Ja	Grid-Client-Knoten-ID für das Profiling
module	string	Nein	Modulname (Standard: grid.client)
profile	string	Ja	Zu erfassender Profiltyp

Verfügbare Profiltypen:

Profil	Beschreibung
cpu	CPU-Nutzungsprofil (30-Sekunden-Stichprobe)
allocs	Speicherallokationsprofil
heap	Heap-Speicherprofil
goroutine	Goroutine-Stack-Traces
block	Blockierungsprofil
mutex	Mutex-Konfliktprofil
threadcreate	Thread-Erstellungsprofil

Antwort (200): Binäre gzip-komprimierte pprof-Daten.

Antwortheader:

Header	Wert
Content-Disposition	attachment; filename=hydden-{profile}-{timestamp}.out
Content-Type	application/octet-stream

Verwendung mit Go-Tools:

# Profil herunterladen
curl -X POST "https://portal/internal/v1/pprof" \
  -H "Authorization: Bearer <token>" \
  -d '{"client":"node-uuid","profile":"cpu"}' \
  -o cpu.out

# Mit pprof analysieren
go tool pprof cpu.out

---

Grid-Laufzeitstatistiken (nur gRPC)

Das Grid-Modul stellt auch Laufzeitstatistiken über gRPC bereit (keine REST-Oberfläche). Diese sind in src/grid/api/grid_api.proto definiert:

Verfügbar über gRPC:

Nachricht	Felder	Beschreibung
Stats	nID, disk, version, error, runtime, component, uptime	Knoten-Laufzeitstatistiken
DiskStats	total, free	Festplattennutzungsstatistiken
Runtime	version, maxProcs, arch, oS, env	Go-Laufzeitinformationen

Diese Statistiken werden intern von der Grid-Cluster-Verwaltungsschicht verwendet und sind nicht über REST verfügbar.

---

Fehlerantworten

Status	Beschreibung
400	Ungültiger Anfragekörper oder unbekannter Profiltyp
403	Authentifizierung fehlgeschlagen oder unzureichende Berechtigungen
404	Zielknoten nicht gefunden oder offline
500	Profiling fehlgeschlagen (Zielmodul nicht erreichbar)

Verwandte Themen

• Dashboard-Widgets API — Systemressourcen-Metriken (CPU, Speicher, Festplatte)
• Audit API — Audit-Protokolle und Metriken