Commit e6004f3
authored
docs: propose KeyViz adapter / namespace labels (follow-up) (#694)
## Summary
Proposes a follow-up KeyViz feature: per-adapter labels so a single Raft
route can split into per-adapter sub-rows in the heatmap.
**Trigger**: a user observed that on a default single-Raft-group
deployment the heatmap shows one row at `route:1` covering all five
adapters (DynamoDB / Redis / S3 / SQS / RawKV) with no way to tell which
adapter generated the traffic. Splitting routes via `SplitRange` or the
multi-group startup flags (`--raftRedisMap`, `--raftDynamoMap`, etc.)
works as an operational workaround, but the most common deployment shape
(single group) is currently opaque on this axis.
## Recommended approach (§4.1)
Extend `Observe(routeID, op, keyLen, valueLen, label)` with a per-call
label string. Each adapter sets a constant at its dispatch entry into
`ShardedCoordinator`; empty label preserves today's behaviour. Slot key
widens from `routeID` to `(routeID, label)` — one extra map lookup per
Observe.
Forward-compatible wire-format extension: optional `label` field on
`KeyVizRow` / `MatrixRow`; old SPA against new server ignores it, new
SPA against old server falls back to legacy formatting.
## Implementation plan (§7)
| PR | Scope |
|---|---|
| **A** | This doc |
| **B** | Sampler API extension + `MatrixRow.Label` |
| **C** | Adapter wiring + canonical label constants in
`keyviz/labels.go` |
| **D** | proto + JSON `label` field; SPA renders `route:N / <label>` |
| **E** | Aggregator merge key gains `label` |
## What this PR does NOT do
Per `CLAUDE.md` design-doc-first: this PR is the proposal only. PR-B
onward starts after this doc is reviewed and accepted. Listed deferrals
in §10:
- Per-table / per-bucket / per-queue / per-Redis-DB sub-labels (only the
adapter family is in scope here)
- Operator-configurable label taxonomy
- Persistence of labelled rows (rides along once Phase 3 persistence
ships)
- Adapter-aware split triggers
## Test plan
- [ ] Design review: confirm Option 4.1 (per-Observe label) is the right
pick vs. 4.2 (per-adapter sampler), 4.3 (operator taxonomy), 4.4
(catalog-level)
- [ ] Confirm forward-compatibility expectations (old SPA + new server,
new SPA + old server) match operator preferences
- [ ] §9 open questions worth a look — especially Q1 (single segment vs.
hierarchical) and Q2 (canonical label allocation)
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Added a KeyViz design proposal introducing an adapter-level label axis
for splitting heatmap rows within a route. Defines wire-format label
handling and composite bucket IDs, merge/aggregation behavior to
preserve labels across distributed transforms, rollout-safe toggle,
label syntax constraints, canonical label constants, and a targeted test
checklist for pre-allocation, reclaim, merge propagation, and
virtual-bucket behavior.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->1 file changed
Lines changed: 891 additions & 0 deletions
0 commit comments