[johnnyeric]

Summary

Instrument usage persistence and queue processing with structured logs for ongoing diagnosis and log-derived counts and latency. Emit completion events at the shared persistence boundary with outcome, monotonic duration, event age, execution region and finite entrypoint/caller context. Keep staging completions and all failures at 100%; sample production recorded/duplicate completions uniformly at 1%, including sample_rate for estimated attempt counts. Add matching severity, acknowledgement/retry action, queue wait and separate writer-attempt timing to consumer logs.

Keep Worker logs in Cloudflare and document the lasting field contract. Only the usage-ingest consumer opts into the queue caller marker; classifier and benchmark writers keep their original headers and an unknown caller. Caller markers are diagnostic only and older clients remain compatible. Completion labels describe the actual persistence path; queue-only fallbacks require deployment flag context and the existing fallback warning. External log export remains off.

These signals also support direct-versus-queued staging load-test comparisons. Include a staging validation guide with read-only database snapshots to help evaluate that use case.

Verification

• Exercised the shipped staging Worker through local HTTP publishing and emulated Queues with a loopback fake writer. Observed recorded/duplicate acknowledgements and HTTP 503 retry, queue wait and measured writer delay; sensitive-data checks passed.
• Confirmed production and staging keep Cloudflare observability enabled, no Logpush opt-in or OpenTelemetry export destinations; both dry-run builds succeed.

Visual Changes

N/A

Reviewer Notes

Passed 140 focused handler/shared/client tests and 63 usage-ingest tests, including runtime tests, plus 458 auto-routing, 66 affected benchmark and 865 Worker-utils tests. Shared-package, Worker-utils, service and scoped writer-route typechecks, type-aware lint, formatting and generated Worker types pass.

Handler tests invoke the actual Next POST handler with mocked persistence; Worker runtime tests use emulated Queues and a fake writer. No hosted load test or DB snapshot execution was performed. Estimate completion attempt counts with sum(1 / sample_rate); sampled distinct IDs cannot establish exact completeness. Consumer logs remain at 100%, and existing slow phase diagnostics are unchanged. Hosted ingestion/sampling and exact persisted-row reconciliation remain separate operational concerns.

[kilo-code-bot]

Code Review Summary

Status: No Issues Found | Recommendation: Merge

Executive Summary

Full-diff review of 18 files found no new issues: caller context is allowlisted and never logged raw, completion logging preserves write results and exceptions, sampling is bounded and documented, and the previously raised test/doc suggestions are addressed.

Files Reviewed (18 files)

• apps/web/src/app/api/internal/usage/record/route.telemetry.test.ts
• apps/web/src/app/api/internal/usage/record/route.ts
• packages/web-shared/src/lib/ai-gateway/processUsage.ts
• packages/web-shared/src/lib/ai-gateway/usage-record-client.test.ts
• packages/web-shared/src/lib/ai-gateway/usage-record-client.ts
• packages/web-shared/src/lib/ai-gateway/usage-record-diagnostics.test.ts
• packages/web-shared/src/lib/ai-gateway/usage-record-diagnostics.ts
• packages/web-shared/src/lib/ai-gateway/usage-shadow-integration.test.ts
• packages/worker-utils/src/usage-writer-client.ts
• services/usage-ingest/README.md
• services/usage-ingest/load-test.md
• services/usage-ingest/src/consume-usage.runtime.test.ts
• services/usage-ingest/src/consume-usage.test.ts
• services/usage-ingest/src/consume-usage.ts
• services/usage-ingest/src/index.runtime.test.ts
• services/usage-ingest/src/receipt-usage.test.ts
• services/usage-ingest/src/receipt-usage.ts
• services/usage-ingest/src/usage-writer-client.test.ts

Previous Review Summaries (2 snapshots, latest commit 52ee6cb)

Current summary above is authoritative. Previous snapshots are kept for context only.

Previous review (commit 52ee6cb)

Status: 3 Issues Found | Recommendation: Address before merge

Executive Summary

The instrumentation logic is sound; the remaining findings are low-risk test-coverage and documentation-accuracy gaps in the new telemetry tests and staging runbook.

Overview

Severity	Count
CRITICAL	0
WARNING	0
SUGGESTION	3

Issue Details (click to expand)

SUGGESTION

File	Line	Issue
apps/web/src/app/api/internal/usage/record/route.telemetry.test.ts	53	The recorded fixture mirrors request values, so response assertions cannot detect returning the DB-shaped result.createdAt or the wrong result fields
packages/web-shared/src/lib/ai-gateway/usage-shadow-integration.test.ts	645	Leakage assertion checks a marker absent from this test's inputs, so it cannot fail
services/usage-ingest/load-test.md	84	queue_wait_ms docs claim intra-batch wait, but max_batch_size: 1 makes that impossible

Files Reviewed (18 files)

• apps/web/src/app/api/internal/usage/record/route.ts
• apps/web/src/app/api/internal/usage/record/route.telemetry.test.ts - 1 issue
• packages/web-shared/src/lib/ai-gateway/processUsage.ts
• packages/web-shared/src/lib/ai-gateway/usage-record-client.ts
• packages/web-shared/src/lib/ai-gateway/usage-record-client.test.ts
• packages/web-shared/src/lib/ai-gateway/usage-record-diagnostics.ts
• packages/web-shared/src/lib/ai-gateway/usage-record-diagnostics.test.ts
• packages/web-shared/src/lib/ai-gateway/usage-shadow-integration.test.ts - 1 issue
• packages/worker-utils/src/usage-writer-client.ts
• services/usage-ingest/README.md
• services/usage-ingest/load-test.md - 1 issue
• services/usage-ingest/src/consume-usage.ts
• services/usage-ingest/src/consume-usage.test.ts
• services/usage-ingest/src/consume-usage.runtime.test.ts
• services/usage-ingest/src/index.runtime.test.ts
• services/usage-ingest/src/receipt-usage.ts
• services/usage-ingest/src/receipt-usage.test.ts
• services/usage-ingest/src/usage-writer-client.test.ts

Fix these issues in Kilo Cloud

Previous review (commit bc646a5)

Status: 2 Issues Found | Recommendation: Address before merge

Executive Summary

The instrumentation changes are functionally sound; both findings are low-risk accuracy issues in a documentation claim and a test assertion.

Overview

Severity	Count
CRITICAL	0
WARNING	0
SUGGESTION	2

Issue Details (click to expand)

SUGGESTION

File	Line	Issue
services/usage-ingest/README.md	112	execution_region docs say it "always identifies where persistence ran", but the implementation maps missing/unexpected VERCEL_REGION to unknown (and load-test.md documents that fallback)
apps/web/src/app/api/internal/usage/record/route.telemetry.test.ts	104	Sensitive-data log assertion is vacuous: persistence is mocked and Math.random is pinned to 1, so logs is always empty

Files Reviewed (18 files)

• apps/web/src/app/api/internal/usage/record/route.ts
• apps/web/src/app/api/internal/usage/record/route.telemetry.test.ts - 1 issue
• packages/web-shared/src/lib/ai-gateway/processUsage.ts
• packages/web-shared/src/lib/ai-gateway/usage-record-client.ts
• packages/web-shared/src/lib/ai-gateway/usage-record-client.test.ts
• packages/web-shared/src/lib/ai-gateway/usage-record-diagnostics.ts
• packages/web-shared/src/lib/ai-gateway/usage-record-diagnostics.test.ts
• packages/web-shared/src/lib/ai-gateway/usage-shadow-integration.test.ts
• packages/worker-utils/src/usage-writer-client.ts
• services/usage-ingest/README.md - 1 issue
• services/usage-ingest/load-test.md
• services/usage-ingest/src/consume-usage.ts
• services/usage-ingest/src/consume-usage.test.ts
• services/usage-ingest/src/consume-usage.runtime.test.ts
• services/usage-ingest/src/index.runtime.test.ts
• services/usage-ingest/src/receipt-usage.ts
• services/usage-ingest/src/receipt-usage.test.ts
• services/usage-ingest/src/usage-writer-client.test.ts

Fix these issues in Kilo Cloud

---

_{Reviewed by deepseek-v4.1-flash-1017 · Input: 125.5K · Output: 33K · Cached: 2.3M}

_{Review guidance: REVIEW.md from base branch main}