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

# Plan - REVIEW_USAGE_GRAFANA

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

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

## 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`: Grafana query를 1차 조회 표면으로 둔다.
  - `limit-followup`: 제한 enforcement는 후속 범위로 남기고 daily/monthly rollup 기준을 문서화한다.
- Completion mode: check-on-pass

## Archive Evidence Snapshot

- Current archived plan: `agent-task/m-usage-token-log-ops-mvp/03+02_grafana_rollup_docs/plan_local_G03_0.log`
- Current archived review: `agent-task/m-usage-token-log-ops-mvp/03+02_grafana_rollup_docs/code_review_local_G03_0.log`
- Verdict: FAIL
- Required summary:
  - `docs/openai-usage-grafana.md:166`: daily/monthly rollup examples are presented as PromQL, but `increment()` is not a Prometheus standard function.
  - `docs/openai-usage-grafana.md:170-175`: fallback example combines aggregation modifiers and raw counter snapshots, so it is not a valid daily delta rollup.
  - `docs/openai-usage-grafana.md:191`: `sum_over_time()` over a raw counter is not a 30-day usage increase and does not satisfy reusable limit follow-up evidence.
- Suggested summary:
  - `docs/openai-usage-grafana.md:150`: dashboard legend uses `{{token_type}}`, but the query groups only by `principal_alias`.
- Affected files:
  - `docs/openai-usage-grafana.md`
- Verification evidence from previous loop:
  - `rg --fixed-strings "iop_openai_usage_tokens_total" docs/openai-usage-grafana.md` - PASS; showed metric examples and the problematic rollup lines.
  - `rg --fixed-strings "daily" docs/openai-usage-grafana.md` - PASS; only string presence, not PromQL validity.
  - `rg --fixed-strings "monthly" docs/openai-usage-grafana.md` - PASS; only string presence, not PromQL validity.
  - `git diff --check` - PASS; no output.
- Roadmap carryover:
  - Keep `grafana-surface` and `limit-followup` as target task ids.
  - Do not update `agent-roadmap/**` from this implementation or review loop.
- Narrow archive reread allowed if needed:
  - `agent-task/m-usage-token-log-ops-mvp/03+02_grafana_rollup_docs/plan_local_G03_0.log`
  - `agent-task/m-usage-token-log-ops-mvp/03+02_grafana_rollup_docs/code_review_local_G03_0.log`

## 배경

첫 리뷰에서 metric 이름과 label allowlist는 실제 코드와 일치함을 확인했다. 실패 지점은 docs/query 품질이다. `limit-followup` Task는 daily/monthly warn/reject 정책에 재사용 가능한 rollup 기준을 문서화해야 하는데, 현재 문서는 Prometheus counter 증가분 계산에 맞지 않는 예시를 포함한다.

## 범위 결정 근거

- 포함: `docs/openai-usage-grafana.md`의 daily/monthly rollup PromQL 수정.
- 포함: 후속 제한 정책에서 재사용할 수 있도록 principal/token/model/token type 기준 grouping 예시 보강.
- 포함: token type legend를 쓰는 dashboard panel query의 label 보존 수정.
- 제외: Grafana JSON dashboard import file, Control Plane/Client dashboard, billing/cost model, user CRUD, token limit enforcement.
- 제외: metric 이름/label schema 변경. 이번 후속은 문서 query correction만 다룬다.

## 구현 체크리스트

- [ ] `docs/openai-usage-grafana.md` daily/monthly rollup PromQL을 `increase()` 기반 counter delta query로 수정한다.
- [ ] `docs/openai-usage-grafana.md`에서 `increment()`, invalid `by`/`without` 혼합, raw counter `sum_over_time()` 대안을 제거하거나 Prometheus query가 아닌 설명으로 분리한다.
- [ ] daily/monthly rollup query가 `principal_alias`/`principal_ref`/`token_ref`/`model_group`/`token_type` 기준 재사용 예시를 포함하도록 보강한다.
- [ ] 사용자별 token 사용량 dashboard panel query가 legend에 쓰는 `token_type` label을 보존하도록 수정한다.
- [ ] 검증 명령을 실행한다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

### [REVIEW_USAGE_GRAFANA-1] Prometheus Rollup Correction

문제: daily/monthly rollup 예시가 Prometheus datasource에서 바로 재사용 가능한 PromQL이 아니며, counter 증가분이 아닌 raw counter sample 집계를 제시한다.

수정 파일 및 체크리스트:
- [ ] `docs/openai-usage-grafana.md`: 일일 rollup을 `increase(iop_openai_usage_tokens_total[1d])` 기반 query로 수정한다.
- [ ] `docs/openai-usage-grafana.md`: 월간 rollup을 `increase(iop_openai_usage_tokens_total[30d])` 기반 query로 수정한다.
- [ ] `docs/openai-usage-grafana.md`: `principal_alias`, `principal_ref`, `token_ref`, `model_group`, `token_type` grouping을 후속 limit policy 재사용 관점에서 명시한다.
- [ ] `docs/openai-usage-grafana.md`: `increment()`, invalid `by`/`without` 혼합, raw counter `sum_over_time()`를 제거한다.

검증:

```bash
rg --fixed-strings "increase(iop_openai_usage_tokens_total[1d])" docs/openai-usage-grafana.md
rg --fixed-strings "increase(iop_openai_usage_tokens_total[30d])" docs/openai-usage-grafana.md
if rg --fixed-strings "increment(" docs/openai-usage-grafana.md; then exit 1; fi
if rg --fixed-strings "sum_over_time(iop_openai_usage_tokens_total" docs/openai-usage-grafana.md; then exit 1; fi
```

### [REVIEW_USAGE_GRAFANA-2] Dashboard Token Type Label Alignment

문제: dashboard panel 후보의 사용자별 token 사용량 query가 `token_type` label을 drop하면서 legend에 `{{token_type}}`을 사용한다.

수정 파일 및 체크리스트:
- [ ] `docs/openai-usage-grafana.md`: 사용자별 token 사용량 panel query를 `sum by (principal_alias, token_type) (...)` 형태로 수정한다.
- [ ] `docs/openai-usage-grafana.md`: legend와 query grouping label이 서로 맞는지 확인한다.

검증:

```bash
rg --fixed-strings "sum by (principal_alias, token_type)" docs/openai-usage-grafana.md
rg --fixed-strings "legend=\`{{principal_alias}} {{token_type}}\`" docs/openai-usage-grafana.md
```

## 수정 파일 요약

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

## 최종 검증

```bash
rg --fixed-strings "increase(iop_openai_usage_tokens_total[1d])" docs/openai-usage-grafana.md
rg --fixed-strings "increase(iop_openai_usage_tokens_total[30d])" docs/openai-usage-grafana.md
rg --fixed-strings "sum by (principal_alias, token_type)" docs/openai-usage-grafana.md
if rg --fixed-strings "increment(" docs/openai-usage-grafana.md; then exit 1; fi
if rg --fixed-strings "sum_over_time(iop_openai_usage_tokens_total" docs/openai-usage-grafana.md; then exit 1; fi
git diff --check
```

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