Tracing & activité
Observabilité de Grace : journal d'événements, synthèses par projet et vue globale.
Le contexte tracing (platform/backend/src/tracing/) enregistre chaque interaction avec
Grace et alimente l'onglet Activité du dashboard. Il suit la même découpe hexagonale que
le reste du backend.
Le modèle d'événement
Un événement de trace capture une interaction avec le resolver ou la config :
type TraceEventType = "context_load" | "talent_get" | "validate" | "config_change";
interface NewTraceEvent {
projectId: string;
type: TraceEventType;
actor: "web" | "mcp";
route: string;
status: number;
durationMs: number;
payload: Record<string, unknown>;
}La capture est transparente : un interceptor (tracing.interceptor.ts) enregistre l'événement
autour de chaque appel, sans polluer la logique métier. Le port TraceStore
(domain/ports/trace-store.port.ts) abstrait la persistance ; l'adaptateur Drizzle
drizzle-trace-store.ts l'implémente.
Trois niveaux de lecture
Le port expose trois agrégations, exposées par TracingController sous /web/* (session Better
Auth, scopée par l'organisation active) :
| Vue | Endpoint | Contenu |
|---|---|---|
| Synthèse projet | GET /web/projects/:id/traces/summary | compteurs par type, dernière activité, tokens réels chargés |
| Journal projet | GET /web/projects/:id/traces?type=&limit= | événements détaillés, filtrables, avec drill-down sur le payload |
| Usage d'un talent | GET /web/projects/:id/talents/:talentId/usage | chargements (resolves ayant compilé ce talent) + changements de config |
| Activité globale | GET /web/activity/summary | agrégation cross-projet : tokens, événements, par type, top talents, top projets |
Côté dashboard
L'onglet Activité d'un projet (à côté de Talents) rend ces données :
- Tendance des tokens réels par resolve (barres) ;
- Répartition par type + latence moyenne + taux d'erreur ;
- Journal filtrable avec drill-down (payload complet au clic).
Une vue globale agrège l'activité sur l'ensemble des projets de l'utilisateur.
Comme la trace mesure les tokens réels servis par resolve, c'est aussi l'instrument qui permet d'évaluer l'impact de la pertinence sémantique.