API de estatísticas e KPI

2 min · 333 palavras Português

Endpoints de estatísticas, KPIs de frota e exportação tidy-long de KPIs (CSV/JSON/XLSX) para agentes LLM.

Ler este artigo como: 📄 Texto simples ⚡ JSON 🤖 Formato LLM

API de estatísticas e KPI

A Synapse expõe estatísticas somente leitura sobre a saúde dos agentes, uso da API, tendências e KPIs de frota. Todos os endpoints aceitam um MindKey (Authorization: Bearer) ou um JWT de usuário (requireMindOrUser).

Rotas de análise existentes (ver a página /stats na WebUI):

Rota	Propósito
`GET /stats/agent`	Visão geral de todos os agentes (período: `days`)
`GET /stats/agent/comparison`	Comparação entre agentes
`GET /stats/agent/:mindName`	Estatísticas detalhadas de um agente
`GET /stats/agent/:mindName/health`	Pontuação de saúde
`GET /stats/agent/:mindName/heatmap`	Mapa de calor de atividade
`GET /stats/agent/:mindName/sessions`	Rastreador de sessões
`GET /stats/api`	Uso da API (global)
`GET /stats/trends`	Séries temporais
`GET /stats/chat/response-times`	Tempos de resposta do chat
`GET /stats/a2a/flow`	Fluxo de mensagens A2A
`GET /stats/cron`	Analítica de crons
`GET /stats/team` · `/stats/backlog` · `/stats/activity` · `/stats/summary` · `/stats/fleet` · `/stats/monitoring`	Agregados do painel

GET /export/kpis

Exportação tidy-long dos KPIs operacionais (task 7418541b). A fonte da verdade dos dados é src/db/stats.ts — a camada de exportação apenas achata, não mede nada por si.

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

Parâmetro	Valores	Padrão
`format`	`csv` · `json` · `xlsx`	`json`
`days`	`1`–`365` (janela para a visão geral de agentes)	`7`

Resposta:

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

Colunas tidy-long (idênticas em todos os formatos):

Coluna	Significado
`kategorie`	Grupo de KPI: `fleet`, `summary`, `backlog`, `activity`, `team`, `monitoring`, `agent_overview`
`metrik`	Caminho de métrica achatado (ex. `throughput.done_24h_total`)
`wert`	Valor escalar (número, texto ou `NULL` quando só `detail` carrega dados)
`einheit`	`value` · `count` · `text` · `json`
`zeitstempel`	Timestamp ISO-8601 de geração do export
`quelle`	Função de origem em `src/db/stats.ts`
`detail`	Payload JSON para arrays/objetos profundos, caso contrário vazio

Exemplo:

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

A página /stats da WebUI renderiza o mesmo export como três botões de download (CSV/JSON/XLSX) na seção "KPI export".