Monitoraggio dell’utilizzo

CodeCourier fornisce un monitoraggio completo dell’utilizzo che registra ogni risorsa consumata durante le operazioni degli agenti IA. Dai conteggi dei singoli token al tempo di attività delle sandbox, dall’attribuzione per passaggio alle tendenze dei costi giornaliere, il sistema di utilizzo ti offre piena visibilità su quanto costano i tuoi workflow IA e su dove finisce il denaro. Questa pagina spiega cosa viene tracciato, come funziona la dashboard di analytics e le strategie per ottimizzare il tuo utilizzo.

Cosa viene tracciato

Ogni operazione che consuma risorse esterne viene registrata come un usageRecord nel database Convex. Ogni record cattura:

• Progetto -- Quale progetto ha generato l’utilizzo.
• Servizio -- Quale servizio è stato consumato (anthropic, openai, openrouter, e2b, trigger_dev, convex).
• Data -- La stringa di data ISO (AAAA-MM-GG) in cui si è verificato l’utilizzo.
• Quantità -- La quantità consumata (token, secondi, byte, ecc.).
• Unità-- Cosa è stato consumato (ad esempio, "input_tokens", "output_tokens", "sandbox_seconds").
• Costo (USD) -- Il costo in dollari calcolato in base alle tariffe applicabili.

Metriche tracciate per servizio

Anthropic / OpenAI / OpenRouter

• Token di input -- Token inviati al modello IA come contesto (prompt di sistema, cronologia della conversazione, file di codice).
• Token di output -- Token generati dal modello IA in risposta.
• Token totali -- Quando la suddivisione input/output non è disponibile, viene registrato il totale combinato.

Sandbox E2B

• Secondi di sandbox -- Tempo di attività della VM dalla creazione alla terminazione.

Trigger.dev

• Tempo di esecuzione dei task -- Durata dell’esecuzione dei job in background.

Campi di attribuzione

Ogni record di utilizzo può includere facoltativamente un’attribuzione dettagliata:

• runId -- Quale run di workflow ha generato questo utilizzo.
• sandboxId -- Quale sandbox era coinvolta.
• chainId -- Quale sprint chain, se applicabile.
• issueSessionId -- Quale issue session, se applicabile.
• toolId -- Quale strumento CLI è stato usato (claude, opencode, codex).
• modelId -- L’ID esatto del modello IA usato.
• stepType -- Quale passaggio della pipeline (designer, checker, optimizer, ecc.).
• stepIndex -- Il numero di iterazione all’interno del passaggio.
• userId -- Quale membro del team ha avviato l’operazione.
• personaId -- Quale persona era responsabile.
• durationMs -- Tempo di esecuzione del passaggio in millisecondi.

Dashboard di utilizzo

Le analytics di utilizzo sono accessibili dalla dashboard del tuo progetto. Il sistema di analytics fornisce più endpoint di query per viste diverse:

Riepilogo dell’utilizzo del progetto

La query usage.getProjectUsageSummary restituisce l’utilizzo aggregato per un progetto su un intervallo di date. Questo alimenta le card di panoramica che mostrano il costo totale, i token totali e le ore totali di sandbox.

Riepilogo dell’utilizzo con confronto

La query usage.getProjectUsageSummaryWithComparison restituisce il riepilogo del periodo corrente insieme al periodo precedente per l’analisi delle tendenze. Questo consente alla dashboard di mostrare le variazioni percentuali (in aumento o in diminuzione) rispetto al periodo equivalente precedente.

Utilizzo per giorno

La query usage.getProjectUsageByDay restituisce i totali dei costi giornalieri, abilitando grafici di serie temporali che mostrano i pattern di spesa nel tempo. Questo aiuta a identificare picchi e tendenze.

Utilizzo per servizio

La query usage.getProjectUsageByService suddivide i costi per categoria di servizio (Claude Code, E2B, Trigger.dev, ecc.), mostrando quali servizi consumano più risorse.

Utilizzo aggregato

La query usage.getProjectUsageAggregated fornisce un’aggregazione flessibile che può raggruppare l’utilizzo per varie dimensioni (servizio, modello, strumento, tipo di passaggio) per un’analisi dettagliata.

Analytics a livello di run

Per i singoli run, il sistema di analytics fornisce:

• runAnalytics.getRunCostsBatch -- Recupero dei costi in batch per più run (usato dalle viste elenco dei run).
• runAnalytics.getRunDetailAnalytics -- Ripartizione dettagliata dei costi per un singolo run, inclusi i conteggi dei token e i costi per passaggio.
• runAnalytics.getRunContextAnalytics -- Analytics contestuali che confrontano i costi di un run con le medie del progetto.

Contatori di progetto

Oltre ai record di utilizzo dettagliati, CodeCourier mantiene contatori denormalizzati nella tabella projectCounters per un rendering rapido della dashboard:

• totalSandboxes / activeSandboxes -- Conteggi delle sandbox totali e attualmente in esecuzione.
• totalRuns / completedRuns / failedRuns -- Conteggi dei run per stato.
• totalWorkflows -- Numero di blueprint di workflow.
• totalMembers / pendingInvitations -- Dimensione del team e inviti in sospeso.

Statistiche giornaliere

La tabella dailyStats fornisce metriche di attività giornaliere preaggregate per ogni progetto:

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

Questi contatori vengono aggiornati in modo incrementale man mano che le operazioni si verificano, evitando query di aggregazione costose su grandi set di dati.

Avvisi e limiti

Il sistema di notifiche di CodeCourier genera avvisi per gli eventi importanti che possono influenzare i tuoi costi:

• Run completato / fallito -- Notifiche quando i run di workflow terminano, aiutandoti a rimanere aggiornato sulle operazioni attive.
• Sprint completato / fallito -- Notifiche per l’avanzamento delle sprint chain, che possono coinvolgere più run sequenziali.
• PR creata / unita / fallita -- Notifiche per gli eventi del ciclo di vita delle pull request.

Poiché la fatturazione effettiva avviene tramite i tuoi account di provider esterno, raccomandiamo anche di configurare avvisi di spesa direttamente con:

• E2B -- Monitora l’utilizzo delle sandbox nella dashboard E2B.
• Anthropic -- Imposta limiti di utilizzo nella console Anthropic.
• OpenAI -- Configura limiti di spesa nella dashboard OpenAI.

Ottimizzare l’utilizzo

Ottimizzazione dei token

• Scrivi prompt mirati. Prompt specifici e ben delimitati riducono sia l’utilizzo di token di input che di output rispetto a istruzioni vaghe.
• Usa modelli appropriati. Assegna modelli più piccoli e veloci (come Sonnet o Haiku) ai task semplici tramite il sistema di personas. Riserva i modelli più grandi per il lavoro architetturale complesso.
• Limita le iterazioni. Imposta maxIterations ragionevoli sui workflow designer-checker. Da tre a cinque iterazioni sono di solito sufficienti.
• Cura i learning. Learning ben curati riducono le iterazioni sprecate insegnando agli agenti a evitare gli errori comuni.

Ottimizzazione delle sandbox

• Imposta timeout appropriati. Timeout più brevi impediscono alle sandbox dimenticate di girare all’infinito.
• Usa « Termina tutte » dopo le sessioni. Quando hai finito di lavorare, termina tutte le sandbox in esecuzione per smettere di accumulare addebiti di calcolo.
• Usa template personalizzati. I template con dipendenze preinstallate evitano il tempo di installazione ripetuto (e il costo in token dell’agente che installa i pacchetti).

Ottimizzazione dei workflow

• Usa single designer per i task semplici. Non tutti i task hanno bisogno di un checker. I task semplici e ben definiti possono usare il tipo di workflow single designer.
• Rivedi le analytics dei run. Dopo aver completato un batch di run, rivedi la ripartizione dei costi per run nella dashboard di analytics. Identifica i run che sono stati insolitamente costosi e regola la configurazione del tuo workflow di conseguenza.
• Usa le issue session in modo efficace. Un prompt di discovery ben strutturato può ridurre l’utilizzo di token per issue producendo prompt suggeriti più chiari e mirati.

Conservazione dei dati

I record di utilizzo vengono conservati indefinitamente nel database Convex. Le statistiche giornaliere sono preaggregate e anch’esse conservate indefinitamente. Questo ti consente di analizzare le tendenze storiche e confrontare i costi su qualsiasi periodo. Se hai bisogno di esportare i dati di utilizzo per sistemi di contabilità esterni, puoi interrogare gli endpoint di utilizzo in modo programmatico tramite la libreria client Convex.