<!-- task=m-usage-token-log-ops-mvp/03+02_grafana_rollup_docs plan=0 tag=USAGE_GRAFANA -->

# Plan - USAGE_GRAFANA

## 이 파일을 읽는 구현 에이전트에게

`CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채우는 것이 마지막 단계다. 구현 후 active 파일을 유지하고 리뷰 준비 상태로 보고한다. 선택된 Milestone `구현 잠금 > 결정 필요` 항목이 실구현을 막을 때만 review stub의 `사용자 리뷰 요청`을 채우고 멈춘다. 직접 사용자에게 질문하거나 `USER_REVIEW.md`, `complete.log`, archive log를 만들지 않는다. 환경/secret/service 차단과 검증 증거 공백은 일반 후속 이슈로 기록한다.

## 배경

이 plan은 Prometheus metric 구현이 끝난 뒤 운영자가 Grafana에서 사용자별 OpenAI-compatible token 사용량을 볼 수 있게 하는 문서 표면이다. Control Plane/Client dashboard, request-level ledger, 사용자별 제한 enforcement는 만들지 않고, 02에서 확정한 metric 이름과 label을 기준으로 PromQL query와 daily/monthly rollup 기준을 문서화한다.

## 선행 의존성

- 선행 subtask: `agent-task/m-usage-token-log-ops-mvp/02+01_usage_metrics`
- 시작 조건: active 경로 또는 같은 task group archive 후보의 선행 `complete.log`가 존재하고, metric 이름/label이 code-review PASS로 확정되어 있어야 한다.
- 선행 완료 전에는 이 plan을 구현하지 말고 active 파일만 유지한다.

## 사용자 리뷰 요청 흐름

구현 중 직접 사용자 프롬프트를 띄우지 않는다. 선택된 Milestone lock decision만 active review stub의 `사용자 리뷰 요청` 섹션에 기록하며, code-review가 검증 후 실제 `USER_REVIEW.md` 작성 여부를 결정한다.

## Roadmap Targets

- Milestone: `agent-roadmap/phase/operational-observability-provider-management/milestones/usage-token-log-ops-mvp.md`
- Milestone link: [Milestone 문서](agent-roadmap/phase/operational-observability-provider-management/milestones/usage-token-log-ops-mvp.md)
- Task ids:
  - `grafana-surface`: Control Plane/Client dashboard 없이 Grafana query를 1차 조회 표면으로 둔다.
  - `limit-followup`: 사용자별 token 제한은 후속 범위로 남기고, daily/monthly warn/reject 정책에 재사용 가능한 rollup 기준을 문서화한다.
- Completion mode: check-on-pass

## 분석 결과

### 읽은 파일

- `agent-roadmap/phase/operational-observability-provider-management/PHASE.md`
- `agent-roadmap/phase/operational-observability-provider-management/milestones/usage-token-log-ops-mvp.md`
- `agent-roadmap/sdd/operational-observability-provider-management/usage-token-log-ops-mvp/SDD.md`
- `agent-contract/outer/openai-compatible-api.md`
- `agent-ops/rules/project/domain/edge/rules.md`
- `agent-ops/rules/project/domain/platform-common/rules.md`
- `agent-ops/rules/project/domain/testing/rules.md`
- `agent-test/local/rules.md`
- `docs/openai-compatible-api-contract.md`
- `docs/edge-local-dev-guide.md`

### SDD 기준

- SDD: `agent-roadmap/sdd/operational-observability-provider-management/usage-token-log-ops-mvp/SDD.md`, 상태 `[승인됨]`, SDD 잠금 `해제`.
- 대상 Acceptance Scenario: S09(`grafana-surface`), S10(`limit-followup`).
- Evidence Map은 Grafana query/dashboard 예시 또는 Prometheus scrape evidence, 제한 enforcement가 후속 범위로 남고 metric 재사용 기준이 문서화된 근거를 요구한다.

### 테스트 환경 규칙

- test_env: `local`.
- 읽은 규칙: `agent-test/local/rules.md`.
- 이 plan은 docs/query 중심이므로 Go test는 코드 변경이 있을 때만 실행한다.
- 적용 명령:

```bash
rg --fixed-strings "iop_openai_usage_tokens_total" docs/openai-usage-grafana.md
rg --fixed-strings "daily" docs/openai-usage-grafana.md
rg --fixed-strings "monthly" docs/openai-usage-grafana.md
git diff --check
```

### 테스트 커버리지 공백

- `docs/`에는 OpenAI-compatible API contract와 Edge local dev guide만 있고 usage/Grafana operator guide가 없다.
- metric 이름과 labels가 02에서 확정되기 전에는 정확한 PromQL을 작성할 수 없다.
- limit enforcement는 Milestone 범위 제외이므로 문서에는 재사용 가능한 rollup 기준과 후속 경계만 남겨야 한다.

### 분할 판단

- split policy를 먼저 적용했다.
- shared task group: `m-usage-token-log-ops-mvp`.
- predecessor `02+01_usage_metrics`가 metric schema를 확정해야 이 docs plan이 의미 있다.
- 이 plan은 문서/운영 query만 다루므로 `local-G03`이 적절하다.

### 범위 결정 근거

- 포함: `docs/openai-usage-grafana.md` 신규 작성.
- 포함: principal alias/token ref별 token type breakdown, reasoning 보조 metric, request status query, daily/monthly rollup query, label cardinality/secret 금지 기준.
- 포함: limit follow-up 기준. warn/reject enforcement는 후속 Milestone으로 남기되, `principal_ref`/`token_ref`/`model_group`/`token_type` rollup이 재사용 가능하다는 점을 문서화한다.
- 제외: Grafana JSON dashboard import file, Control Plane/Client dashboard, billing/cost model, user CRUD, token limit enforcement.

### 빌드 등급

- `local-G03`: code-free docs/query 작업이다. 단, 02 metric schema와 직접 맞아야 하므로 선행 완료 확인이 필요하다.

## 구현 체크리스트

- [ ] 선행 `02+01_usage_metrics`의 active 또는 same-task-group archive `complete.log`와 PASS evidence를 확인한다.
- [ ] 02에서 확정된 metric 이름과 label allowlist를 실제 코드에서 확인한다.
- [ ] `docs/openai-usage-grafana.md`를 작성한다.
- [ ] Grafana query examples가 principal/token/model/token type별 사용량을 보여주도록 작성한다.
- [ ] daily/monthly rollup과 limit follow-up 경계를 명확히 문서화한다.
- [ ] 검증 명령을 실행한다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

### [USAGE_GRAFANA-1] Grafana Operator Guide

문제: 운영자가 Prometheus metric을 직접 알더라도 어떤 query를 Grafana panel로 써야 하는지, 어떤 label을 group by 해야 하는지 문서화되어 있지 않다.

수정 파일 및 체크리스트:
- [ ] `docs/openai-usage-grafana.md`: 목적, metric 목록, label allowlist, 금지 label, PromQL examples, dashboard panel 후보를 작성한다.
- [ ] `docs/openai-usage-grafana.md`: `principal_alias`, `principal_ref`, `token_ref`, `model_group`, `endpoint`, `response_mode`, `token_type`, `usage_source`, `status` 기준 query를 포함한다.
- [ ] `docs/openai-usage-grafana.md`: provider가 reasoning token을 보고하지 않는 경우 token 추정 없이 `iop_openai_reasoning_observed_total`/`iop_openai_reasoning_chars_total`를 보는 기준을 포함한다.

검증:

```bash
rg --fixed-strings "iop_openai_usage_tokens_total" docs/openai-usage-grafana.md
rg --fixed-strings "iop_openai_reasoning_observed_total" docs/openai-usage-grafana.md
```

### [USAGE_GRAFANA-2] Limit Follow-up Rollup

문제: 사용자별 token 제한은 이 Milestone에서 구현하지 않지만, 1차 metric이 후속 daily/monthly warn/reject 정책에 재사용 가능한 형태인지 문서 evidence가 필요하다.

수정 파일 및 체크리스트:
- [ ] `docs/openai-usage-grafana.md`: daily/monthly token rollup PromQL examples를 작성한다.
- [ ] `docs/openai-usage-grafana.md`: warn/reject enforcement는 후속 Milestone이며, 현재 문서는 조회와 운영 판단 기준까지만 제공한다고 명시한다.
- [ ] `docs/openai-usage-grafana.md`: billing/price/ROI amount 산출과 request-level ledger는 범위 제외라고 명시한다.

검증:

```bash
rg --fixed-strings "daily" docs/openai-usage-grafana.md
rg --fixed-strings "monthly" docs/openai-usage-grafana.md
rg --fixed-strings "후속" docs/openai-usage-grafana.md
```

## 수정 파일 요약

| 파일 | 항목 |
|------|------|
| `docs/openai-usage-grafana.md` | USAGE_GRAFANA-1, USAGE_GRAFANA-2 |

## 최종 검증

```bash
rg --fixed-strings "iop_openai_usage_tokens_total" docs/openai-usage-grafana.md
rg --fixed-strings "daily" docs/openai-usage-grafana.md
rg --fixed-strings "monthly" docs/openai-usage-grafana.md
git diff --check
```

모든 문서 변경 완료 후 반드시 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.
