# Milestone: [observe-02] Provider 부하 메트릭과 Live Queue Dashboard

## 위치

- Roadmap: [ROADMAP.md](../../../ROADMAP.md)
- Phase: [PHASE.md](../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 기반](request-execution-log-usage-ledger-foundation.md)에서 별도로 다룬다.
- 선행 작업: 사용자별 OpenAI-compatible 토큰 측정 MVP, Model Group Long-Context Admission
- 후속 작업: [요청 실행 로그와 Usage Ledger 기반](request-execution-log-usage-ledger-foundation.md), [Provider-Device-Model Qualification 리포트와 Lifecycle 관리](provider-device-model-qualification-report.md)
- 확인 필요: `구현 잠금 > 결정 필요`의 label 세트 최종 확인
