From 29a00f5634a12eb670ed60070d1c6392ce5fbd90 Mon Sep 17 00:00:00 2001 From: toki Date: Thu, 25 Jun 2026 10:22:45 +0900 Subject: [PATCH] =?UTF-8?q?feat:=20operational-observability-provider-phas?= =?UTF-8?q?e=20=EC=97=85=EB=8D=B0=EC=9D=B4=ED=8A=B8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - PHASE.md 및 usage-token-log-ops-mvp.md 업데이트 - request-execution-log-usage-ledger-foundation.md 마일스톤 추가 - SDD 디렉터리 초기화 --- .../PHASE.md | 6 +- ...t-execution-log-usage-ledger-foundation.md | 93 ++++++++++++++ .../milestones/usage-token-log-ops-mvp.md | 30 +++-- .../SDD.md | 117 ++++++++++++++++++ .../USER_REVIEW.md | 77 ++++++++++++ 5 files changed, 314 insertions(+), 9 deletions(-) create mode 100644 agent-roadmap/phase/operational-observability-provider-management/milestones/request-execution-log-usage-ledger-foundation.md create mode 100644 agent-roadmap/sdd/operational-observability-provider-management/request-execution-log-usage-ledger-foundation/SDD.md create mode 100644 agent-roadmap/sdd/operational-observability-provider-management/request-execution-log-usage-ledger-foundation/USER_REVIEW.md diff --git a/agent-roadmap/phase/operational-observability-provider-management/PHASE.md b/agent-roadmap/phase/operational-observability-provider-management/PHASE.md index 11d1415..8557139 100644 --- a/agent-roadmap/phase/operational-observability-provider-management/PHASE.md +++ b/agent-roadmap/phase/operational-observability-provider-management/PHASE.md @@ -22,7 +22,11 @@ provider 확장 Phase에서 검증한 Ollama, vLLM, SGLang, Lemonade 같은 추 - [스케치] 사용량, 토큰, 로그 운영 추적 MVP - 경로: `agent-roadmap/phase/operational-observability-provider-management/milestones/usage-token-log-ops-mvp.md` - - 요약: 사용자 관리, token 관리, API/CLI/local inference 사용량 집계, 로그 관리의 1차 운영 경계를 스케치한다. + - 요약: 사용자 관리, token 관리, API/CLI/local inference 사용량 집계, 요청별 device/provider/time/token ledger, 로그 관리의 1차 운영 경계를 스케치한다. + +- [스케치] 요청 실행 로그와 Usage Ledger 기반 + - 경로: `agent-roadmap/phase/operational-observability-provider-management/milestones/request-execution-log-usage-ledger-foundation.md` + - 요약: 사용자 요청 하나의 device/provider/model 선택, queue/dispatch/start/first-token/end 시간, token breakdown, status/error를 구조화된 실행 로그와 usage ledger로 남기는 로그 시스템 개편 후보를 스케치한다. - [스케치] Provider-Device-Model Qualification 리포트와 Lifecycle 관리 - 경로: `agent-roadmap/phase/operational-observability-provider-management/milestones/provider-device-model-qualification-report.md` diff --git a/agent-roadmap/phase/operational-observability-provider-management/milestones/request-execution-log-usage-ledger-foundation.md b/agent-roadmap/phase/operational-observability-provider-management/milestones/request-execution-log-usage-ledger-foundation.md new file mode 100644 index 0000000..b01f6c3 --- /dev/null +++ b/agent-roadmap/phase/operational-observability-provider-management/milestones/request-execution-log-usage-ledger-foundation.md @@ -0,0 +1,93 @@ +# Milestone: 요청 실행 로그와 Usage Ledger 기반 + +## 위치 + +- Roadmap: `agent-roadmap/ROADMAP.md` +- Phase: `agent-roadmap/phase/operational-observability-provider-management/PHASE.md` + +## 목표 + +사용자 요청 하나를 기준으로 Edge, Node, provider/device/model, OpenAI-compatible 응답, Control Plane 운영 기록을 연결하는 구조화된 실행 로그와 usage ledger 기반을 스케치한다. +요청별 사용 device, 시작/종료/first-token 시간, queue wait, latency, token breakdown, error/status, usage source를 가능한 한 많이 수집하되 prompt/response 노출과 장기 보관 정책은 별도 결정으로 둔다. + +## 상태 + +[스케치] + +## 승격 조건 + +- [ ] 요청 실행 이벤트의 최소 lifecycle을 request accepted, queued, admitted, dispatched, provider started, first token, completed/error/cancelled로 정의한다. +- [ ] 요청별 ledger record의 canonical owner를 Edge-local store, Control Plane store, 또는 dual-write/replay 중 하나로 결정한다. +- [ ] input/cached input/think/output/total token을 provider-reported 값과 추정값으로 나누어 기록하는 source 정책을 결정한다. +- [ ] node/provider/device/model identity, run_id/request_id/session/user/workspace/source metadata를 어떤 로그와 API 응답에 포함할지 결정한다. +- [ ] prompt/response/reasoning preview redaction, raw payload 보관 여부, export 권한 경계를 결정한다. +- [ ] 기존 zap 로그, runtime event, audit/observability package, Control Plane operation history를 어떻게 migration 또는 병행 운용할지 결정한다. + +## 구현 잠금 + +- 상태: 잠금 +- SDD: 필요 +- SDD 문서: `agent-roadmap/sdd/operational-observability-provider-management/request-execution-log-usage-ledger-foundation/SDD.md` +- SDD 사유: 요청 실행 로그와 usage ledger는 proto/event/schema/storage/API, 데이터 보존, 권한, 실패 처리 경계를 함께 바꾸는 설계 Milestone이다. +- 잠금 해제 조건: 아래 체크리스트 + - [ ] SDD 잠금이 해제되어 있다. + - [ ] SDD 사용자 리뷰가 없거나 승인/해결되었다. + - [ ] Acceptance Scenario가 Milestone 기능 Task와 연결되어 있다. + - [ ] Evidence Map이 완료 시 `Roadmap Completion`과 최종 검증 evidence로 검증 가능하게 연결되어 있다. +- 결정 필요: 아래 체크리스트 + - [ ] request ledger의 canonical 저장 책임을 Edge와 Control Plane 중 어디에 둘지 결정한다. + - [ ] token usage source가 provider-reported, estimated, mixed, unavailable일 때 운영 UI와 export에서 어떻게 표시할지 결정한다. + - [ ] hidden think/reasoning token을 provider가 보고하지 않는 경우 표시 reasoning text 기반 추정을 허용할지 결정한다. + - [ ] full prompt/response, preview, metadata, error detail의 redaction과 retention 기본값을 결정한다. + - [ ] 로그 개편을 기존 runtime event schema 확장으로 할지, 별도 request ledger/audit event schema로 분리할지 결정한다. + +## 범위 + +- 요청 실행 lifecycle별 timestamp와 correlation id 정의 +- 요청별 사용 device/provider/node/model alias/served model 기록 +- input, cached input, think/reasoning, output, total token usage와 source 표시 +- queue wait, TTFT, provider duration, total duration, status/error 기록 +- Edge/Node/Control Plane 로그와 run event, audit/observability package의 연결 방식 +- 운영 조회/export를 위한 최소 ledger query 후보 + +## 기능 + +### Epic: [run-ledger] Request Execution Ledger + +요청 하나를 운영자가 나중에 재구성할 수 있도록 lifecycle, device routing, token usage, 결과 상태를 연결하는 capability를 묶는다. + +- [ ] [event-lifecycle] request accepted, queued, admitted, dispatched, provider started, first token, completed/error/cancelled 이벤트와 timestamp 의미가 정리되어 있다. +- [ ] [identity-correlation] request_id, run_id, session_id, user/token scope, workspace, source, node_id, provider_id, device_id, model alias, served model의 correlation 기준이 정리되어 있다. +- [ ] [token-usage] input, cached input, think/reasoning, output, total token 필드와 provider-reported/estimated/mixed/unavailable source 정책이 정리되어 있다. +- [ ] [latency-metrics] queue wait, TTFT, provider duration, stream duration, total duration, retry/fallback 시도 기록 후보가 정리되어 있다. +- [ ] [log-redaction] prompt/response/reasoning preview, metadata, error detail의 redaction과 retention 기본값 후보가 정리되어 있다. +- [ ] [storage-query] Edge-local store, Control Plane operation history, export API/CLI/Client 조회 후보와 canonical owner가 정리되어 있다. +- [ ] [migration-plan] 기존 zap 로그와 runtime event를 유지하면서 request ledger를 추가하는 migration 또는 병행 운용 전략이 정리되어 있다. + +## 완료 리뷰 + +- 상태: 없음 +- 요청일: 없음 +- 완료 근거: 스케치 Milestone이며 기능 Task가 아직 충족되지 않았다. +- 리뷰 필요: + - [ ] 사용자가 완료 결과를 확인했다 + - [ ] archive 이동을 승인했다 +- 리뷰 코멘트: 없음 + +## 범위 제외 + +- 실제 proto/schema/storage/API 구현 +- 장기 retention, billing, chargeback, 조직 IAM +- provider routing 알고리즘 변경 +- provider가 보고하지 않는 hidden reasoning token의 완전 정확한 복원 +- 품질 평가나 route recommendation 자동화 + +## 작업 컨텍스트 + +- 관련 경로: `apps/edge/internal/openai`, `apps/edge/internal/service`, `apps/node/internal/node`, `apps/node/internal/adapters/openai_compat`, `apps/control-plane`, `apps/client`, `packages/go/audit`, `packages/go/observability`, `proto/iop/runtime.proto` +- 표준선(선택): Edge는 runtime execution과 provider routing의 원본 이벤트를 가장 먼저 알고, Control Plane은 연결 view와 운영 조회/export 표면을 제공한다. +- 표준선(선택): usage는 provider-reported 값을 우선하고, provider가 주지 않는 값은 estimated 또는 unavailable로 명시해 정확도와 추정을 분리한다. +- SDD gate: `agent-roadmap/sdd/operational-observability-provider-management/request-execution-log-usage-ledger-foundation/SDD.md`, 사용자 리뷰 `USER_REVIEW.md` +- 선행 작업: 사용량, 토큰, 로그 운영 추적 MVP +- 후속 작업: Provider-Device-Model Qualification 리포트, 운영 리포트, 품질 기반 routing/fallback 고도화 +- 확인 필요: ledger canonical owner, usage source 표시 정책, redaction/retention 기본값, schema 분리 여부 diff --git a/agent-roadmap/phase/operational-observability-provider-management/milestones/usage-token-log-ops-mvp.md b/agent-roadmap/phase/operational-observability-provider-management/milestones/usage-token-log-ops-mvp.md index 20ded0d..5107d92 100644 --- a/agent-roadmap/phase/operational-observability-provider-management/milestones/usage-token-log-ops-mvp.md +++ b/agent-roadmap/phase/operational-observability-provider-management/milestones/usage-token-log-ops-mvp.md @@ -9,6 +9,7 @@ 사용자 관리, token 관리, API/CLI/local inference 사용량 집계, 로그 관리를 1차 MVP 운영 축으로 스케치한다. 이미 존재하는 runtime usage, CLI usage status, audit/observability 패키지와 Control Plane/Client 운영 표면을 기준으로 삼되, 구체 schema와 저장소 구현은 후속 구체화 전까지 확정하지 않는다. +사용자 요청 하나가 어떤 device/provider/node/model로 처리되었는지, 언제 시작/종료되었는지, input/think/output token을 얼마나 사용했는지 추적 가능한 운영 기록을 MVP 핵심 후보로 둔다. ## 상태 @@ -17,22 +18,30 @@ ## 승격 조건 - [ ] 1차 MVP에서 관리할 사용자/token 범위와 운영 주체를 결정한다. -- [ ] API, CLI, local inference 사용량을 어떤 단위로 집계할지 결정한다. -- [ ] 로그 관리의 최소 범위와 보관/조회 책임 경계를 결정한다. +- [ ] API, CLI, local inference 사용량을 요청, run, session, user, provider/device/model 중 어떤 단위로 집계할지 결정한다. +- [ ] 요청별 input token, cached input token, think/reasoning token, output token, total token을 어떤 provider-reported/estimated 기준으로 기록할지 결정한다. +- [ ] 요청별 사용 device/provider/node, model alias/served model, queue/dispatch/start/first-token/end timestamp, duration, status/error를 어느 이벤트와 저장소에 남길지 결정한다. +- [ ] 로그 관리의 최소 범위, 보관/조회/export 책임 경계, prompt/response preview redaction 정책을 결정한다. - [ ] Control Plane, Edge-local CLI, Client 중 어떤 표면을 MVP에 포함할지 결정한다. ## 구현 잠금 - 상태: 잠금 +- SDD: 불필요 +- SDD 사유: 현재 Milestone은 운영 범위와 산출물 스케치이며, proto/schema/storage/API 구현 전 별도 구체화에서 SDD 필요 여부를 재판정한다. - 결정 필요: 아래 체크리스트 - [ ] 사용자와 token을 개인/Edge/조직 중 어떤 단위로 시작할지 결정한다. - - [ ] 사용량 집계의 MVP 단위를 요청, token, runtime duration, CLI limit status 중 어디까지로 둘지 결정한다. + - [ ] 사용량 집계의 MVP 단위를 요청, token, runtime duration, CLI limit status, provider/device throughput 중 어디까지로 둘지 결정한다. + - [ ] think/reasoning token을 provider-reported 값만 신뢰할지, 표시된 reasoning text 기반 추정치를 함께 둘지 결정한다. + - [ ] 요청별 device/provider 사용 기록을 사용자 로그, audit log, 성능 ledger 중 어디에 canonical하게 둘지 결정한다. - [ ] 로그 조회와 export의 MVP 표면을 Control Plane/Client/CLI 중 어디에 둘지 결정한다. ## 범위 - 사용자 관리와 token 관리의 1차 운영 경계 - API, CLI, local inference 사용량 집계의 MVP 산출물 정의 +- 요청별 run ledger: user/session/workspace/source/request_id/run_id, 사용 device/provider/node/model, queue/dispatch/start/first-token/end timestamp, status/error +- token ledger: input, cached input, think/reasoning, output, total token과 provider-reported/estimated/unavailable source 표시 - Edge/Node/Control Plane 로그 관리의 최소 조회 경계 - 기존 `Usage`, CLI usage status, audit/observability 패키지와 연결 가능한 표준선 정리 @@ -43,8 +52,11 @@ 운영자가 사용량과 로그를 한 곳에서 이해하기 위한 최소 capability를 묶는다. - [ ] [identity-scope] 사용자와 token 관리의 MVP 책임 경계가 정리되어 있다. -- [ ] [usage-rollup] API, CLI, local inference 사용량 집계 후보와 제외 범위가 정리되어 있다. -- [ ] [log-surface] Edge/Node/Control Plane 로그 조회와 export의 최소 표면 후보가 정리되어 있다. +- [ ] [usage-rollup] API, CLI, local inference 사용량 집계 후보와 제외 범위가 요청/run/session/user/provider/device/model 단위로 정리되어 있다. +- [ ] [request-ledger] 사용자 요청별 사용 device/provider/node/model, run_id/request_id, queue/dispatch/start/first-token/end timestamp, duration, status/error를 남기는 MVP ledger 후보가 정리되어 있다. +- [ ] [token-breakdown] input, cached input, think/reasoning, output, total token과 usage source(provider-reported/estimated/mixed/unavailable) 기준이 정리되어 있다. +- [ ] [usage-collection] OpenAI-compatible streaming usage, provider별 native usage, CLI usage status, 추정 token count를 어떤 우선순위로 수집할지 정리되어 있다. +- [ ] [log-surface] Edge/Node/Control Plane 로그 조회와 export의 최소 표면 후보가 redaction/preview 정책과 함께 정리되어 있다. - [ ] [ops-review] 사용자가 MVP 운영 범위와 후속 구체화 우선순위를 검토했다. ## 완료 리뷰 @@ -62,11 +74,13 @@ - 결제, chargeback, 조직 IAM, 장기 retention 정책의 상세 구현 - 모든 로그 schema와 audit schema 확정 - provider routing 또는 inference adapter 구현 +- hidden reasoning token을 provider가 보고하지 않는 경우의 완전 정확한 복원 ## 작업 컨텍스트 -- 관련 경로: `apps/control-plane`, `apps/client`, `apps/edge`, `apps/node`, `packages/go/audit`, `packages/go/observability`, `proto/iop/runtime.proto` +- 관련 경로: `apps/control-plane`, `apps/client`, `apps/edge`, `apps/node`, `packages/go/audit`, `packages/go/observability`, `proto/iop/runtime.proto`, `apps/edge/internal/openai`, `apps/node/internal/adapters/openai_compat` - 표준선(선택): Edge는 로컬 runtime 상태의 원본을 유지하고, Control Plane은 연결 view와 운영 기록을 보기 쉽게 제공한다. +- 표준선(선택): provider가 usage를 보고하면 provider-reported 값을 우선하고, 보고하지 않는 필드는 estimated/unavailable source를 명시한다. - 선행 작업: Control Plane과 Client 운영, OpenAI-compatible usage 응답, CLI usage checker -- 후속 작업: 운영 리포트, audit retention, 품질 기반 routing/fallback 고도화 -- 확인 필요: 사용자/token 단위, 사용량 집계 단위, 로그 관리 표면 +- 후속 작업: 요청 실행 로그와 Usage Ledger 기반, 운영 리포트, audit retention, 품질 기반 routing/fallback 고도화 +- 확인 필요: 사용자/token 단위, 사용량 집계 단위, think token 신뢰 기준, 로그 관리 표면 diff --git a/agent-roadmap/sdd/operational-observability-provider-management/request-execution-log-usage-ledger-foundation/SDD.md b/agent-roadmap/sdd/operational-observability-provider-management/request-execution-log-usage-ledger-foundation/SDD.md new file mode 100644 index 0000000..52e142b --- /dev/null +++ b/agent-roadmap/sdd/operational-observability-provider-management/request-execution-log-usage-ledger-foundation/SDD.md @@ -0,0 +1,117 @@ +# SDD: 요청 실행 로그와 Usage Ledger 기반 + +## 위치 + +- Milestone: `agent-roadmap/phase/operational-observability-provider-management/milestones/request-execution-log-usage-ledger-foundation.md` +- Phase: `agent-roadmap/phase/operational-observability-provider-management/PHASE.md` + +## 상태 + +[초안] + +## SDD 잠금 + +- 상태: 잠금 +- 사용자 리뷰: `USER_REVIEW.md` +- 잠금 항목: + - [ ] [D01] request ledger의 canonical 저장 책임을 Edge와 Control Plane 중 어디에 둘지 결정한다. + - [ ] [D02] provider-reported, estimated, mixed, unavailable usage source를 운영 UI와 export에서 어떻게 표시할지 결정한다. + - [ ] [D03] provider가 hidden think/reasoning token을 보고하지 않는 경우 표시 reasoning text 기반 추정치를 허용할지 결정한다. + - [ ] [D04] full prompt/response, preview, metadata, error detail의 redaction과 retention 기본값을 결정한다. + - [ ] [D05] 기존 runtime event 확장과 별도 request ledger/audit event schema 중 기본 구현 경계를 결정한다. + +## 문제 / 비목표 + +- 문제: 현재 IOP는 OpenAI-compatible 요청의 device/provider dispatch, 시작/종료 시간, queue wait, token breakdown, status/error를 요청 단위로 재구성하기 어렵다. 운영자는 provider 효율, 사용자별 사용량, 문제 요청의 원인, prompt/response 보관 범위를 한 기록에서 확인할 수 있어야 한다. +- 비목표: + - billing, chargeback, 조직 IAM, 장기 retention 정책 구현 + - provider routing 알고리즘 변경 + - provider가 보고하지 않는 hidden reasoning token의 완전 정확한 복원 + - 품질 평가나 route recommendation 자동화 + +## Source of Truth + +| 영역 | 기준 | 메모 | +|------|------|------| +| Roadmap | `agent-roadmap/phase/operational-observability-provider-management/milestones/request-execution-log-usage-ledger-foundation.md` | Milestone 목표, 기능 Task, 잠금 항목 기준 | +| Code | `apps/edge/internal/openai`, `apps/edge/internal/service`, `apps/node/internal/node`, `apps/node/internal/adapters/openai_compat`, `proto/iop/runtime.proto` | OpenAI-compatible input, dispatch, runtime event, usage propagation 구현 기준 | +| External Provider | OpenAI-compatible provider usage chunk | provider-reported token usage가 있으면 우선 사용하고, 없으면 estimated/unavailable로 표시 | +| User Decision | D01-D05 | 저장 책임, usage source 표시, reasoning token 추정, redaction/retention, schema 분리 결정 필요 | + +## State Machine + +| 상태 | 진입 조건 | 다음 상태 | 근거 | +|------|-----------|-----------|------| +| accepted | Edge OpenAI-compatible 또는 native 실행 요청을 수신했다 | queued 또는 dispatched | request_id/run_id 생성, source metadata | +| queued | model group/provider capacity가 가득 차 요청이 대기한다 | admitted 또는 cancelled/error | queue admission event | +| admitted | scheduler가 provider slot을 예약했다 | dispatched 또는 error | provider_id/node_id/model selection | +| dispatched | Edge가 Node에 RunRequest를 보냈다 | provider_started 또는 error | RunRequest dispatch result | +| provider_started | Node adapter가 provider request를 시작했다 | first_token 또는 completed/error | Node runtime event 또는 adapter execution log | +| first_token | 첫 delta 또는 reasoning_delta가 관측되었다 | completed/error/cancelled | runtime stream event timestamp | +| completed | provider/adapter가 complete event를 보냈다 | 없음 | complete event, usage, finish_reason | +| error | Edge, Node, provider, queue 중 하나가 실패했다 | 없음 | error event와 error detail | +| cancelled | 사용자 또는 runtime이 취소했다 | 없음 | cancel event | + +## Interface Contract + +- 계약 원문: 없음 +- 입력: + - `request_id`: 외부 요청 또는 Edge-generated 요청 correlation id + - `run_id`: Node runtime 실행 correlation id + - `metadata.user/session/workspace/source`: 사용자, session, workspace, 호출 표면 식별 + - `model` / `served_model`: 외부 model alias와 provider 실제 served model + - `provider_id` / `node_id` / `device_id`: 선택된 실행 위치 식별 + - `usage`: input, cached input, think/reasoning, output, total token과 source 표시 +- 출력: + - 요청별 실행 ledger record + - provider/device/model별 usage와 latency rollup 후보 + - 운영 UI/CLI/export에서 조회 가능한 redacted request summary +- 금지: + - provider가 보고하지 않은 token을 provider-reported처럼 표시하지 않는다. + - hidden reasoning token을 표시 reasoning text 추정치와 혼동하지 않는다. + - prompt/response 원문 보관 여부를 SDD 사용자 결정 없이 기본값으로 확정하지 않는다. + +## Acceptance Scenarios + +| ID | Milestone Task | Given | When | Then | +|----|----------------|-------|------|------| +| S01 | `event-lifecycle` | OpenAI-compatible 요청이 들어온다 | 요청이 queue, dispatch, provider, stream, complete 또는 error 경로를 지난다 | lifecycle별 timestamp 의미와 event source가 문서화되어 있다 | +| S02 | `identity-correlation` | 요청이 provider pool을 통해 특정 Node/provider/model로 라우팅된다 | 운영자가 run을 조회한다 | request_id, run_id, user/session/workspace/source, node/provider/device/model correlation 기준이 문서화되어 있다 | +| S03 | `token-usage` | provider가 usage를 보고하거나 보고하지 않는다 | complete event 또는 response usage를 구성한다 | provider-reported/estimated/mixed/unavailable source 정책과 token breakdown 필드가 문서화되어 있다 | +| S04 | `latency-metrics` | 요청이 대기, 실행, streaming 단계를 지난다 | 운영자가 latency를 비교한다 | queue wait, TTFT, provider duration, stream duration, total duration 후보가 문서화되어 있다 | +| S05 | `log-redaction` | 요청/응답/metadata/error detail이 ledger에 남는다 | 운영 UI 또는 export가 기록을 표시한다 | preview/redaction/retention 기본값 후보와 사용자 결정 항목이 분리되어 있다 | +| S06 | `storage-query` | Edge와 Control Plane이 모두 운영 기록 후보를 가질 수 있다 | 저장/조회 경계를 설계한다 | canonical owner와 조회/export 후보가 사용자 결정 항목으로 정리되어 있다 | +| S07 | `migration-plan` | 기존 zap log, runtime event, Control Plane operation history가 존재한다 | request ledger를 추가한다 | 병행 운용 또는 migration 전략 후보가 문서화되어 있다 | + +## Evidence Map + +| Scenario | Required Evidence | `agent-task` 연결 | 완료 Evidence 기대 | +|----------|-------------------|------------------|---------------------------| +| S01 | Milestone 문서와 SDD에서 lifecycle 표와 event source 확인 | `agent-task/m-request-execution-log-usage-ledger-foundation/...` | `Roadmap Completion`에 `event-lifecycle`와 S01 충족 근거 | +| S02 | correlation field 목록과 provider/device/model identity mapping 확인 | `agent-task/m-request-execution-log-usage-ledger-foundation/...` | `Roadmap Completion`에 `identity-correlation`와 S02 충족 근거 | +| S03 | usage field/source 정책과 provider-reported/estimated 구분 확인 | `agent-task/m-request-execution-log-usage-ledger-foundation/...` | `Roadmap Completion`에 `token-usage`와 S03 충족 근거 | +| S04 | latency metric 후보와 timestamp 계산 기준 확인 | `agent-task/m-request-execution-log-usage-ledger-foundation/...` | `Roadmap Completion`에 `latency-metrics`와 S04 충족 근거 | +| S05 | redaction/retention 결정 항목과 기본 후보 확인 | `agent-task/m-request-execution-log-usage-ledger-foundation/...` | `Roadmap Completion`에 `log-redaction`와 S05 충족 근거 | +| S06 | canonical owner 사용자 리뷰 해결 또는 결정 기록 확인 | `agent-task/m-request-execution-log-usage-ledger-foundation/...` | `Roadmap Completion`에 `storage-query`와 S06 충족 근거 | +| S07 | 기존 로그/event와 새 ledger 병행 또는 migration 전략 확인 | `agent-task/m-request-execution-log-usage-ledger-foundation/...` | `Roadmap Completion`에 `migration-plan`와 S07 충족 근거 | + +## Cross-repo Dependencies + +- 없음 + +## Drift Check + +- [ ] Milestone 기능 Task와 Acceptance Scenario가 일치한다. +- [ ] Evidence Map이 code-review/complete.log에서 검증 가능하다. +- [ ] agent-contract를 쓰는 경우 SDD에 계약 원문을 복제하지 않았다. +- [ ] 사용자 리뷰가 필요한 항목은 `USER_REVIEW.md`에만 남겼다. + +## 사용자 리뷰 이력 + +- 없음 + +## 작업 컨텍스트 + +- 표준선: Edge는 runtime execution과 provider routing의 원본 이벤트를 가장 먼저 알고, Control Plane은 연결 view와 운영 조회/export 표면을 제공한다. +- 표준선: usage는 provider-reported 값을 우선하고, provider가 주지 않는 값은 estimated 또는 unavailable로 명시해 정확도와 추정을 분리한다. +- 후속 SDD: 없음 diff --git a/agent-roadmap/sdd/operational-observability-provider-management/request-execution-log-usage-ledger-foundation/USER_REVIEW.md b/agent-roadmap/sdd/operational-observability-provider-management/request-execution-log-usage-ledger-foundation/USER_REVIEW.md new file mode 100644 index 0000000..492a3dc --- /dev/null +++ b/agent-roadmap/sdd/operational-observability-provider-management/request-execution-log-usage-ledger-foundation/USER_REVIEW.md @@ -0,0 +1,77 @@ +# SDD User Review + +## 상태 + +요청됨 + +## 검토 대상 + +- SDD: `agent-roadmap/sdd/operational-observability-provider-management/request-execution-log-usage-ledger-foundation/SDD.md` +- Milestone: `agent-roadmap/phase/operational-observability-provider-management/milestones/request-execution-log-usage-ledger-foundation.md` + +## 사용자 결정 항목 + +### [D01] Ledger 저장 책임 + +- 결정 필요: 요청별 request ledger의 canonical 저장 책임을 Edge-local store, Control Plane store, 또는 Edge 원본 + Control Plane replica 중 어디에 둘지 결정해야 한다. +- 추천안: Edge를 원본으로 두고 Control Plane은 조회/export용 replica 또는 relay view로 시작한다. +- 대안: Control Plane을 원본으로 두거나, MVP에서는 Edge-local CLI 조회만 제공한다. +- 영향: source of truth, 장애 복구, 다중 Control Plane 전환, export API, 저장소 schema 경계에 영향을 준다. +- 적용 위치: + - SDD: `Source of Truth`, `Interface Contract`, `Acceptance Scenarios` + - Milestone: `storage-query`, `구현 잠금` + +### [D02] Usage Source 표시 정책 + +- 결정 필요: provider-reported, estimated, mixed, unavailable usage source를 운영 UI와 export에서 어떤 기본 표현으로 보여줄지 결정해야 한다. +- 추천안: 모든 token 필드에 source를 함께 저장하고, rollup에서는 provider-reported와 estimated를 기본적으로 분리해 표시한다. +- 대안: total token만 source를 표시하거나, estimated 값을 기본 rollup에 포함하지 않는다. +- 영향: provider 효율 비교, 사용자별 사용량 통계, 비용/성능 판단 정확도에 영향을 준다. +- 적용 위치: + - SDD: `Interface Contract`, `Acceptance Scenarios` + - Milestone: `token-usage` + +### [D03] Think/Reasoning Token 추정 + +- 결정 필요: provider가 hidden think/reasoning token을 보고하지 않는 경우 표시된 reasoning text 기반 추정치를 별도 필드로 허용할지 결정해야 한다. +- 추천안: provider-reported reasoning token만 canonical `reasoning_tokens`로 두고, 표시 reasoning text 기반 값은 `reasoning_tokens_estimated`처럼 별도 추정 필드로만 둔다. +- 대안: 추정치를 MVP에서 아예 제외하거나, output token에 합산한다. +- 영향: 모델/provider 비교, hidden reasoning 비용 추정, 사용자 로그 신뢰도에 영향을 준다. +- 적용 위치: + - SDD: `Interface Contract` + - Milestone: `token-usage` + +### [D04] Redaction과 Retention 기본값 + +- 결정 필요: prompt/response/reasoning 원문, preview, metadata, error detail의 기본 보관 범위와 redaction 정책을 결정해야 한다. +- 추천안: MVP 기본값은 원문 미보관, redacted preview와 metadata summary만 저장하고, raw payload export는 별도 opt-in으로 둔다. +- 대안: Edge-local에 raw payload를 짧게 보관하거나, 운영자 권한이 있으면 Control Plane에서 raw 조회를 허용한다. +- 영향: 보안, 개인 정보, 저장 비용, 디버깅 깊이, 사용자 신뢰에 영향을 준다. +- 적용 위치: + - SDD: `Interface Contract`, `Acceptance Scenarios` + - Milestone: `log-redaction` + +### [D05] Schema 분리 방식 + +- 결정 필요: 기존 `RunEvent`/runtime event schema를 확장할지, 별도 request ledger/audit event schema를 둘지 결정해야 한다. +- 추천안: runtime stream의 `RunEvent`는 실행 중 이벤트로 유지하고, 완료/관측용 request ledger record를 별도 schema로 둔다. 필요한 correlation 필드만 runtime event에 보강한다. +- 대안: `RunEvent`를 확장해 ledger까지 흡수하거나, audit event만 확장한다. +- 영향: proto 변경 범위, Edge/Node/Control Plane 책임 경계, 과거 로그 migration, client UI parsing에 영향을 준다. +- 적용 위치: + - SDD: `Interface Contract`, `State Machine` + - Milestone: `migration-plan` + +## 승인 항목 + +- [ ] 위 결정 항목을 승인했다. +- [ ] SDD 잠금 해제를 승인했다. + +## 답변 기록 + +- 없음 + +## 해결 조건 + +- 모든 사용자 결정 항목의 답변이 SDD에 반영되어 있다. +- `USER_REVIEW.md`가 `user_review_N.log`로 이동되어 있다. +- 남은 잠금 항목이 없으면 SDD 상태가 `[승인됨]`이고 `SDD 잠금` 상태가 `해제`다.