Milestone: Provider 부하 메트릭과 Live Queue Dashboard

위치

Roadmap: ROADMAP.md
Phase: PHASE.md

목표

토큰 사용량 지표만으로는 보이지 않는 provider별 live 부하를 시간대별로 분석할 수 있게 한다. Edge가 이미 소유한 provider capacity, in-flight, queued 상태와 queue admission 대기 시간을 Prometheus time series로 노출하고, Grafana에서 capacity 사용률, queue 적체, queue wait p50/p95, timeout/full 패턴을 볼 수 있는 운영 대시보드를 제공한다.

상태

[계획]

승격 조건

없음

구현 잠금

상태: 잠금
SDD: 불필요
SDD 문서: 없음
SDD 사유: 기존 Edge /metrics scrape 경로와 provider snapshot/queue state를 재사용하는 additive 관측 Milestone이며, proto/API/storage 계약이나 raw payload 보관 정책을 바꾸지 않는다.
잠금 해제 조건: 아래 체크리스트
- 사용자가 이 Milestone의 metric/dashboard 범위와 low-cardinality label 표준선을 검토했다.
결정 필요: 아래 체크리스트
- 구현 시작 전 provider_id, model_group, queue_reason, context_class 등 Grafana 분석에 필요한 label 세트가 충분한지 최종 확인한다.

범위

Edge provider-pool queue state에서 provider별 capacity, in_flight, queued, load_ratio, long-context capacity/in-flight/queued를 Prometheus gauge로 노출한다.
queue admission 경로에서 queue wait duration, dispatch/timeout/full/cancel 결과, queue reason을 Prometheus histogram/counter로 노출한다.
Grafana dashboard를 repository-managed provisioning 대상으로 추가해 live 부하와 시간대별 적체를 조회할 수 있게 한다.
dev-corp 또는 local runtime에서 /metrics scrape, Prometheus query, capacity+1 smoke 중 queue 적체/회복 관측을 검증한다.
기존 token usage 지표와 같은 secret-safe, low-cardinality label 원칙을 유지한다.

기능

Epic: [load-observability] Live Provider Load Observability

provider capacity 사용률과 queue 적체를 운영자가 시간대별로 분석할 수 있는 계측과 대시보드 capability를 묶는다.

[provider-gauges] Edge /metrics에 provider별 capacity, in_flight, queued, load_ratio, long-context gauge가 추가되어 있다. 검증: /metrics에서 신규 iop_edge_provider_* metric이 노출되고 provider별 label cardinality가 bounded인지 확인한다.
[queue-wait] queue admission 경로에서 대기 시간 histogram과 dispatch/full/timeout/cancel counter가 기록되어 있다. 검증: queue가 발생하는 동시 호출 테스트에서 iop_edge_provider_queue_wait_seconds_bucket과 queue result counter가 증가한다.
[dashboard] Grafana dashboard가 capacity 사용률, in-flight/capacity, queued, queue wait p50/p95, queue full/timeout rate를 보여준다. 검증: Prometheus datasource 기준 dashboard JSON/provisioning이 로드되고 각 panel query가 빈 쿼리 오류 없이 동작한다.
[devcorp-verify] dev-corp 또는 local capacity+1 smoke로 부하가 찼다가 회복되는 흐름을 metric과 dashboard에서 확인한다. 검증: smoke 중 peak in_flight, queued, queue wait가 관측되고 종료 후 in_flight=0, queued=0 회복이 확인된다.
[cardinality-guard] metric label allowlist가 request_id, session_id, raw token, prompt/response text를 포함하지 않도록 테스트 또는 코드 검토 근거가 남아 있다.

완료 리뷰

상태: 없음
요청일: 없음
완료 근거: 계획 Milestone이며 기능 Task가 아직 충족되지 않았다.
검토 항목: 기능 Task와 검증이 충족되고 구현 잠금이 해제되었는지 확인한다.
agent-ui 상태 반영: 해당 없음
리뷰 코멘트: 없음

범위 제외

요청별 ledger storage, 장기 retention, export API, billing/chargeback
prompt/response/reasoning raw payload 또는 preview 보관 정책
provider routing 알고리즘, capacity 의미, queue timeout 정책 변경
Control Plane/Flutter client UI의 신규 화면 구현
provider runtime launch/restart, 모델 다운로드, lifecycle 제어

작업 컨텍스트

관련 경로: apps/edge/internal/service, apps/edge/internal/openai, packages/go/observability, configs/prometheus, configs/grafana, agent-test/dev-corp
표준선(선택): provider 부하의 source of truth는 Edge queue state이며, Control Plane status snapshot은 live 조회 표면이고 Prometheus는 시간대별 분석 표면이다.
표준선(선택): metric label은 edge_id, node_id, provider_id, provider_type, model_group, queue_reason, context_class, status처럼 bounded set으로 제한하고 request/user raw data를 넣지 않는다.
표준선(선택): request-level 원장, redaction, storage/export는 요청 실행 로그와 Usage Ledger 기반에서 별도로 다룬다.
선행 작업: 사용자별 OpenAI-compatible 토큰 측정 MVP, Model Group Long-Context Admission
후속 작업: 요청 실행 로그와 Usage Ledger 기반, Provider-Device-Model Qualification 리포트와 Lifecycle 관리
확인 필요: 구현 잠금 > 결정 필요의 label 세트 최종 확인

5.3 KiB Raw Blame History