feat(usage): show cache metrics by model

[xdober]

Summary

The Usage page's Models table now shows input tokens, output tokens, cache hits, cache writes, and cache hit rate for each model. When a provider does not report cache telemetry, the cache cells display an em dash. The change also adds translations for all supported GUI locales, documents the new metrics, and includes a rendered GUI regression test.

Verification

• bun run typecheck
• bun run test:changed — 164 passed, 0 failed
• GUI lint, i18n lint, and GUI build
• Usage focused tests — 28 passed; usage layout tests — 9 passed; GUI tests — 2,064 passed
• Documentation site build — 441 pages passed
• git diff --check

Checklist

• Scope stays focused and avoids unrelated cleanup.
• Docs or release notes were updated when needed.
• Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults.

Review readiness checklist

• All CI tests are green on my local testing.
• I pushed my PR to the latest dev commit.
• I resolved all correct Codex and CodeRabbit findings.
• My PR is ready for review.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

✅ Deterministic PR hygiene checks passed.

[github-actions]

⏳ DRAFT

• review readiness checklist open (0/4 boxes ticked).

What to do

• Tick all four boxes in the PR description once you're done (currently 0/4).

Review readiness checklist

• ⬜ All CI tests are green on my local testing.
• ⬜ I pushed my PR to the latest dev commit.
• ⬜ I resolved all correct Codex and CodeRabbit findings.
• ⬜ My PR is ready for review.

0/4 boxes ticked.

This PR stays in draft until every box above is ticked.

[lidge-jun]

리뷰 · 우선순위 54 / 80

이 PR은 Usage 페이지의 Models 표를 넓혀서, 모델마다 입력 토큰·출력 토큰·캐시 히트·캐시 쓰기·캐시 히트율을 한눈에 보게 합니다. 지금 dev HEAD(ada3a9b1b, #4792 bare tool-name echo) 기준으로 보면, 백엔드 src/usage/summary.ts의 UsageModel에는 이미 cachedInputTokens / cacheReadInputTokens / cacheCreationInputTokens / cacheHitRate가 실려 나갑니다. 그런데 GUI gui/src/pages/Usage.tsx의 Models 표는 요청 수·측정 수·총 토큰·비중만 보여 주고, 캐시 숫자는 위쪽 Summary 카드(usage.card.cachedTokens)에만 모여 있었습니다. 그래서 이 PR은 새 집계 로직을 만들기보다, 이미 API가 주는 필드를 표 칸으로 꺼내는 GUI·i18n·문서·회귀 테스트 묶음입니다.

왜 지금 보면 쓸모가 있냐면, 캐시 히트는 비용·지연 체감에 바로 이어지는데 모델별로 갈리면 어디가 잘 맞고 어디가 텔레메트리가 비는지 바로 보입니다. 제공자가 캐시 숫자를 안 주면 칸에 em dash(—)를 넣는 것도 맞습니다. formatOptionalTokens / formatOptionalPct가 undefined·null·비유한 숫자를 걸러 주고, 히트 칸은 cacheReadInputTokens ?? cachedInputTokens로 예전·새 필드 이름을 같이 받습니다. Summary 카드가 쓰던 것과 같은 폴백이라 화면끼리 말이 맞습니다.

범위도 비교적 작습니다. 손대는 곳은 Usage.tsx Models 표, 9개 GUI 로케일 키, web-dashboard.md 한 줄, usage-custom-range 회귀 테스트, PR 스크린샷입니다. types.ts/config.ts 대분할과 충돌하는 경로도 아니고, base가 지금 dev tip(ada3a9b1b)이라 리베이스 빚도 거의 없습니다. 다만 아직 draft이고 본문 체크리스트가 비어 있으며, Cross-platform CI·React Doctor는 action_required로 본검사가 아직 안 돈 상태입니다. 로컬에서 돌렸다는 말은 있지만, 호스티드 CI 초록을 보기 전에는 랜딩 후보로 올리면 안 됩니다.

한 가지 더: Summary에는 이미 전체 캐시 카드가 있는데, Models에만 입력/출력/캐시 칸을 넣고 Providers 표(UsageProvidersTable)는 예전 그대로입니다. 백엔드 UsageProvider에도 같은 캐시 필드가 있으니, 모델만 디테일하고 제공자 쪽은 총 토큰만 보이는 비대칭이 생깁니다. 또 히트율은 calculateCacheHitRate가 cacheObservedInputTokens 분모로 계산하는데, 표에는 분모/관찰 여부를 안 보여 줘서 일부 행만 캐시를 잰 모델의 %를 과신할 수 있습니다. 열을 다섯 개나 늘려서 좁은 화면에서 가로로 빡빡해질 수도 있습니다(tbl-wrap은 세로 스크롤 위주).

정리하면, 방향은 맞고 dev 현재 축(응답 패스스루·토큰 리프레시 등)을 깨지 않는 대시보드 다듬기입니다. draft를 Ready로 올리고 호스티드 CI가 통과한 뒤, Providers 대칭·히트율 분모 힌트만 메인테이너가 원하면 같이 넣고 머지하면 됩니다. 당장 닫을 중복·무효 PR은 아닙니다.

라인 70-73 - UsageModel에 캐시 필드를 optional로 넣은 건 맞지만, API의 cacheObservedInputTokens는 안 받아서 히트율이 부분 관찰인지 GUI가 구분 못 함
라인 116-121 - formatOptionalPct는 null/비유한을 — 로 잘 처리하지만, 분모가 작을 때 높은 %가 나와도 경고·title이 없음
라인 676-680 - Models 표에 입력/출력/캐시 열 5개를 한꺼번에 추가해 열이 11개로 늘어남. 좁은 뷰포트·기존 tbl-wrap 세로 스크롤만으로는 가로 가독성이 빡빡할 수 있음
라인 692-696 - 캐시 히트는 cacheReadInputTokens ?? cachedInputTokens로 Summary와 맞췄고, 없는 값은 — 처리라 좋음. 다만 입력/출력은 항상 formatTokens라 0도 숫자로 보여서, 캐시 — 와 섞이면 “측정 안 됨” vs “진짜 0” 느낌이 칸마다 다름
gui/src/pages/Usage.tsx UsageProvidersTable - Providers 쪽은 같은 캐시 필드를 API가 주는데 표는 안 보여 줘서 Models만 디테일해짐
.github/pr-assets/opencodex-cache-usage.png - PR 설명용 PNG가 저장소에 영구 커밋됨. 랜딩 후 자산 유지가 필요한지 한 번만 정하면 됨
PR 상태 - draft + 체크리스트 미체크 + Cross-platform CI/React Doctor action_required. 본검사 초록 전에는 Ready/머지 대상 아님

메인테이너의 판단이 필요한 지점

• Providers 표에도 같은 캐시 열을 이 PR에서 같이 넣을지, 후속 PR로 미룰지
• 히트율 옆에 cacheObservedInputTokens 힌트(title·캡션)를 필수할지, %만으로 충분한지
• .github/pr-assets 스크린샷을 트리에 남길지, PR 본문 첨부만으로 둘지
• draft 기여자가 Ready로 올리기 전에 메인테이너가 CI 승인만 해 줄지

너의 추천
draft를 Ready로 올린 뒤 호스티드 Cross-platform CI·관련 GUI 검사가 초록인지 확인하고, Providers 대칭·히트율 분모 힌트는 원하면 작은 후속 커밋으로 붙인 다음 머지하세요. 지금은 리뷰·대기만 하고 닫지 마세요. types/config 분할에 무효화될 경로도 아닙니다.

이 댓글은 grok-bot이 작성했습니다