Monitoring

CodeCourier fournit des outils de monitoring complets pour suivre l’exécution des workflows, la santé des sandboxes et les performances à l’échelle du système. Toutes les données de monitoring sont propulsées par des requêtes réactives Convex, ce qui signifie que le dashboard se met à jour en temps réel sans polling. Ce guide couvre les surfaces de monitoring, les données qu’elles exposent et comment les utiliser efficacement.

Suivi du statut des runs

Dashboard de liste des runs

La page Runs est la principale surface de monitoring. Elle montre une liste paginée de tous les runs du projet actuel, ordonnée par heure de création (les plus récents en premier). Chaque ligne affiche :

• Badge de statut - Indicateur codé par couleur montrant pending (gris), running (bleu), completed (vert), failed (rouge) ou cancelled (ambre).
• Nom du run - Nom auto-généré ou fourni par l’utilisateur.
• Source - D’où le run provient : workflow, sprint, sandbox ou merge agent.
• Aperçu du prompt - Premières lignes de la description de la tâche.
• Timing - Heure de création et durée (si terminé).
• Statut de PR - Si une pull request a été créée, mergée ou a échoué.

Vue détaillée du run

Cliquer sur un run ouvre sa page de détail avec des informations d’exécution complètes :

• Timeline des étapes - Une représentation visuelle de chaque étape du pipeline, montrant le rôle (designer, checker, evaluator, etc.), l’outil CLI et le modèle utilisés, le statut et la durée. Les étapes sont affichées dans l’ordre d’exécution avec les numéros d’itération.
• Sortie de sandbox - La sortie de terminal de la sandbox de chaque étape, y compris les réponses de l’agent IA, les événements d’utilisation d’outils et les messages d’erreur. La sortie se met à jour en temps réel pendant l’exécution de l’étape.
• Verdicts de checker - Pour les étapes checker, le verdict pass/fail et le texte de feedback sont affichés inline dans la timeline.
• Scores de qualité - Pour les étapes evaluator, la décomposition des scores de qualité sur cinq dimensions et le score composite sont affichés inline. Un indicateur de seuil montre si le score composite atteint le seuil configuré.
• Statut des CI checks - Le statut CI agrégé (passing, failing, pending) et les résultats de checks individuels avec des liens vers GitHub.
• Configuration - La config de sandbox du run, le prompt, les images de référence et les métadonnées.
• Détails d’erreur - Si le run a échoué, le message d’erreur et l’étape où l’échec s’est produit.

Monitoring des scores de qualité

Les scores de qualité fournissent une vue quantitative de la manière dont chaque workflow run répond aux critères de qualité définis. Ils sont produits par les étapes Evaluator et remontés à deux niveaux :

• Niveau run - Le champ qualityScore de l’enregistrement du run contient le score composite (0 à 100) agrégé sur toutes les étapes evaluator du pipeline. Il est visible dans la liste des Runs sous forme de badge de score, permettant une comparaison de qualité d’un coup d’œil entre les runs.
• Niveau étape - Les enregistrements de run step evaluator individuels portent la décomposition complète qualityScores sur les cinq dimensions.

Interpréter les dimensions de 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
}

Chaque dimension est notée indépendamment de 0 (ne répond pas aux critères) à 100 (répond entièrement aux critères). Le score composite est une moyenne pondérée - vous pouvez configurer les poids sur la persona evaluator pour mettre l’accent sur les dimensions les plus importantes pour votre projet. Le booléen thresholdResult est le signal le plus actionnable : une valeur false signifie que l’implémentation n’a pas atteint votre barre de qualité et peut justifier une itération supplémentaire.

Tendances de qualité

La section Workflow Analytics montre les tendances des scores de qualité au fil du temps pour un workflow donné. Suivre le score composite à travers les runs révèle si votre pipeline produit constamment une sortie de haute qualité ou présente une qualité dégradante au fil du temps (ce qui signale souvent que les instructions de persona ont besoin d’être affinées ou que le workflow a besoin d’une passe d’amélioration supplémentaire).

Monitoring des CI Checks

Après qu’un run crée une pull request, CodeCourier surveille le statut des CI checks pour cette PR et le remonte dans l’interface de monitoring.

Statut CI dans la liste des runs

La liste des Runs affiche un indicateur de statut CI à côté du statut de PR pour chaque run. Le statut agrégé (« passing », « failing » ou « pending ») est montré sous forme de badge coloré. Les runs avec prStatus = "blocked_on_ci" sont mis en évidence pour indiquer que la PR ne peut pas être mergée tant que la CI n’est pas résolue.

Détails des checks individuels

La vue détaillée du run liste chaque CI check individuel avec son nom, son statut et un lien direct vers le check run sur GitHub. Cela vous permet de naviguer directement d’un run CodeCourier en échec vers la sortie spécifique du job CI, réduisant le temps passé à diagnostiquer les échecs.

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 des Sprint Chains

Les sprint chains apparaissent dans les surfaces de monitoring avec un contexte supplémentaire par rapport aux runs individuels.

Sprint chain dans la liste des runs

Les runs de sprint individuels apparaissent dans la liste des Runs avec la source sprint. Le nom du run inclut le numéro de sprint (par exemple, « Sprint 2 of 5 - Feature X ») afin que vous puissiez suivre chaque phase d’un coup d’œil. Vous pouvez filtrer la liste des Runs par source pour n’afficher que les runs issus de sprints.

Vue détaillée de la sprint chain

La vue détaillée de la sprint chain fournit une vue consolidée de toute la chaîne :

• Statut de la chaîne - L’état global de la chaîne (pending, running, completed, failed ou cancelled).
• Progression des sprints- Index de sprint actuel et nombre total de sprints (par exemple, « 3 of 5 sprints completed »).
• URLs de PR par sprint - Le tableau sprintPrUrls affiché sous forme de liste cliquable, une entrée par sprint. Les sprints terminés montrent leur URL de PR ; les sprints futurs apparaissent comme pending.
• Timeline des sprints - Une timeline des exécutions de sprints avec les heures de début et de fin, permettant la comparaison des durées entre sprints.

Statut des runs Trigger.dev

En plus du suivi au niveau Convex, CodeCourier lie chaque run à son exécution de tâche Trigger.dev correspondante. Le champ triggerRunId de l’enregistrement du run fournit une traçabilité vers le dashboard Trigger.dev où vous pouvez inspecter :

• La position dans la file de tâches et la planification.
• Les logs d’exécution au niveau de l’infrastructure.
• L’historique de retry (si la tâche a été réessayée).
• La consommation de ressources et le timing.

Ce suivi à deux niveaux (Convex + Trigger.dev) garantit que vous pouvez déboguer à la fois les problèmes de niveau applicatif (mauvais prompt, feedback de checker) et les problèmes de niveau infrastructure (timeout, OOM, panne réseau).

Monitoring des sandboxes

Compteur de sandboxes actives

Le dashboard de projet affiche un compteur de sandboxes actives - le nombre de sandboxes actuellement à l’état running. Ce compteur est dénormalisé dans la table projectCounters et se met à jour en temps réel à mesure que les sandboxes démarrent et s’arrêtent.

Liste des sandboxes

La page Sandboxes montre toutes les sandboxes du projet (à l’exclusion de celles créées par les workflows et les sessions d’issue). Chaque entrée montre le statut de la sandbox, la configuration, l’heure de création et les informations de PR liées.

Terminal en streaming

Pour les sandboxes individuelles, le composant de terminal en streaming fournit une sortie en temps réel de l’agent IA. Le terminal rend :

• Les messages assistant avec du texte formaté.
• Les événements d’utilisation d’outils (écritures de fichiers, exécution de commandes).
• Les messages user envoyés interactivement.
• Les indicateurs de statut pour les états streaming, completed et error.

Métriques au niveau du projet

Compteurs de projet

CodeCourier maintient des compteurs dénormalisés pour chaque projet :

• Total des sandboxes - Nombre à vie de sandboxes créées.
• Sandboxes actives - Sandboxes actuellement en cours d’exécution.
• Total des runs - Nombre à vie de workflow runs.
• Runs terminés - Runs terminés avec succès.
• Runs en échec - Runs qui se sont terminés en échec.
• Total des workflows - Nombre de blueprints de workflow.
• Total des membres - Membres de l’équipe dans le projet.
• Invitations en attente - Invitations de membres non acceptées.

Ces compteurs sont affichés sur la page de vue d’ensemble du projet et se mettent à jour de manière réactive.

Statistiques quotidiennes

La table dailyStats suit des métriques par jour :

• Sandboxes créées.
• Runs créés, terminés et en échec.
• Total des itérations sur tous les runs.
• Workflows créés.

Ces données alimentent les graphiques historiques et l’analyse des tendances dans le dashboard de projet.

Suivi d’usage et de coût

Chaque session de sandbox et étape de workflow génère des enregistrements d’usage dans la table usageRecords. Ces enregistrements fournissent une visibilité de coût détaillée :

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

Les enregistrements d’usage sont liés à des runs, sandboxes, chaînes et sessions d’issue spécifiques. Cela vous permet de suivre les coûts à chaque niveau - des étapes individuelles aux work chains entières.

Notifications

CodeCourier envoie des notifications pour les événements importants. La table notifications stocke les notifications par utilisateur avec les types suivants :

• run_completed - Un workflow run s’est terminé avec succès.
• run_failed - Un workflow run a échoué.
• pr_created - Une pull request a été créée.
• pr_merged - Une pull request a été mergée.
• pr_failed - La création d’une pull request a échoué.
• member_joined - Un nouveau membre d’équipe a rejoint le projet.
• workflow_completed - Toutes les étapes d’un workflow se sont terminées.
• sprint_completed - Une sprint chain s’est terminée.
• sprint_failed - Une sprint chain a échoué.

Les notifications sont affichées dans le dashboard et peuvent être marquées comme lues ou rejetées. Elles sont indexées par projet, utilisateur et statut de lecture pour un requêtage efficace.

Monitoring des erreurs

Surfaces d’erreur

Les erreurs sont capturées à plusieurs niveaux :

• Erreurs de sandbox - Le champ error des enregistrements de sandbox stocke les échecs de provisionnement E2B et les crashs d’agent.
• Erreurs de run - Le champ error des enregistrements de run stocke les échecs de niveau pipeline.
• Erreurs d’étape - Le champ error des enregistrements de run step stocke les échecs spécifiques aux étapes.
• Erreurs de PR - Le champ prError des enregistrements de sandbox et de run stocke les échecs de création de pull request.
• Erreurs d’extraction de learning - Le champ learningExtractionError des enregistrements de sandbox.

Patterns d’erreur courants

• Mauvaise configuration de clé API - Clés manquantes ou invalides pour E2B, Anthropic ou GitHub. Vérifiez les Paramètres du projet.
• Template introuvable - Le template E2B spécifié n’existe pas. Vérifiez le template ID dans la config du workflow.
• Timeout dépassé - La sandbox a tourné plus longtemps que le timeout configuré. Augmentez le timeout ou simplifiez la tâche.
• Rate limiting - Le provider IA a limité le débit des requêtes. Attendez et réessayez, ou passez à un modèle différent.
• Échec de git push - La sandbox n’a pas pu pousser vers le remote. Vérifiez que le token GitHub a un accès en écriture.

Workflow Analytics

CodeCourier fournit des requêtes d’analytics pour les performances des workflows. Le module workflowAnalytics expose des métriques comme :

• Runs par workflow (à quelle fréquence chaque blueprint est utilisé).
• Taux de succès (runs terminés vs. en échec).
• Nombre moyen d’itérations (combien de boucles avant de passer).
• Durée moyenne (temps du début à l’achèvement).

Ces métriques vous aident à identifier quels workflows sont efficaces et lesquels ont besoin d’ajustement - que cela signifie ajuster les instructions de persona, changer de modèle ou restructurer le pipeline.