API de estadísticas y KPI

2 min · 348 palabras Español

Endpoints de estadísticas, KPIs de flota y exportación tidy-long de KPIs (CSV/JSON/XLSX) para agentes LLM.

Leer este artículo como: 📄 Texto plano ⚡ JSON 🤖 Formato LLM

API de estadísticas y KPI

Synapse expone estadísticas de solo lectura sobre la salud de los agentes, el uso de la API, las tendencias y los KPIs de flota. Todos los endpoints aceptan un MindKey (Authorization: Bearer) o un JWT de usuario (requireMindOrUser).

Rutas de análisis existentes (ver la página /stats en la WebUI):

Ruta	Propósito
`GET /stats/agent`	Vista general de todos los agentes (período: `days`)
`GET /stats/agent/comparison`	Comparación entre agentes
`GET /stats/agent/:mindName`	Estadísticas detalladas de un agente
`GET /stats/agent/:mindName/health`	Puntuación de salud
`GET /stats/agent/:mindName/heatmap`	Mapa de calor de actividad
`GET /stats/agent/:mindName/sessions`	Rastreador de sesiones
`GET /stats/api`	Uso de la API (global)
`GET /stats/trends`	Series temporales
`GET /stats/chat/response-times`	Tiempos de respuesta del chat
`GET /stats/a2a/flow`	Flujo de mensajes A2A
`GET /stats/cron`	Analítica de cron
`GET /stats/team` · `/stats/backlog` · `/stats/activity` · `/stats/summary` · `/stats/fleet` · `/stats/monitoring`	Agregados del panel

GET /export/kpis

Exportación tidy-long de los KPIs operativos (tarea 7418541b). La fuente de verdad de los datos es src/db/stats.ts — la capa de exportación solo aplana, no mide nada por sí misma.

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

Parámetro	Valores	Predeterminado
`format`	`csv` · `json` · `xlsx`	`json`
`days`	`1`–`365` (ventana para la vista general de agentes)	`7`

Respuesta:

format=json → { generated_at, period_days, format: "long", columns, row_count, rows[] }
format=csv → text/csv; charset=utf-8 (RFC 4180, BOM, CRLF) como adjunto
format=xlsx → libro de Excel (hoja única KPIs) como adjunto

Columnas tidy-long (idénticas en todos los formatos):

Columna	Significado
`kategorie`	Grupo de KPI: `fleet`, `summary`, `backlog`, `activity`, `team`, `monitoring`, `agent_overview`
`metrik`	Ruta de métrica aplanada (p. ej. `throughput.done_24h_total`)
`wert`	Valor escalar (número, texto o `NULL` cuando solo `detail` lleva datos)
`einheit`	`value` · `count` · `text` · `json`
`zeitstempel`	Marca de tiempo ISO-8601 de generación del export
`quelle`	Función de origen en `src/db/stats.ts`
`detail`	Payload JSON para arrays/objetos profundos, de lo contrario vacío

Ejemplo:

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

La página /stats de la WebUI renderiza el mismo export como tres botones de descarga (CSV/JSON/XLSX) en la sección "KPI export".