[Demo] Prometheus/Grafana 예제와 provider smoke 시나리오 준비

[HuitaePark]

목적

심사자와 사용자가 API key 없이 TokenPilot의 핵심 문제 해결을 재현하고, 선택적으로 실제 provider smoke까지 확인할 수 있는 end-to-end sample을 만든다. 단순히 Grafana 화면을 띄우는 데모가 아니라 preflight, 차단, 동시성, 정산과 관측의 인과관계를 보여준다.

현재 코드 근거

• token-pilot-sample-app과 fake ChatModel 기반 E2E test가 있다.
• /test/token-pilot/smoke, /record, /budget, /chat 등 기본 endpoint가 있다.
• Prometheus/Grafana provisioning과 dashboard 파일이 이미 존재한다.
• 현재 sample은 기본 record/budget/metric 흐름은 보이지만 Week 2~3의 context preflight와 reservation lifecycle 전체를 시연하는 release demo는 아니다.

필수 데모 시나리오

A. Context preflight

1. 짧은 요청은 fits=true로 통과한다.
2. 입력 estimate와 reserved output이 context window를 넘으면 BLOCK한다.
3. BLOCK 시 fake provider 호출 횟수가 증가하지 않는다.
4. 응답/로그에 input, reserved output, max context와 remaining을 확인할 수 있다.

B. Budget reservation과 동시성

1. 동일 budget에 여러 요청을 동시에 보낸다.
2. atomic reservation 결과 허용 가능한 요청만 provider로 전달된다.
3. 중복 request ID는 중복 차감되지 않는다.
4. 성공은 actual usage로 commit, provider 실패/취소는 release된다.
5. actual usage를 알 수 없으면 0으로 정산하지 않고 reconciliation 상태를 보여준다.

C. Metrics

• estimate/admission/reservation/commit/release/block/reconciliation 결과를 TokenPilot meter로 노출
• Prometheus scrape 성공
• Grafana dashboard에서 허용·차단 수, reserved/actual cost와 lifecycle outcome 확인
• user ID, prompt, request ID처럼 cardinality가 무한한 값을 tag로 사용하지 않음

실행 모드

기본 모드 — 필수

• fake provider 사용
• API key와 외부 network 불필요
• deterministic한 token usage/cost 반환
• CI와 로컬에서 동일한 결과
• Docker Compose로 application, Prometheus와 Grafana 실행 가능

실제 provider smoke — 선택

• 명시적 profile/환경 변수로만 활성화
• 최소 한 provider에 대해 한 번의 정상 호출을 검증
• credential이 없으면 실패가 아니라 skip/안내
• secret과 prompt 원문을 로그나 repository에 남기지 않음
• 비용 발생 가능성을 runbook에 경고

구현 범위

• sample app endpoint 또는 scripted scenario 정리
• deterministic fake provider와 호출 횟수 probe
• context/budget/lifecycle E2E test
• Prometheus scrape config와 Grafana dashboard 갱신
• Docker Compose 실행, 종료와 초기화 절차
• 데모 예상 출력과 3~5분 시연 runbook
• 실패 시 확인할 metric/log/state 안내

검증 시나리오

• clean environment에서 한 명령으로 기본 stack을 실행한다.
• API key 없이 context pass/block가 재현된다.
• BLOCK 요청에서 provider invocation이 0임을 증명한다.
• 동시 요청에서 예산 초과 승인과 중복 차감이 없다.
• success/failure/unknown actual이 각각 commit/release/reconciliation로 관측된다.
• Prometheus target이 healthy이고 TokenPilot metric query가 값을 반환한다.
• Grafana dashboard가 자동 provisioning되고 핵심 panel에 데이터가 보인다.
• 전체 필수 시나리오가 automated E2E test로도 실행된다.

Acceptance criteria

• fake provider 기반 핵심 데모가 network/credential 없이 재현 가능하다.
• context와 budget BLOCK이 provider 호출 전에 일어남을 보여준다.
• reservation lifecycle과 동시성 안전성이 상태 및 metric으로 확인된다.
• Prometheus/Grafana 화면이 JVM 기본 지표가 아니라 TokenPilot 고유 지표를 보여준다.
• 실제 provider smoke는 완전히 opt-in이며 기본 CI를 불안정하게 만들지 않는다.
• README 또는 별도 runbook에 실행·검증·정리 절차가 있다.

제외 범위

• 다중 provider routing/fallback gateway
• 부하 테스트 플랫폼
• production-grade dashboard/alert 전체 세트
• 실제 provider 호출을 기본 CI gate로 사용
• exact BPE 성능 데모

의존관계와 순서

#33의 context preflight, #36~#38의 reservation lifecycle, #39~#40의 Spring AI/metrics 계약 이후 마무리한다. 문서 실행 경로는 #43과 함께 검증한다.

Source

• 30일 MVP — Week 4 sample/demo