iop/agent-roadmap/phase/operational-observability-provider-management/milestones/request-execution-log-usage-ledger-foundation.md

Milestone: 요청 실행 로그와 Usage Ledger 기반

위치

• Roadmap: ROADMAP.md
• Phase: 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 노출과 장기 보관 정책은 별도 결정으로 둔다. provider/tool-call bridge에서 native tool call, text fallback, synthesized tool call, raw tool-call leak, stream parse failure가 발생했는지 사후 판별할 수 있는 추적 기준도 포함한다.

상태

[스케치]

승격 조건

• 요청 실행 이벤트의 최소 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 응답에 포함할지 결정한다.
• provider raw response, native tool_calls, text fallback/synthesized tool_calls, raw tool-call leak, stream parse failure의 관측 지점과 저장 수준을 정의한다.
• prompt/response/reasoning preview redaction, raw payload 보관 여부, export 권한 경계를 결정한다.
• 기존 zap 로그, runtime event, audit/observability package, Control Plane operation history를 어떻게 migration 또는 병행 운용할지 결정한다.

구현 잠금

• 상태: 잠금
• SDD: 필요
• SDD 문서: 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 기반 추정을 허용할지 결정한다.
  • tool-call argument, provider raw chunk, parser error detail을 preview/hash/raw capture 중 어떤 수준으로 보관하고 어떻게 redaction할지 결정한다.
  • 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 기록
• native tool_calls, text_tool_fallback, synthesized_tool_calls, raw_tool_call_leaked, provider stream parse failure/retry/fallback 시도 기록
• 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 시도 기록 후보가 정리되어 있다.
• [tool-call-trace] provider/tool-call bridge에서 native tool_calls 수, text_tool_fallback, synthesized_tool_calls, raw_tool_call_leaked, parse failure/retry/fallback 시도와 redaction 기준이 정리되어 있다.
• [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/node/internal/adapters/vllm, apps/node/internal/adapters/ollama, 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로 명시해 정확도와 추정을 분리한다.
• 표준선(선택): tool-call 추적은 기본적으로 raw 원문 저장보다 run_id 기준 판정 필드, 길이, hash, 짧은 redacted preview를 우선하고, bounded raw capture는 명시적으로 켠 진단 모드로 제한한다.
• SDD gate: SDD.md, 사용자 리뷰 USER_REVIEW.md
• 선행 작업: 사용량, 토큰, 로그 운영 추적 MVP
• 후속 작업: Provider-Device-Model Qualification 리포트, 운영 리포트, 품질 기반 routing/fallback 고도화
• 확인 필요: ledger canonical owner, usage source 표시 정책, tool-call/raw chunk redaction과 capture 수준, redaction/retention 기본값, schema 분리 여부