adr multi resolution history

ADR - Multi-resolution History Storage

메타데이터	값
상태	accepted
결정일	2026-05-28
구현 완료	2026-05-29
현재 유효 여부	유효
구현 근거	apps/graph-metrics-aggregator, apps/dashboard-backend(history window 분기)
검증 근거	history_raw steady-state item 감소, /history?window=24h 응답 < 2초

---

결정

단일 HISTORY#STATE# 이력을 두 해상도 계층으로 나눈다.

계층	sort key	TTL	역할
history_raw	HISTORY#STATE#*	목표 2h (마지막 문서화된 운영값 48h)	1h 실시간 정밀 차트
history_bucket	GRAPH#5M#*	48h	5분 avg/min/max 집계, 6h/12h/24h 그래프

Dashboard Backend는 조회 window에 따라 분기한다 — 1h는 HISTORY#STATE#(원시), 6h/12h/24h는 GRAPH#5M#(집계, 24h 기준 factory당 288 items). 집계는 GraphAggregator5m Lambda가 5분 주기 EventBridge로 직전 완료 버킷을 계산해 PutItem한다.

이유 (사고 기반)

2026-05-28 production incident: HISTORY_TTL=48h × factory_state 3초 주기 × 3공장 기준으로 약 116,000개 이상의 아이템이 상주했다. /history?window=24h를 3공장 동시 요청하면 50+ DynamoDB Query 페이지 호출로 async semaphore가 포화되어 cascade 504 Gateway Timeout이 발생했다.

임시방편(max_items=500 cap)은 500건 초과 구간의 위험 스파이크가 차트에서 유실되는 문제를 남겼다. 계층화로 steady-state 아이템 수를 ~8,000(3공장)으로 약 93% 감소시키고, 집계 버킷에 min/max를 보존해 스파이크 유실 없이 504를 해소했다.

영향

• GraphAggregator5m Lambda + EventBridge Scheduler 신설(8,640 invocations/월, 추가 비용 소액).
• Backend get_factory_history() window 분기, GRAPH#5M 응답 필드(risk_score_avg/min/max 등) 추가.
• Frontend 차트를 LineChart → ComposedChart로 교체(평균 실선 + 최대 점선 + 음영 + 임계선).
• 집계는 완료된 버킷만 처리하므로 진행 중인 마지막 5분 버킷은 다음 주기까지 GRAPH#5M에 없다.

Safety Score 방향은 100 = 최안전, 0 = 최위험이다(안전 85↑ / 주의 50~84 / 위험 49↓).

관련 문서

• 데이터 조회 모델
• Graph Aggregator 5m
• API 명세
• DynamoDB Key Model
• ADR 인덱스