feat: per-key cache miss tracking for arbitrary commands

[fcostaoliveira]

Summary

Extends miss/hit accounting (today only available for GET/MGET) to any Redis command supplied via --command, with per-key bucket granularity. Driven by a vendored snapshot of Redis' src/commands/*.json (8.8) processed at build time into a static C++ registry — no JSON parser linked into the binary, no runtime probe required for the common case.

Two commits for review:

1. build: vendor Redis 8.8 commands.json + command_meta registry — pure infrastructure; introduces make commands-meta targets and the codegen pipeline. No behavior change.
2. feat: per-key cache miss tracking for arbitrary commands — the actual feature; ~700 lines of C++.

Reply-shape coverage

Shape	Examples	Tracking
SingleNullBulk	GET, HGET, ZSCORE, GETEX, GETDEL, LPOP, SPOP	null reply ⇒ miss; 1 bucket
ArrayPerElementNulls	MGET, HMGET, ZMSCORE	walk top-level mbulk; per-position null mask
EmptyCollection	SMEMBERS, LRANGE, HGETALL, HKEYS, HVALS, ZRANGE	empty == miss heuristic
IntegerMembership	EXISTS, SISMEMBER, HEXISTS	integer reply N is the hit count
NotMissable / Unknown	SET, INCR, modules…	feature silently disabled

CLI

--command-miss-tracking={auto,off}    default: auto

auto enables tracking for any --command whose first token (or CONTAINER SUB for subcommands) resolves to a miss-bearing reply shape in the registry. off keeps the old JSON shape (no Hits/Misses fields, no Per-Key section) for back-compat with downstream tooling.

JSON output (mb.json, under ALL STATS)

• Per-arbitrary-command entries gain real Hits/sec / Misses/sec (previously hardcoded to 0.0).
• New nested Per-Key Misses section:

"Per-Key Misses": {
    "MGET": {
        "Total Hits": 380, "Total Misses": 820,
        "key[0] Hits": 130, "key[0] Misses": 270,
        "key[1] Hits": 130, "key[1] Misses": 270,
        "key[2] Hits": 120, "key[2] Misses": 280
    }
}

Make targets (maintainer-only)

make commands-meta                       # default REDIS_VERSION=8.8
make commands-meta REDIS_VERSION=8.6     # bump
make commands-meta-fetch                 # JSONs only (slow, network)
make commands-meta-gen                   # regen .h from JSONs (fast)
make commands-meta-check                 # CI guard for stale .h

End-user builds do not require Python; AM_PATH_PYTHON resolves to : if absent.

Smoke results

3 keys preloaded (memtier-1..3), 10-key uniform-random range, 200 reqs × 2 clients (~30% expected hit rate):

Command	Total Hits / Misses	Buckets
GET __key__	120 / 280	key[0]
MGET __key__ __key__ __key__	380 / 820	key[0..2] (no phantom 4th)
EXISTS __key__	120 / 280	key[0]
SMEMBERS __key__	120 / 280	key[0]
GET __key__ w/ --command-miss-tracking=off	(no section)	—

Implementation notes

• m_keep_value=true is forced only on connections that need reply-array inspection (ArrayPerElementNulls / EmptyCollection). SingleNullBulk and IntegerMembership reuse the parser's existing scalar m_hits / m_status and pay no allocation cost.
• Memcached / module / unknown commands resolve to spec=NULL and the feature is silently disabled — no changes to the memcached path.
• Thread-safe: per-thread run_stats carry per-command miss totals and per-key vectors; merged into the printer's run_stats after threads join.
• Mismatches between user-supplied __key__ placeholder count and spec-resolved key count emit a startup warning but do not fail (user might be testing custom modules).

Test plan

• make format, make format-check
• make commands-meta-check (codegen idempotent)
• make -j$(nproc) clean
• ./memtier_benchmark --help shows the new flag
• Man page entry present
• Bash completion entry present
• Smoke battery for all four reply shapes against local Redis 8 (results above)
• CI / RLTest run (will be exercised by tests/test_arbitrary_command_misses.py)

🤖 Generated with Claude Code

---

Note

Medium Risk
Adds non-trivial response-shape parsing and new stats aggregation on the hot arbitrary-command reply path, which could affect correctness/performance for some commands and reply edge cases. Build now vendors a large Redis command metadata snapshot and introduces codegen targets, increasing maintenance surface area.

Overview
Adds per-key hit/miss accounting for --command arbitrary Redis commands, expanding beyond the existing GET/MGET-only tracking. At startup, commands are resolved against a new static command_meta registry (generated from a vendored Redis commands.json snapshot) to determine key positions and reply “shapes”, and at runtime client.cpp inspects responses to compute per-command and per-bucket hits/misses (with optional value materialization only when array-walking is needed).

Introduces the command_meta subsystem (command_meta.{h,cpp} + generated command_meta_data.h) and a maintainer workflow (make commands-meta*, optional Python) to fetch/regen the metadata; the Redis JSON snapshot is committed under deps/commands_json and un-ignored in .gitignore. Stats plumbing is extended via run_stats::update_arbitrary_op_misses() to accumulate totals and per-key vectors, and shell completion is updated to include the new --command-miss-tracking option.

^{Reviewed by Cursor Bugbot for commit f4716fd. Bugbot is set up for automated code reviews on this repo. Configure here.}

[jit-ci]

🛡️ Jit Security Scan Results

✅ No security findings were detected in this PR

---

^{Security scan by Jit}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit dbff900. Configure here.}

[cursor]

Inconsistent NULL status handling between reply shape cases

Low Severity

The SingleNullBulk case treats a NULL status pointer (from response->get_status()) as a cache HIT because the is_null condition short-circuits to false. In contrast, the IntegerMembership case treats NULL status as all MISSES (since n stays 0). This asymmetry means that if the parser ever fails to populate the status for a non-error response, SingleNullBulk silently records phantom hits while IntegerMembership records phantom misses.

Additional Locations (1)

• client.cpp#L837-L843

 

^{Reviewed by Cursor Bugbot for commit dbff900. Configure here.}