통계 & KPI API

1 분 · 265 단어 한국어

통계 엔드포인트, 플릿 KPI, LLM 에이전트를 위한 tidy-long KPI 내보내기(CSV/JSON/XLSX).

Synapse는 에이전트 건강, API 사용량, 추세, 플릿 KPI에 대한 읽기 전용 통계를 노출합니다. 모든 엔드포인트는 MindKey(Authorization: Bearer) 또는 사용자 JWT(requireMindOrUser)를 받습니다.

기존 분석 라우트(WebUI의 /stats 페이지 참조):

라우트	목적
`GET /stats/agent`	모든 에이전트 개요(기간: `days`)
`GET /stats/agent/comparison`	에이전트 간 비교
`GET /stats/agent/:mindName`	한 에이전트의 상세 통계
`GET /stats/agent/:mindName/health`	건강 점수
`GET /stats/agent/:mindName/heatmap`	활동 히트맵
`GET /stats/agent/:mindName/sessions`	세션 트래커
`GET /stats/api`	API 사용량(전역)
`GET /stats/trends`	시계열
`GET /stats/chat/response-times`	채팅 응답 시간
`GET /stats/a2a/flow`	A2A 메시지 흐름
`GET /stats/cron`	크론 분석
`GET /stats/team` · `/stats/backlog` · `/stats/activity` · `/stats/summary` · `/stats/fleet` · `/stats/monitoring`	대시보드 집계

GET /export/kpis

운영 KPI의 tidy-long 내보내기(task 7418541b). 데이터의 진실 원천은 src/db/stats.ts입니다 — 내보내기 계층은 평탄화만 하며, 스스로는 아무것도 측정하지 않습니다.

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

매개변수	값	기본값
`format`	`csv` · `json` · `xlsx`	`json`
`days`	`1`–`365`(에이전트 개요의 창)	`7`

응답:

format=json → { generated_at, period_days, format: "long", columns, row_count, rows[] }
format=csv → text/csv; charset=utf-8(RFC 4180, BOM, CRLF) 첨부파일로
format=xlsx → Excel 통합문서(단일 시트 KPIs) 첨부파일로

tidy-long 열(모든 형식에서 동일):

열	의미
`kategorie`	KPI 그룹: `fleet`, `summary`, `backlog`, `activity`, `team`, `monitoring`, `agent_overview`
`metrik`	평탄화된 메트릭 경로(예: `throughput.done_24h_total`)
`wert`	스칼라 값(숫자, 텍스트 또는 `detail`만 데이터를 담을 때 `NULL`)
`einheit`	`value` · `count` · `text` · `json`
`zeitstempel`	내보내기 생성의 ISO-8601 타임스탬프
`quelle`	`src/db/stats.ts`의 원천 함수
`detail`	배열/깊은 객체용 JSON 페이로드, 그 외에는 비어 있음

예시:

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

WebUI의 /stats 페이지는 같은 내보내기를 「KPI export」 섹션에 세 개의 다운로드 버튼(CSV/JSON/XLSX)으로 렌더링합니다.