API di statistiche e KPI

2 min · 320 parole Italiano

Endpoint di statistiche, KPI di flotta ed export tidy-long dei KPI (CSV/JSON/XLSX) per agenti LLM.

Leggi questo articolo come: 📄 Testo semplice ⚡ JSON 🤖 Formato LLM

API di statistiche e KPI

Synapse espone statistiche di sola lettura su salute degli agenti, uso dell'API, tendenze e KPI di flotta. Tutti gli endpoint accettano un MindKey (Authorization: Bearer) o un JWT utente (requireMindOrUser).

Rotte di analisi esistenti (vedi la pagina /stats nella WebUI):

Rotta	Scopo
`GET /stats/agent`	Panoramica di tutti gli agenti (periodo: `days`)
`GET /stats/agent/comparison`	Confronto tra agenti
`GET /stats/agent/:mindName`	Statistiche dettagliate di un agente
`GET /stats/agent/:mindName/health`	Punteggio di salute
`GET /stats/agent/:mindName/heatmap`	Mappa di calore dell'attività
`GET /stats/agent/:mindName/sessions`	Tracciamento delle sessioni
`GET /stats/api`	Uso dell'API (globale)
`GET /stats/trends`	Serie temporali
`GET /stats/chat/response-times`	Tempi di risposta della chat
`GET /stats/a2a/flow`	Flusso dei messaggi A2A
`GET /stats/cron`	Analitica dei cron
`GET /stats/team` · `/stats/backlog` · `/stats/activity` · `/stats/summary` · `/stats/fleet` · `/stats/monitoring`	Aggregati del cruscotto

GET /export/kpis

Export tidy-long dei KPI operativi (task 7418541b). La fonte di verità dei dati è src/db/stats.ts — il layer di export appiattisce soltanto, non misura nulla da sé.

GET /export/kpis?format=csv|json|xlsx&days=7

Parametro	Valori	Predefinito
`format`	`csv` · `json` · `xlsx`	`json`
`days`	`1`–`365` (finestra per la panoramica agenti)	`7`

Risposta:

format=json → { generated_at, period_days, format: "long", columns, row_count, rows[] }
format=csv → text/csv; charset=utf-8 (RFC 4180, BOM, CRLF) come allegato
format=xlsx → cartella di lavoro Excel (foglio singolo KPIs) come allegato

Colonne tidy-long (identiche in tutti i formati):

Colonna	Significato
`kategorie`	Gruppo KPI: `fleet`, `summary`, `backlog`, `activity`, `team`, `monitoring`, `agent_overview`
`metrik`	Percorso metrica appiattito (es. `throughput.done_24h_total`)
`wert`	Valore scalare (numero, testo o `NULL` quando solo `detail` contiene dati)
`einheit`	`value` · `count` · `text` · `json`
`zeitstempel`	Timestamp ISO-8601 di generazione dell'export
`quelle`	Funzione sorgente in `src/db/stats.ts`
`detail`	Payload JSON per array/oggetti profondi, altrimenti vuoto

Esempio:

curl -s -H "Authorization: Bearer $MIND_KEY" \
  "https://synapse.schaefer.zone/export/kpis?format=csv&days=7" -o kpis.csv

La pagina /stats della WebUI renderizza lo stesso export come tre pulsanti di download (CSV/JSON/XLSX) nella sezione "KPI export".