InsForge Debug

Was macht InsForge Debug?

Diagnostiziere Probleme in InsForge-Projekten durch Kombination der Observability-Primitiven des Backends – Logs, Metriken, DB-Gesundheit, Advisor, Policies, Metadaten, Fehlerobjekte, Bereitstellungsstatus und KI-Assistenz. Dieser Skill bietet:

1. Eine Referenz pro Debug-Primitiv (eine Beobachtungsoberfläche – unter references/)
2. Symptom-Rezepte (unten), die die Primitive-Sequenz für bekannte reaktive Symptome und proaktive Audits benennen

Verwende immer npx -y @insforge/cli – installiere die CLI niemals global.

Schnellster Weg: KI-unterstützte Triage

Wenn der Benutzer eine konkrete Beschreibung (Fehlermeldung, fehlschlagende URL, HTTP-Status) angibt, übergib sie an den InsForge-Debug-Agenten. Anders als die anderen Primitiven liefert dieser Vorschläge, nicht nur Beobachtungen – überprüfe die Diagnose gegen die von ihm zitierten Primitiven, bevor du darauf handelst.

npx -y @insforge/cli diagnose --ai "<Problembeschreibung>"

Siehe references/ai-assisted.md für die Entscheidung, wann dieser zuerst verwendet werden sollte, wann nicht und wie die Ausgabe zu überprüfen ist.

Debug-Primitiven

Jedes Primitiv ist eine unabhängig abfragbare Beobachtungsoberfläche, die auf einer eigenen Datenquelle basiert. Echte Diagnosen sind Zusammensetzungen von Primitiven.

Alle Befehle werden über npx -y @insforge/cli ... ausgeführt. Der neben jedem Primitiv angezeigte (Befehl) ist der tatsächliche CLI-Befehl – die Primitiv-Namen sind Konzeptbezeichnungen, keine CLI-Unterbefehlnamen (z. B. ist „DB-Gesundheit" diagnose db, nicht diagnose db-health; „Policies" ist db policies, nicht diagnose policies).

Primitiv (Befehl)	Was du siehst	Referenz
Logs (logs <quelle>; diagnose logs für quellenübergreifende Aggregation)	Zeitstrahl von Ereignissen aus 5 Backend-Quellen (insforge.logs / postgREST.logs / postgres.logs / function.logs / function-deploy.logs)	references/logs.md
Metriken (diagnose metrics)	EC2-Instanz-Zeitreihen (CPU / Arbeitsspeicher / Festplatte / Netzwerk) über 1h / 6h / 24h / 7d	references/metrics.md
DB-Gesundheit (diagnose db)	Aktueller Postgres-Zustand über 7 benannte Prüfungen (connections / slow-queries / bloat / size / index-usage / locks / cache-hit)	references/db-health.md
Advisor (diagnose advisor --json)	Statisch gescannte Probleme in 3 Kategorien (security / performance / health) mit ruleId / affectedObject / recommendation	references/advisor.md
Policies (db policies)	Aktive RLS-Regeln aus pg_policies (USING / WITH CHECK pro Befehl pro Rolle) – gibt alle Policies als Dump zurück	references/policies.md
Metadaten (metadata --json)	Deklarativer Backend-Zustandsdump (Auth-Konfiguration / Tabellen / Buckets / Funktionen / KI-Modelle / Realtime-Kanäle)	references/metadata.md
Fehlerobjekte (kein Befehl – lies SDK / HTTP-Antwort)	SDK-Fehlerhülle + HTTP-Status – die Routingtabelle von einem clientseitigen Fehler zur richtigen Logquelle	references/error-objects.md
Bereitstellungsstatus (deployments list + deployments status <id> --json + logs function-deploy.logs)	Frontend (Vercel) Bereitstellungsverlauf + Metadaten pro Bereitstellung sowie Edge-Function-Bereitstellungslogs	references/deploy-state.md
KI-Assistenz (diagnose --ai "<Beschreibung>")	LLM-Agent, der die anderen Primitiven kombiniert – gibt eine Diagnose mit Vorschlägen zurück	references/ai-assisted.md

Symptom-Rezepte

Jedes Rezept ist eine Primitive-Aufrufsequenz mit einer einzeiligen „Suche nach X"-Anweisung pro Schritt. Befehlssyntax, Flags und tiefere Interpretation findest du in den referenzierten Dokumenten pro Primitiv.

Rezept: SDK hat { data: null, error: { code, message } } zurückgegeben

1. Fehlerobjekte – lies code/message/details. Wenn der Code mit PGRST* beginnt, leite anhand der Tabelle in der Referenz über das Präfix weiter.
2. Logs (passende Quelle gemäß Fehlerobjekte-Routing) – finde den Fehlerzeitstempel, erhalte den vollständigen Backend-Kontext.
3. DB-Gesundheit (connections, locks, slow-queries) – nur wenn der Fehler auf ein DB-Problem hindeutet (PostgREST-Timeout, Sperrkonflikt).

Rezept: HTTP-4xx/5xx-Antwort auf eine bestimmte Anfrage

1. Fehlerobjekte – verwende die HTTP-Status-Routingtabelle, um die Logquelle auszuwählen (jeder Status hat einen eigenen Pfad; 429 ist speziell).
2. Logs (richtige Quelle für diesen Status) – finde die fehlschlagende Anforderungszeile und den Fehler.
3. Metriken – nur bei 5xx-Mustern, die mehrere Endpunkte betreffen, um ein systemweites Lastproblem zu bestätigen.

Rezept: RLS-Zugriffsproblem (403 bei Schreibzugriff oder leeres Ergebnis bei Lesezugriff)

Gleicher Fehler, zwei Erscheinungsformen. Schreibzugriffe (INSERT / UPDATE / DELETE) schlagen lautstark mit 403 fehl. Lesezugriffe (SELECT) schlagen leise mit einem leeren Array fehl – PostgREST filtert verweigerte Zeilen heraus, anstatt 403 zurückzugeben, sodass die Anfrage mit null Zeilen erfolgreich erscheint. Der Diagnosepfad ist derselbe, außer dass Schritt 1 nur für die 403-Variante gilt.

1. Logs (postgREST.logs) – nur 403-Variante: finde das Policy-Verletzungsereignis mit Tabellen- und Rollenkontext. Leeres-Ergebnis-Variante: überspringen – für still gefilterte Zeilen wird kein Fehler protokolliert.
2. Policies – liste die Policies für diese Tabelle auf; vergleiche USING / WITH CHECK mit der tatsächlichen Anfrage und dem verwendeten JWT-Anspruch.
3. Metadaten – überprüfe die Auth-Konfiguration (welcher Anspruch speist auth.uid() / requesting_user_id(); bei Drittanbieter-Auth wie Clerk/Auth0, ist der Anbieter als JWT-Aussteller registriert?).
4. DB-Abfrage (db query "<sql>") – nur Leeres-Ergebnis-Variante: bestätige, dass Zeilen, die sichtbar sein sollten, tatsächlich existieren, indem du als Service-Rolle (nicht als Benutzer) abfragst: npx -y @insforge/cli db query "SELECT id, user_id FROM <tabelle>". Unterscheidet zwischen „RLS hat alles herausgefiltert" und „es existieren keine passenden Daten".

Rezept: Login schlägt fehl / OAuth-Callback-Fehler / Token abgelaufen

1. Logs (insforge.logs) – finde Auth-Fehler mit Zeitstempel und Anbieterkontext.
2. Metadaten – überprüfe, ob der Anbieter aktiviert ist und die Weiterleitungs-URLs genau der Callback-URL entsprechen (Protokoll + Host + Pfad).

Rezept: Edge-Function-Laufzeitfehler / Timeout

1. Logs (function.logs) – erhalte den Fehler-Stack und den Ausführungskontext.
2. Metadaten – bestätige, dass die Funktion existiert und status: "active" ist.
3. (Falls nötig) npx -y @insforge/cli functions code <slug> – überprüfe den Quellcode auf offensichtliche Probleme.

Rezept: functions deploy fehlgeschlagen

1. Bereitstellungsstatus (function-deploy.logs) – finde den Build-/Push-Fehler.
2. Metadaten – bestätige, ob die Funktion in der aktiven Liste gelandet ist (Erkennung von Teilbereitstellungen).

Rezept: deployments deploy fehlgeschlagen (Vercel)

1. Bereitstellungsstatus (deployments list + status <id> --json) – lies status, metadata.webhookEventType und envVarKeys.
2. Lokal npm run build – reproduziere denselben Fehler lokal für schnellere Iteration.

Rezept: Einzelne langsame Abfrage / ein Endpunkt ist langsam

1. Logs (postgres.logs) – finde den Abfragetext und den Zeitstempel.
2. DB-Gesundheit (slow-queries, index-usage) – slow-queries erfasst sie nur, während sie noch läuft (>5s-Schnappschuss); überprüfe index-usage auf einen fehlenden Index. Bereits beendet? Advisor (--category performance --json) enthält den pg_stat_statements-Text + die mittlere Zeit; Schritt 1 hat den Zeitstempel.
3. Policies – wenn es sich um eine RLS-geschützte Tabelle handelt, überprüfe, ob die Policy keine versteckten Joins hinzufügt.

Rezept: „Arbeitsspeicher liegt bei ~80%, aber nichts ist langsam"

1. Erwartet – sag das zuerst. Eine dedizierte Postgres-Instanz wandelt freien RAM in Shared Buffers und Page Cache um; ständig hoher Speicherverbrauch bei wenig Verkehr ist ihr gesunder Zustand, kein Leck (references/metrics.md, „Speicher: hoch ist normal").
2. Metriken (--range 24h) – nur ein steigender Trend oder OOM-Kills/Neustarts ändern die Antwort. OOM-Hinweise finden sich in postgres.logs als die Absturz-Wiederherstellungs-Nachwirkungen („terminating connection because of crash of another server process" / „automatic recovery in progress").
3. Bei OOM-Hinweisen ist die Lösung Spielraum: Upgrade auf einen kostenpflichtigen Plan und wähle eine größere Instanzgröße (Dashboard → Project Settings → Compute & Disk). OOM auf den kleinsten Instanzen unter realer Last ist häufig und erwartet – niemals „Neustart, um Speicher freizugeben".

Rezept: Alle Antworten langsam / hohe CPU-/Speicherauslastung (aktiver Vorfall)

1. Metriken (--range 1h) – bestätige systemweiten Druck (CPU / Arbeitsspeicher / Festplatte).
2. DB-Gesundheit – DB ist der häufigste Engpass; überprüfe connections, locks, slow-queries.
3. Logs (diagnose logs Aggregat) – Fehlermuster über Quellen hinweg zum Zeitpunkt des Anstiegs.
4. Advisor (--severity critical) – bereits bestehende bekannte Probleme, die die Verschlechterung erklären können.

Rezept: Realtime-Kanal verbindet nicht / Nachrichten fehlen

1. Logs (insforge.logs) – WebSocket-Fehler und Abonnementfehler.
2. Metadaten – überprüfe, ob das Kanalmuster mit dem übereinstimmt, was der Client abonniert, enabled: true.
3. Policies – RLS auf der zugrunde liegenden Tabelle (Realtime liefert Zeilenänderungen; RLS steuert, welche Zeilen der Abonnent sieht).

Rezept: 429-Ratenbegrenzung

1. Fehlerobjekte – bestätige 429-Status. Für 429er werden keine Logs aufgezeichnet; es wird kein Retry-After-Header zurückgegeben. Verschwende keine Zeit mit der Log-Suche.
2. Metriken (--range 1h) – allgemeiner Backend-Lastkontext.
3. Die Lösung ist immer clientseitig: Entprellen, Bündeln, exponentielles Backoff, Wiederholungsschleifen eliminieren.

Rezept: Gateway-Timeout (502 / 503 / 504) auf eine bestimmte URL

Leite nach URL-Subsystem weiter, bevor du tiefer gräbst:

URL-Muster	Vertiefung in
/api/database/records/...	Logs (postgREST.logs → postgres.logs) + DB-Gesundheit (locks, slow-queries)
/functions/<slug>	Logs (function.logs) – Funktion könnte sich im Crash-Loop befinden
/api/auth/...	Logs (insforge.logs)
Beliebigter Pfad während systemweitem Anstieg	Metriken (--range 1h)

504er über nicht verwandte Pfade auf einer kleinen Instanz: Verdacht auf OOM zuerst. Intermittierende Gateway-Timeouts, die Datenbank, Authentifizierung und Funktionen gleichermaßen treffen, sind die klassische Out-of-Memory-Signatur auf den kleinsten Instanzgrößen: Der Kernel tötet Postgres, jede laufende Anfrage timeoutet am Gateway, während die Crash-Wiederherstellung läuft, und wiederholt sich beim nächsten Lastanstieg.

Schnellster Weg: npx -y @insforge/cli diagnose incident (Plattform-Login erforderlich). Der Bericht wird vollständig auf der Cloud-Seite erstellt – Prometheus-Scrape-Verlauf, Plattformaufzeichnungen, eine ausgehende Datenbankabfrage – funktioniert also selbst wenn die Instanz ausgefallen oder blockiert ist, genau dann, wenn diagnose logs keine Antwort mehr gibt. Er gibt ein Urteil zurück (oom_likely, platform_operation_in_progress, paused_or_suspended, metrics_stopped, down_unknown, no_incident_detected) mit den Beweisen und der empfohlenen Maßnahme; oom_likely bedeutet bereits, dass die Neustart-/Speicherkorrelationsprüfungen unten auf der Plattformseite bestanden wurden.

Wenn der Befehl nicht verfügbar ist (ältere CLI/Backend, --api-key-Link-Modus), bestätige manuell in den Logs (postgres.logs) über die Absturz-Wiederherstellungs-Nachwirkungen – „terminating connection because of crash of another server process" / „automatic recovery in progress" – zeitkorreliert mit dem 5xx-Ausbruch: Ein Wiederherstellungsnachweis allein beweist nur einen unsauberen Postgres-Neustart, daher müssen die Zeitstempel übereinstimmen, bevor OOM zur Hauptdiagnose wird (references/metrics.md). Mit diesen Beweisen ist die Lösung Spielraum, keine Wiederholungsschleife:

1. Instanz upgraden – npx -y @insforge/cli projects upgrade-instance <typ> (nano → micro → small → medium → large → xl), oder Dashboard → Project Settings → Compute & Disk. Im kostenlosen Plan zuerst auf einen kostenpflichtigen Plan upgraden, dann die Größe wählen. Die Größenänderung ändert die Rechnung und die CLI fragt nach interaktiver Bestätigung – hole zuerst die Zustimmung des Benutzers ein, führe dann unbeaufsichtigt mit dem CLI-eigenen --yes aus (das -y in npx -y ist npm's Installationsflag, nicht die Bestätigungsüberspringung). Die Größenänderung ist asynchron – frage projects get ab, bis operation_status gelöscht ist, bevor du den Vorfall als behoben erklärst.
2. Die Größenänderung startet das Projekt als Teil der Änderung neu, was auch jeden blockierten Zustand bereinigt – es gibt keinen separaten benutzerseitigen Neustart, und ein bloßer Neustart würde nur Minuten vor dem nächsten OOM-Anstieg kaufen. OOM unter realer Last auf den kleinsten Größen ist häufig und erwartet, kein Fehler.

Rezept: Vor dem Start / proaktives Audit

Erfordert Plattform-Login (npx -y @insforge/cli login). Nicht verfügbar, wenn das Projekt über --api-key verbunden ist – falle in diesem Fall auf db-health + policies + metadata für ein manuelles Audit zurück.

1. Advisor – vollständiger Scan, dann zuerst --severity critical, dann Warnungen.
2. Advisor (--category security) – fokussiere auf Sicherheitsprobleme; kreuzverifiziere mit Policies (RLS-Abdeckung) und Metadaten (Auth-Konfiguration, öffentliche Buckets, Secret-Vorhandensein).
3. Advisor (--category performance) – kreuzverifiziere mit DB-Gesundheit (slow-queries, index-usage, bloat).
4. Advisor (--category health) – kreuzverifiziere mit Metriken (Ressourcentrends über 7d).
5. Nach Korrekturen führe Advisor erneut aus und bestätige isResolved: true für jede behandelte ruleId.

Rezept: Keine Ahnung, wo anfangen

1. KI-unterstützt (diagnose --ai "<Fehler oder URL>") – erhalte eine erste Hypothese.
2. Überprüfe durch erneutes Überprüfen der Primitiven, die die Diagnose nennt. Vertraue den Primitive-Beobachtungen mehr als dem Vorschlag.

Wenn die Ursache InsForge selbst ist

Manche Diagnosen enden bei einem InsForge-seitigen Defekt, nicht bei einer Projektfehlkonfiguration: ein Plattform-Bug oder eine Regression, ein SDK-Aufruf, der sich falsch verhält, eine Dokumentation oder ein Skill, der dem beobachteten Verhalten widerspricht, oder eine fehlende Fähigkeit. Eine Debug-Sitzung ist genau der Ort, an dem diese bestätigt werden – melde sie, solange die Beweise vorliegen:

npx -y @insforge/cli feedback --json \
  --type bug --component backend --area db \
  --title "<einzeilige Zusammenfassung>" \
  --detail "<was passiert ist vs. erwartet, minimale Reproduktion>" \
  --command "<der fehlschlagende Aufruf>" \
  --error "<wörtlicher Fehler aus Logs>"