Skip to content

Instrument KV cache tiers and enforce matched performance promotion gates #1647

Description

@i386

Context

PR #1632 adds an exact node-local durable L3 cache, but every optimization added to that work needs a matched before/after gate. This issue owns the measurement contract for the expanded KV-tier work; it complements the broader cache telemetry in #1097.

The current L3 implementation can produce roughly 9,500 geometry-aligned segment references for a realistic 19K-token prefix. Storage layout, copying, I/O scheduling, admission, and tier routing therefore need measurements that expose where time and bytes are actually spent.

Coordinated in Buzz channel #skippy-kv.

Work

  • Add phase timings for lookup, export, encode, queue, write, read, verify, decode, import, and commit.
  • Count logical bytes, unique physical bytes, bytes copied, bytes allocated, bytes read/written, file operations, and peak transient memory.
  • Record L1/L2/L3 hit, partial-hit, miss, refusal, admission, promotion, demotion, eviction, and cold-fallback reasons.
  • Capture queue depth, read-ahead depth, write-behind depth, compaction debt, and time blocked by cache maintenance.
  • Report restored tokens, suffix-prefill tokens, TTFT, TPOT/decode-event p50/p95/p99, throughput/goodput, CPU time, and device utilization.
  • Extend the release harness with identical cold/current/candidate A/B workloads across representative prefix lengths, growth patterns, repetition rates, cache pressure, and concurrency.
  • Run the discrete CUDA/non-unified-memory cell as well as unified-memory Metal and every supported release backend/model-family cell required by feat(skippy): add configurable node-local L3 KV cache #1632.
  • Hash inputs, binaries, configuration, order, and outputs so comparisons are attributable to an exact build and workload.

Promotion gate

  • Exact deterministic output identity and corruption/fallback tests remain green.
  • A candidate must beat the current feat(skippy): add configurable node-local L3 KV cache #1632 implementation on its stated primary metric under an identical workload; storage-size improvement alone is not sufficient.
  • No candidate may regress the existing disk-off p99 decode-event latency gate beyond 5%.
  • Publish raw artifacts and a concise comparison table, including negative results.

Relationship to other issues

This is the common evidence gate for the packed L3, streaming import/export, value-aware policy, L2 RAM, codec, and non-prefix experiments. It does not itself choose or implement those mechanisms.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions