Monitoring

CodeCourier bietet umfassende Monitoring-Tools zur Verfolgung der Workflow-Ausführung, Sandbox-Gesundheit und systemweiten Leistung. Alle Monitoring-Daten werden von reaktiven Convex-Abfragen gespeist, sodass das Dashboard ohne Polling in Echtzeit aktualisiert wird. Diese Anleitung beschreibt die Monitoring-Oberflächen, die Daten, die sie offenlegen, und wie Sie sie effektiv nutzen.

Verfolgung des Run-Status

Run-Listen-Dashboard

Die Runs-Seite ist die primäre Monitoring-Oberfläche. Sie zeigt eine paginierte Liste aller Runs des aktuellen Projekts, sortiert nach Erstellungszeit (neueste zuerst). Jede Zeile zeigt:

• Status-Badge - Farblich codierter Indikator, der pending (grau), running (blau), completed (grün), failed (rot) oder cancelled (bernstein) anzeigt.
• Run-Name - Automatisch generierter oder vom Nutzer vergebener Name.
• Quelle - Woher der Run stammt: Workflow, Sprint, Sandbox oder Merge-Agent.
• Prompt-Vorschau - Die ersten paar Zeilen der Aufgaben- Beschreibung.
• Zeitangaben - Erstellungszeit und Dauer (falls abgeschlossen).
• PR-Status - Ob ein Pull-Request erstellt, gemergt oder fehlgeschlagen wurde.

Run-Detailansicht

Ein Klick auf einen Run öffnet dessen Detailseite mit umfassenden Ausführungsinformationen:

• Schritt-Zeitleiste - Eine visuelle Darstellung jedes Schritts in der Pipeline, mit Rolle (Designer, Checker, Evaluator usw.), verwendetem CLI-Tool und Modell, Status und Dauer. Schritte werden in Ausführungsreihenfolge mit Iterations- Nummern angezeigt.
• Sandbox-Ausgabe - Die Terminal-Ausgabe jeder Sandbox des Schritts, einschließlich KI-Agenten-Antworten, Tool-Use-Ereignissen und Fehlermeldungen. Die Ausgabe wird in Echtzeit aktualisiert, während der Schritt läuft.
• Checker-Urteile - Für Checker-Schritte werden das Pass/Fail-Urteil und der Feedback-Text inline in der Zeitleiste angezeigt.
• Qualitäts-Scores - Für Evaluator-Schritte werden die Aufschlüsselung in fünf Qualitätsdimensionen und der Composite-Score inline angezeigt. Ein Schwellenwert-Indikator zeigt, ob der Composite- Score den konfigurierten Schwellenwert erfüllt.
• CI-Check-Status - Der aggregierte CI-Status (passing, failing, pending) und die einzelnen Check-Ergebnisse mit Links zu GitHub.
• Konfiguration - Die Sandbox-Konfiguration des Runs, Prompt, Referenzbilder und Metadaten.
• Fehlerdetails - Wenn der Run fehlgeschlagen ist, die Fehler- Meldung und der Schritt, in dem der Fehler aufgetreten ist.

Monitoring der Qualitäts-Scores

Qualitäts-Scores bieten eine quantitative Sicht darauf, wie gut jeder Workflow-Run definierte Qualitätskriterien erfüllt. Sie werden von Evaluator-Schritten erzeugt und auf zwei Ebenen sichtbar gemacht:

• Run-Ebene - Das Feld qualityScoreim Run-Datensatz hält den Composite-Score (0–100), der über alle Evaluator-Schritte der Pipeline aggregiert ist. Er ist in der Run-Liste als Score-Badge sichtbar und ermöglicht einen schnellen Qualitätsvergleich zwischen Runs.
• Schritt-Ebene - Einzelne Evaluator-Run-Schritt- Datensätze tragen die vollständige qualityScores-Aufschlüsselung über alle fünf Dimensionen.

Qualitätsdimensionen interpretieren

qualityScores: {
  correctness: number,       // 0-100: Does the implementation meet requirements?
  typeSafety: number,        // 0-100: Are TypeScript types correct and non-coercive?
  codeStyle: number,         // 0-100: Does code follow project conventions?
  testCoverage: number,      // 0-100: Are changes covered by meaningful tests?
  completeness: number,      // 0-100: Is the implementation fully finished, not stubbed?
  composite: number,         // 0-100: Weighted average of all five dimensions
  thresholdResult: boolean,  // True if composite >= configured threshold
}

Jede Dimension wird unabhängig von 0 (Kriterien nicht erfüllt) bis 100 (Kriterien vollständig erfüllt) bewertet. Der composite-Score ist ein gewichteter Durchschnitt - Sie können die Gewichte auf der Evaluator- Persona konfigurieren, um die für Ihr Projekt wichtigsten Dimensionen zu betonen. Der thresholdResult-Boolean ist das aussagekräftigste Signal: Ein false-Wert bedeutet, dass die Implementierung Ihre Qualitätshürde nicht erreicht hat und eine weitere Iteration rechtfertigen kann.

Qualitätstrends

Der Workflow-Analytics-Bereich zeigt Trends der Qualitäts-Scores über die Zeit für einen bestimmten Workflow. Das Verfolgen des Composite-Scores über Runs hinweg zeigt, ob Ihre Pipeline konstant hochwertige Ergebnisse erzeugt oder eine Qualitätsverschlechterung über die Zeit aufweist (was häufig signalisiert, dass Persona- Anweisungen verfeinert werden müssen oder der Workflow einen zusätzlichen Verbesserungslauf benötigt).

Monitoring der CI-Checks

Nachdem ein Run einen Pull-Request erzeugt, überwacht CodeCourier den Status der CI-Checks für diesen PR und zeigt ihn in der Monitoring-UI an.

CI-Status in der Run-Liste

Die Runs-Liste zeigt einen CI-Status-Indikator neben dem PR-Status für jeden Run. Der aggregierte Status ("passing", "failing" oder "pending") wird als farbiges Badge angezeigt. Runs mit prStatus = "blocked_on_ci" werden hervorgehoben, um zu signalisieren, dass der PR nicht gemergt werden kann, bis die CI durchläuft.

Details einzelner Checks

Die Run-Detailansicht listet jeden einzelnen CI-Check mit Name, Status und direktem Link zum Check-Lauf auf GitHub. So können Sie direkt von einem fehlgeschlagenen CodeCourier-Run zur spezifischen CI-Job-Ausgabe navigieren, was die Zeit zur Fehlerdiagnose reduziert.

ciChecks: {
  status: "passing" | "failing" | "pending",
  checks: Array<{
    name: string,      // e.g., "Build", "Unit Tests", "Lint", "E2E Tests"
    status: string,    // Per-check status from GitHub
    url: string,       // Direct link to the check run
  }>,
  checkedAt: number,   // Timestamp of last GitHub poll
}

Monitoring von Sprint Chains

Sprint Chains erscheinen in den Monitoring-Oberflächen mit zusätzlichem Kontext gegenüber einzelnen Runs.

Sprint Chain in der Runs-Liste

Einzelne Sprint-Runs erscheinen in der Runs-Liste mit Quelle sprint. Der Run-Name enthält die Sprint-Nummer (z. B. "Sprint 2 von 5 - Feature X"), sodass Sie jede Phase auf einen Blick verfolgen können. Sie können die Runs-Liste nach Quelle filtern, um nur Sprint-Runs anzuzeigen.

Sprint-Chain-Detailansicht

Die Sprint-Chain-Detailansicht bietet eine konsolidierte Sicht auf die gesamte Chain:

• Chain-Status - Der Gesamtstatus der Chain (pending, running, completed, failed oder cancelled).
• Sprint-Fortschritt- Aktueller Sprint-Index und Gesamt-Sprint-Anzahl (z. B. "3 von 5 Sprints abgeschlossen").
• PR-URLs pro Sprint - Das Array sprintPrUrls wird als klickbare Liste angezeigt, ein Eintrag pro Sprint. Abgeschlossene Sprints zeigen ihre PR-URL; zukünftige Sprints werden als ausstehend angezeigt.
• Sprint-Zeitleiste - Eine Zeitleiste von Sprint- Ausführungen mit Start- und Endzeiten, was den Dauer-Vergleich über Sprints hinweg ermöglicht.

Trigger.dev-Run-Status

Zusätzlich zum Tracking auf Convex-Ebene verknüpft CodeCourier jeden Run mit seiner entsprechenden Trigger.dev-Task-Ausführung. Das Feld triggerRunId im Run-Datensatz bietet Rückverfolgbarkeit zum Trigger.dev-Dashboard, wo Sie inspizieren können:

• Position in der Task-Queue und Scheduling.
• Ausführungs-Logs auf Infrastrukturebene.
• Retry-Verlauf (falls der Task wiederholt wurde).
• Ressourcenverbrauch und Timing.

Dieses zweistufige Tracking (Convex + Trigger.dev) stellt sicher, dass Sie sowohl Probleme auf Anwendungsebene (falscher Prompt, Checker-Feedback) als auch Probleme auf Infrastrukturebene (Timeout, OOM, Netzwerkfehler) debuggen können.

Sandbox-Monitoring

Zähler aktiver Sandboxes

Das Projekt-Dashboard zeigt einen Zähler aktiver Sandboxes - die Anzahl der Sandboxes, die sich aktuell im Zustand running befinden. Dieser Zähler ist in der Tabelle projectCounters denormalisiert und wird in Echtzeit aktualisiert, sobald Sandboxes starten und stoppen.

Sandbox-Liste

Die Sandboxes-Seite zeigt alle Sandboxes des Projekts (ohne diejenigen, die von Workflows und Issue-Sessions erstellt wurden). Jeder Eintrag zeigt den Sandbox-Status, die Konfiguration, die Erstellungszeit und verknüpfte PR-Informationen.

Streaming-Terminal

Für einzelne Sandboxes liefert die Streaming-Terminal-Komponente Echtzeit-Ausgabe des KI-Agenten. Das Terminal rendert:

• Assistant-Nachrichten mit formatiertem Text.
• Tool-Use-Ereignisse (Dateischreibvorgänge, Befehlsausführung).
• Interaktiv gesendete Nutzer-Nachrichten.
• Statusindikatoren für Streaming-, Completed- und Error-Zustände.

Metriken auf Projektebene

Projekt-Zähler

CodeCourier verwaltet denormalisierte Zähler für jedes Projekt:

• Sandboxes gesamt - Lebenslange Anzahl erstellter Sandboxes.
• Aktive Sandboxes - Aktuell laufende Sandboxes.
• Runs gesamt - Lebenslange Anzahl an Workflow-Runs.
• Abgeschlossene Runs - Erfolgreich beendete Runs.
• Fehlgeschlagene Runs - Runs, die mit einem Fehler endeten.
• Workflows gesamt - Anzahl der Workflow-Blaupausen.
• Mitglieder gesamt - Teammitglieder im Projekt.
• Ausstehende Einladungen - Nicht angenommene Mitglieder-Einladungen.

Diese Zähler werden auf der Projekt-Übersichtsseite angezeigt und aktualisieren sich reaktiv.

Tagesstatistiken

Die Tabelle dailyStats verfolgt tägliche Metriken:

• Erstellte Sandboxes.
• Erstellte, abgeschlossene und fehlgeschlagene Runs.
• Gesamtzahl der Iterationen über alle Runs.
• Erstellte Workflows.

Diese Daten speisen historische Diagramme und Trendanalysen im Projekt- Dashboard.

Nutzungs- und Kostenverfolgung

Jede Sandbox-Session und jeder Workflow-Schritt erzeugt Nutzungsdatensätze in der Tabelle usageRecords. Diese Datensätze bieten detaillierte Kostentransparenz:

{
  service: "anthropic",     // or "openai", "openrouter", "e2b", "trigger_dev"
  date: "2026-03-15",       // ISO date
  quantity: 15000,          // tokens consumed
  unit: "output_tokens",    // what was measured
  costUsd: 0.45,            // calculated cost
  toolId: "claude",         // CLI tool used
  modelId: "claude-opus-4-6", // specific model
  stepType: "designer",     // step role
  inputTokens: 12000,       // detailed token breakdown
  outputTokens: 15000,
  durationMs: 45000,        // step duration
}

Nutzungsdatensätze sind mit konkreten Runs, Sandboxes, Chains und Issue-Sessions verknüpft. So können Sie Kosten auf jeder Ebene verfolgen - von einzelnen Schritten bis zu ganzen Work Chains.

Benachrichtigungen

CodeCourier sendet Benachrichtigungen für wichtige Ereignisse. Die Tabellenotifications speichert nutzer-spezifische Benachrichtigungen mit folgenden Typen:

• run_completed - Ein Workflow-Run wurde erfolgreich beendet.
• run_failed - Ein Workflow-Run ist fehlgeschlagen.
• pr_created - Ein Pull-Request wurde erstellt.
• pr_merged - Ein Pull-Request wurde gemergt.
• pr_failed - Die PR-Erstellung ist fehlgeschlagen.
• member_joined - Ein neues Teammitglied ist dem Projekt beigetreten.
• workflow_completed - Alle Schritte in einem Workflow sind abgeschlossen.
• sprint_completed - Eine Sprint Chain wurde abgeschlossen.
• sprint_failed - Eine Sprint Chain ist fehlgeschlagen.

Benachrichtigungen werden im Dashboard angezeigt und können als gelesen markiert oder verworfen werden. Sie sind nach Projekt, Nutzer und Lesestatus für eine effiziente Abfrage indiziert.

Fehler-Monitoring

Fehler-Quellen

Fehler werden auf mehreren Ebenen erfasst:

• Sandbox-Fehler - Das Feld error in Sandbox-Datensätzen speichert E2B-Bereitstellungsfehler und Agent-Abstürze.
• Run-Fehler - Das Feld error in Run- Datensätzen speichert Fehler auf Pipeline-Ebene.
• Schritt-Fehler - Das Feld error in Run- Schritt-Datensätzen speichert schrittbezogene Fehler.
• PR-Fehler - Das Feld prError in Sandbox- und Run-Datensätzen speichert PR-Erstellungsfehler.
• Learning-Extraktions-Fehler - Das Feld learningExtractionError in Sandbox-Datensätzen.

Häufige Fehlermuster

• API-Schlüssel falsch konfiguriert - Fehlende oder ungültige Schlüssel für E2B, Anthropic oder GitHub. Prüfen Sie die Projekteinstellungen.
• Vorlage nicht gefunden - Die angegebene E2B-Vorlage existiert nicht. Verifizieren Sie die Vorlagen-ID in der Workflow-Konfiguration.
• Timeout überschritten - Die Sandbox lief länger als das konfigurierte Timeout. Erhöhen Sie das Timeout oder vereinfachen Sie die Aufgabe.
• Rate Limiting - Der KI-Anbieter hat Anfragen rate-limitiert. Warten Sie und versuchen Sie es erneut, oder wechseln Sie das Modell.
• Git-Push-Fehler - Die Sandbox konnte nicht auf das Remote pushen. Prüfen Sie, ob der GitHub-Token Schreibzugriff hat.

Workflow-Analytics

CodeCourier bietet Analytics-Abfragen zur Workflow-Leistung. Das Modul workflowAnalytics stellt Metriken wie folgende bereit:

• Runs pro Workflow (wie oft jede Blaupause verwendet wird).
• Erfolgsquote (abgeschlossene vs. fehlgeschlagene Runs).
• Durchschnittliche Iterationsanzahl (wie viele Schleifen vor dem Pass).
• Durchschnittliche Dauer (Zeit von Start bis Abschluss).

Diese Metriken helfen Ihnen zu identifizieren, welche Workflows effektiv sind und welche optimiert werden müssen - sei es durch Anpassung der Persona-Anweisungen, Wechsel der Modelle oder Umstrukturierung der Pipeline.