Skip to content

Commit e6004f3

Browse files
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 -->
2 parents d4d7ad8 + c788a96 commit e6004f3

1 file changed

Lines changed: 891 additions & 0 deletions

File tree

0 commit comments

Comments
 (0)