Monitoring

CodeCourier fornisce strumenti di monitoring completi per tracciare l’esecuzione dei workflow, la salute delle sandbox e le performance a livello di sistema. Tutti i dati di monitoring sono alimentati da query reattive Convex, il che significa che il dashboard si aggiorna in tempo reale senza polling. Questa guida copre le superfici di monitoring, i dati che espongono e come usarle efficacemente.

Tracciamento dello status dei run

Dashboard della lista dei run

La pagina Runs è la superficie di monitoring principale. Mostra una lista paginata di tutti i run del progetto attuale, ordinata per ora di creazione (i più recenti per primi). Ogni riga mostra:

• Badge di status - Indicatore con codice colore che mostra pending (grigio), running (blu), completed (verde), failed (rosso) o cancelled (ambra).
• Nome del run - Nome auto-generato o fornito dall’utente.
• Source - Da dove ha avuto origine il run: workflow, sprint, sandbox o merge agent.
• Anteprima del prompt - Prime righe della descrizione del task.
• Timing - Ora di creazione e durata (se completato).
• Status della PR - Se una pull request è stata creata, mergiata o è fallita.

Vista di dettaglio del run

Cliccare su un run apre la sua pagina di dettaglio con informazioni di esecuzione complete:

• Timeline degli step - Una rappresentazione visiva di ogni step della pipeline, che mostra il ruolo (designer, checker, evaluator, ecc.), lo strumento CLI e il modello usati, lo status e la durata. Gli step sono mostrati in ordine di esecuzione con i numeri di iterazione.
• Output della sandbox - L’output del terminale della sandbox di ogni step, incluse le risposte dell’agente IA, gli eventi di uso degli strumenti e i messaggi di errore. L’output si aggiorna in tempo reale mentre lo step è in esecuzione.
• Verdetti del checker - Per gli step checker, il verdetto pass/fail e il testo di feedback vengono mostrati inline nella timeline.
• Punteggi di qualità - Per gli step evaluator, la scomposizione dei punteggi di qualità su cinque dimensioni e il punteggio composite vengono mostrati inline. Un indicatore di soglia mostra se il punteggio composite soddisfa la soglia configurata.
• Status dei CI check - Lo status CI aggregato (passing, failing, pending) e i risultati dei singoli check con link a GitHub.
• Configurazione - La config di sandbox del run, il prompt, le immagini di riferimento e i metadati.
• Dettagli dell’errore - Se il run è fallito, il messaggio di errore e lo step in cui è avvenuto il fallimento.

Monitoring dei punteggi di qualità

I punteggi di qualità forniscono una vista quantitativa di quanto bene ogni workflow run soddisfa i criteri di qualità definiti. Sono prodotti dagli step Evaluator e portati in superficie a due livelli:

• Livello run - Il campo qualityScore del record del run contiene il punteggio composite (0-100) aggregato su tutti gli step evaluator della pipeline. È visibile nella lista dei Runs come badge di punteggio, abilitando un confronto di qualità a colpo d’occhio tra i run.
• Livello step - I singoli record di run step evaluator portano l’intera scomposizione qualityScores su tutte le cinque dimensioni.

Interpretare le dimensioni di qualità

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
}

Ogni dimensione è valutata indipendentemente da 0 (non soddisfa i criteri) a 100 (soddisfa pienamente i criteri). Il punteggio composite è una media pesata - puoi configurare i pesi sulla persona evaluator per enfatizzare le dimensioni più importanti per il tuo progetto. Il booleanothresholdResult è il segnale più attuabile: un valore false significa che l’implementazione non ha raggiunto la tua soglia di qualità e potrebbe giustificare un’ulteriore iterazione.

Trend di qualità

La sezione Workflow Analytics mostra i trend dei punteggi di qualità nel tempo per un dato workflow. Tracciare il punteggio composite attraverso i run rivela se la tua pipeline produce costantemente output di alta qualità o presenta una qualità in degrado nel tempo (il che spesso segnala che le istruzioni di persona hanno bisogno di raffinamento o che il workflow ha bisogno di un passaggio di miglioramento aggiuntivo).

Monitoring dei CI Check

Dopo che un run crea una pull request, CodeCourier monitora lo status dei CI check per quella PR e lo porta in superficie nell’interfaccia di monitoring.

Status CI nella lista dei run

La lista dei Runs mostra un indicatore di status CI accanto allo status della PR per ogni run. Lo status aggregato (« passing », « failing » o « pending ») è mostrato come badge colorato. I run con prStatus = "blocked_on_ci" vengono evidenziati per indicare che la PR non può essere mergiata finché la CI non si risolve.

Dettagli dei singoli check

La vista di dettaglio del run elenca ogni singolo CI check con il suo nome, status e un link diretto al check run su GitHub. Questo ti permette di navigare direttamente da un run CodeCourier fallito allo specifico output del job CI, riducendo il tempo speso a diagnosticare i fallimenti.

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 delle Sprint Chain

Le sprint chain appaiono nelle superfici di monitoring con contesto aggiuntivo rispetto ai run individuali.

Sprint chain nella lista dei run

I singoli run di sprint appaiono nella lista dei Runs con source sprint. Il nome del run include il numero di sprint (ad esempio, « Sprint 2 of 5 - Feature X ») così puoi tracciare ogni fase a colpo d’occhio. Puoi filtrare la lista dei Runs per source per mostrare solo i run originati da sprint.

Vista di dettaglio della sprint chain

La vista di dettaglio della sprint chain fornisce una vista consolidata dell’intera chain:

• Status della chain - Lo stato complessivo della chain (pending, running, completed, failed o cancelled).
• Avanzamento degli sprint- Indice di sprint attuale e conteggio totale degli sprint (ad esempio, « 3 of 5 sprints completed »).
• URL di PR per sprint - L’array sprintPrUrls mostrato come lista cliccabile, una voce per sprint. Gli sprint completati mostrano il loro URL di PR; gli sprint futuri appaiono come pending.
• Timeline degli sprint - Una timeline delle esecuzioni di sprint con orari di inizio e fine, abilitando il confronto delle durate tra sprint.

Status dei run Trigger.dev

Oltre al tracciamento a livello di Convex, CodeCourier collega ogni run alla sua corrispondente esecuzione di task Trigger.dev. Il campo triggerRunId del record del run fornisce tracciabilità verso il dashboard Trigger.dev dove puoi ispezionare:

• La posizione nella coda di task e la pianificazione.
• I log di esecuzione a livello di infrastruttura.
• La cronologia dei retry (se il task è stato riprovato).
• Il consumo di risorse e il timing.

Questo tracciamento a due livelli (Convex + Trigger.dev) garantisce che tu possa debuggare sia problemi a livello applicativo (prompt sbagliato, feedback del checker) sia problemi a livello di infrastruttura (timeout, OOM, guasto di rete).

Monitoring delle sandbox

Contatore delle sandbox attive

Il dashboard del progetto mostra un contatore delle sandbox attive - il numero di sandbox attualmente nello stato running. Questo contatore è denormalizzato nella tabella projectCounters e si aggiorna in tempo reale man mano che le sandbox partono e si fermano.

Lista delle sandbox

La pagina Sandboxes mostra tutte le sandbox del progetto (escluse quelle create da workflow e sessioni di issue). Ogni voce mostra lo status della sandbox, la configurazione, l’ora di creazione e le informazioni di PR collegate.

Terminale in streaming

Per le singole sandbox, il componente di terminale in streaming fornisce output in tempo reale dall’agente IA. Il terminale renderizza:

• I messaggi assistant con testo formattato.
• Gli eventi di uso degli strumenti (scritture di file, esecuzione di comandi).
• I messaggi user inviati interattivamente.
• Gli indicatori di status per gli stati streaming, completed ed error.

Metriche a livello di progetto

Contatori del progetto

CodeCourier mantiene contatori denormalizzati per ogni progetto:

• Totale delle sandbox - Conteggio a vita delle sandbox create.
• Sandbox attive - Sandbox attualmente in esecuzione.
• Totale dei run - Conteggio a vita dei workflow run.
• Run completati - Run conclusi con successo.
• Run falliti - Run che si sono conclusi in fallimento.
• Totale dei workflow - Numero di blueprint di workflow.
• Totale dei membri - Membri del team nel progetto.
• Inviti in sospeso - Inviti di membri non accettati.

Questi contatori sono mostrati nella pagina di panoramica del progetto e si aggiornano in modo reattivo.

Statistiche giornaliere

La tabella dailyStats traccia metriche per giorno:

• Sandbox create.
• Run creati, completati e falliti.
• Totale delle iterazioni su tutti i run.
• Workflow creati.

Questi dati alimentano i grafici storici e l’analisi dei trend nel dashboard del progetto.

Tracciamento dell’usage e del costo

Ogni sessione di sandbox e step di workflow genera record di usage nella tabella usageRecords. Questi record forniscono una visibilità di costo dettagliata:

{
  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
}

I record di usage sono collegati a run, sandbox, chain e sessioni di issue specifici. Questo ti permette di tracciare i costi a ogni livello - dai singoli step alle intere work chain.

Notifiche

CodeCourier invia notifiche per eventi importanti. La tabella notifications memorizza le notifiche per utente con i seguenti tipi:

• run_completed - Un workflow run si è concluso con successo.
• run_failed - Un workflow run è fallito.
• pr_created - Una pull request è stata creata.
• pr_merged - Una pull request è stata mergiata.
• pr_failed - La creazione di una pull request è fallita.
• member_joined - Un nuovo membro del team si è unito al progetto.
• workflow_completed - Tutti gli step di un workflow si sono conclusi.
• sprint_completed - Una sprint chain si è conclusa.
• sprint_failed - Una sprint chain è fallita.

Le notifiche sono mostrate nel dashboard e possono essere marcate come lette o rimosse. Sono indicizzate per progetto, utente e status di lettura per un querying efficiente.

Monitoring degli errori

Superfici di errore

Gli errori vengono catturati a più livelli:

• Errori di sandbox - Il campo error dei record di sandbox memorizza i fallimenti di provisioning E2B e i crash dell’agente.
• Errori di run - Il campo error dei record di run memorizza i fallimenti a livello di pipeline.
• Errori di step - Il campo error dei record di run step memorizza i fallimenti specifici degli step.
• Errori di PR - Il campo prError dei record di sandbox e run memorizza i fallimenti di creazione delle pull request.
• Errori di estrazione dei learning - Il campo learningExtractionError dei record di sandbox.

Pattern di errore comuni

• Configurazione errata delle chiavi API - Chiavi mancanti o non valide per E2B, Anthropic o GitHub. Controlla le Impostazioni del progetto.
• Template non trovato - Il template E2B specificato non esiste. Verifica il template ID nella config del workflow.
• Timeout superato - La sandbox ha girato più a lungo del timeout configurato. Aumenta il timeout o semplifica il task.
• Rate limiting - Il provider IA ha limitato le richieste. Attendi e riprova, o passa a un modello diverso.
• Fallimento del git push - La sandbox non è riuscita a pushare verso il remote. Controlla che il token GitHub abbia accesso in scrittura.

Workflow Analytics

CodeCourier fornisce query di analytics per le performance dei workflow. Il modulo workflowAnalytics espone metriche come:

• Run per workflow (quanto spesso ogni blueprint viene usato).
• Tasso di successo (run completati vs. falliti).
• Numero medio di iterazioni (quanti loop prima di passare).
• Durata media (tempo dall’inizio al completamento).

Queste metriche ti aiutano a identificare quali workflow sono efficaci e quali hanno bisogno di regolazione - che significhi aggiustare le istruzioni di persona, cambiare modello o ristrutturare la pipeline.