Suivi de l’utilisation

CodeCourier fournit un suivi complet de l’utilisation qui enregistre chaque ressource consommée lors des opérations des agents IA. Des décomptes de tokens individuels au temps de fonctionnement des sandboxes, de l’attribution par étape aux tendances de coût quotidiennes, le système d’usage vous donne une visibilité complète sur ce que coûtent vos workflows IA et sur l’endroit où l’argent va. Cette page explique ce qui est suivi, comment fonctionne le tableau de bord d’analytique et les stratégies pour optimiser votre usage.

Ce qui est suivi

Chaque opération qui consomme des ressources externes est enregistrée comme un usageRecord dans la base de données Convex. Chaque enregistrement capture :

• Projet -- Quel projet a généré l’usage.
• Service -- Quel service a été consommé (anthropic, openai, openrouter, e2b, trigger_dev, convex).
• Date -- La chaîne de date ISO (AAAA-MM-JJ) à laquelle l’usage s’est produit.
• Quantité -- La quantité consommée (tokens, secondes, octets, etc.).
• Unité-- Ce qui a été consommé (par exemple, "input_tokens", "output_tokens", "sandbox_seconds").
• Coût (USD) -- Le coût en dollars calculé selon les taux applicables.

Métriques suivies par service

Anthropic / OpenAI / OpenRouter

• Tokens d’entrée -- Tokens envoyés au modèle IA comme contexte (prompt système, historique de conversation, fichiers de code).
• Tokens de sortie -- Tokens générés par le modèle IA en réponse.
• Tokens totaux -- Lorsque la répartition entrée/sortie n’est pas disponible, le total combiné est enregistré.

Sandboxes E2B

• Secondes de sandbox -- Temps de fonctionnement actif de la VM de la création à la terminaison.

Trigger.dev

• Temps d’exécution des tâches -- Durée d’exécution des tâches de fond.

Champs d’attribution

Chaque enregistrement d’usage peut inclure facultativement une attribution détaillée :

• runId -- Quel run de workflow a généré cet usage.
• sandboxId -- Quelle sandbox était impliquée.
• chainId -- Quelle sprint chain, le cas échéant.
• issueSessionId -- Quelle issue session, le cas échéant.
• toolId -- Quel outil CLI a été utilisé (claude, opencode, codex).
• modelId -- L’ID de modèle IA exact utilisé.
• stepType -- Quelle étape du pipeline (designer, checker, optimizer, etc.).
• stepIndex -- Le numéro d’itération au sein de l’étape.
• userId -- Quel membre de l’équipe a déclenché l’opération.
• personaId -- Quelle persona était responsable.
• durationMs -- Temps d’exécution de l’étape en millisecondes.

Tableau de bord d’utilisation

L’analytique d’utilisation est accessible depuis le tableau de bord de votre projet. Le système d’analytique fournit plusieurs points de terminaison de query pour différentes vues :

Résumé d’utilisation du projet

La query usage.getProjectUsageSummary renvoie l’usage agrégé pour un projet sur une plage de dates. Cela alimente les cartes de vue d’ensemble montrant le coût total, le total de tokens et le total d’heures de sandbox.

Résumé d’utilisation avec comparaison

La query usage.getProjectUsageSummaryWithComparison renvoie le résumé de la période actuelle aux côtés de la période précédente pour l’analyse des tendances. Cela permet au tableau de bord d’afficher les variations en pourcentage (à la hausse ou à la baisse) par rapport à la période équivalente précédente.

Utilisation par jour

La query usage.getProjectUsageByDay renvoie les totaux de coût quotidiens, permettant des graphiques de séries temporelles qui montrent les schémas de dépenses au fil du temps. Cela aide à identifier les pics et les tendances.

Utilisation par service

La query usage.getProjectUsageByService ventile les coûts par catégorie de service (Claude Code, E2B, Trigger.dev, etc.), montrant quels services consomment le plus de ressources.

Utilisation agrégée

La query usage.getProjectUsageAggregated fournit une agrégation flexible qui peut regrouper l’usage par diverses dimensions (service, modèle, outil, type d’étape) pour une analyse détaillée.

Analytique au niveau du run

Pour les runs individuels, le système d’analytique fournit :

• runAnalytics.getRunCostsBatch -- Récupération de coût par lot pour plusieurs runs (utilisée par les vues liste de runs).
• runAnalytics.getRunDetailAnalytics -- Ventilation détaillée des coûts pour un run unique, y compris les décomptes de tokens et les coûts par étape.
• runAnalytics.getRunContextAnalytics -- Analytique contextuelle comparant les coûts d’un run aux moyennes du projet.

Compteurs de projet

En plus des enregistrements d’usage détaillés, CodeCourier maintient des compteurs dénormalisés dans la table projectCounters pour un rendu rapide du tableau de bord :

• totalSandboxes / activeSandboxes -- Nombre total et nombre de sandboxes actuellement en cours d’exécution.
• totalRuns / completedRuns / failedRuns -- Nombres de runs par statut.
• totalWorkflows -- Nombre de modèles de workflow.
• totalMembers / pendingInvitations -- Taille de l’équipe et invitations en attente.

Statistiques quotidiennes

La table dailyStats fournit des métriques d’activité quotidiennes préagrégées pour chaque projet :

• Sandboxes créées par jour
• Runs créés, terminés et échoués par jour
• Total d’itérations sur tous les runs par jour
• Workflows créés par jour

Ces compteurs sont mis à jour de manière incrémentielle à mesure que les opérations se produisent, évitant les queries d’agrégation coûteuses sur de grands ensembles de données.

Alertes et limites

Le système de notifications de CodeCourier génère des alertes pour les événements importants qui peuvent affecter vos coûts :

• Run terminé / échoué -- Notifications lorsque les runs de workflow se terminent, vous aidant à rester au courant des opérations actives.
• Sprint terminé / échoué -- Notifications pour la progression des sprint chains, qui peuvent impliquer plusieurs runs séquentiels.
• PR créée / fusionnée / échouée -- Notifications pour les événements du cycle de vie des pull requests.

Puisque la facturation réelle se produit via vos comptes de fournisseur externe, nous recommandons également de configurer des alertes de dépenses directement avec :

• E2B -- Surveillez l’usage de sandbox dans le tableau de bord E2B.
• Anthropic -- Définissez des limites d’usage dans la console Anthropic.
• OpenAI -- Configurez des limites de dépenses dans le tableau de bord OpenAI.

Optimiser l’utilisation

Optimisation des tokens

• Rédigez des prompts ciblés. Des prompts spécifiques et bien délimités réduisent à la fois l’usage de tokens d’entrée et de sortie par rapport à des instructions vagues.
• Utilisez des modèles appropriés. Assignez des modèles plus petits et plus rapides (comme Sonnet ou Haiku) aux tâches simples via le système de personas. Réservez les modèles plus grands pour le travail architectural complexe.
• Limitez les itérations. Définissez des maxIterations raisonnables sur les workflows designer-checker. Trois à cinq itérations sont généralement suffisantes.
• Curez les learnings. Des learnings bien curés réduisent les itérations gaspillées en apprenant aux agents à éviter les erreurs courantes.

Optimisation des sandboxes

• Définissez des délais d’expiration appropriés. Des délais plus courts empêchent les sandboxes oubliées de tourner indéfiniment.
• Utilisez « Arrêter tout » après les sessions. Lorsque vous avez terminé, arrêtez toutes les sandboxes en cours d’exécution pour cesser d’accumuler des frais de calcul.
• Utilisez des templates personnalisés. Les templates avec des dépendances préinstallées évitent le temps d’installation répété (et le coût en tokens de l’agent installant les paquets).

Optimisation des workflows

• Utilisez single designer pour les tâches simples. Toutes les tâches n’ont pas besoin d’un checker. Les tâches simples et bien définies peuvent utiliser le type de workflow single designer.
• Examinez l’analytique des runs. Après avoir terminé un lot de runs, examinez la ventilation des coûts par run dans le tableau de bord d’analytique. Identifiez les runs qui ont été inhabituellement coûteux et ajustez votre configuration de workflow en conséquence.
• Utilisez les issue sessions efficacement. Un prompt de découverte bien structuré peut réduire l’usage de tokens par issue en produisant des prompts suggérés plus clairs et plus ciblés.

Conservation des données

Les enregistrements d’usage sont conservés indéfiniment dans la base de données Convex. Les statistiques quotidiennes sont préagrégées et également conservées indéfiniment. Cela vous permet d’analyser les tendances historiques et de comparer les coûts sur n’importe quelle période. Si vous devez exporter les données d’usage pour des systèmes de comptabilité externes, vous pouvez interroger les points de terminaison d’usage de manière programmatique via la bibliothèque client Convex.