toki
8a4f6c55a1
- Update roadmap milestones and phase docs across multiple phases - Update plan, code-review, create-roadmap, update-roadmap, finalize-task-routing skills - Update dev-corp-runtime-deploy, dev-runtime-deploy, orchestrate-agent-task-loop skills - Refactor agent-task-loop dispatch script - Add streamgate Go package (commit_boundary, evidence_tail, filter_registry, stream_release) - Add test inventory files (dev, dev-corp, unified) - Update test smoke tests and rules for dev/dev-corp - Update docs/edge-local-dev-guide and e2e scripts - Update inventory-query Go package - Remove deprecated templates and inventory.yaml files - Add orchestrate-agent-task-loop tests
110 lines
8.4 KiB
Markdown
110 lines
8.4 KiB
Markdown
# Milestone: 요청 실행 로그와 Usage Ledger 기반
|
|
|
|
## 위치
|
|
|
|
- Roadmap: [ROADMAP.md](../../../ROADMAP.md)
|
|
- Phase: [PHASE.md](../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/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 기반 추정을 허용할지 결정한다.
|
|
- [ ] 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 시도 기록 후보가 정리되어 있다.
|
|
|
|
### Epic: [run-trace-privacy] Tool Trace and Privacy
|
|
|
|
tool-call bridge 진단 정보와 민감 데이터 redaction 및 retention 경계를 묶는다.
|
|
|
|
- [ ] [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 기본값 후보가 정리되어 있다.
|
|
|
|
### Epic: [run-ledger-storage] Ledger Storage and Migration
|
|
|
|
request ledger의 저장·조회 책임과 기존 로그 체계에서의 도입 경계를 묶는다.
|
|
|
|
- [ ] [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는 명시적으로 켠 진단 모드로 제한한다.
|
|
- 우선순위: [OpenAI-compatible 출력 검증 필터](../../knowledge-tool-optimization-extension/milestones/openai-compatible-output-validation-filters.md)와 [Seulgivibe OpenAI-compatible Provider 연동](../../../archive/phase/routing-policy-model-orchestration/milestones/seulgivibe-openai-compatible-provider.md) 이후 재개한다.
|
|
- SDD gate: [SDD.md](../../../sdd/operational-observability-provider-management/request-execution-log-usage-ledger-foundation/SDD.md), 사용자 리뷰 [USER_REVIEW.md](../../../sdd/operational-observability-provider-management/request-execution-log-usage-ledger-foundation/USER_REVIEW.md)
|
|
- 선행 작업: 사용량, 토큰, 로그 운영 추적 MVP
|
|
- 후속 작업: Provider-Device-Model Qualification 리포트, 운영 리포트, 품질 기반 routing/fallback 고도화
|
|
- 확인 필요: ledger canonical owner, usage source 표시 정책, tool-call/raw chunk redaction과 capture 수준, redaction/retention 기본값, schema 분리 여부
|