lmcache trace#

The lmcache trace command inspects and replays LMCache storage-level trace files (.lct). It has two sub-commands:

lmcache trace {info,replay} FILE [options]

Note

lmcache trace needs the full lmcache package (StorageManager, trace codecs, TraceReader). It is not available in the lightweight lmcache-cli install and exits with status 2 if those modules are missing.

Trace capture is not a trace sub-command — recording is bound to a live server via lmcache server --trace-level storage [--trace-output ...] (see lmcache server).

info#

Print a one-screen summary of a trace file: header metadata plus per-qualname record counts.

lmcache trace info path/to/trace.lct

Trace file: path/to/trace.lct
  level:                storage
  format_version:       1
  trace_schema_version: 1
  duration:             12.345s
  sm_config_digest:     a1b2c3d4
  total_records:        2048
  ops:
    StorageManager.store: 1024
    StorageManager.retrieve: 1024

The only argument is the positional FILE (path to a .lct trace file).

replay#

Reissue every recorded call against a fresh StorageManager, honoring the recorded inter-call timings.

lmcache trace replay path/to/trace.lct \
    --l1-size-gb 10 --eviction-policy LRU

replay accepts the standard storage-manager configuration flags (--l1-size-gb, --eviction-policy, --l2-...); see lmcache server --help for the full list. The replay-side config may differ from the config recorded in the trace, which can legitimately cause retrieve misses.

Warning

A replay environment mismatch may cause retrieve misses. Replay uses the replay-side StorageManager config (which may differ from the recorded config), runs on a host whose performance may differ from the recording host, and StorageManager reads/writes are async. Treat retrieve-miss counts as a signal about the replay environment, not a defect in the trace.

Options#

Flag	Description
`FILE`	Path to a `.lct` trace file (positional, required).
`--verbose`	Print one line per replayed record.
`--jsonl-out PATH`	Write one JSON object per replayed record to `PATH` (qualname, latency_ms, failed).
`--output-dir DIR`	Directory for aggregated CSV / JSON summary output (default: current directory).
`--no-csv`	Skip the aggregated CSV summary export.
`--json`	Also export an aggregated JSON summary.
`-q` / `--quiet`	Suppress the terminal metrics table (files are still written).

The terminal summary reports overall replay stats (records replayed / skipped / failed, duration, config-digest match) and per-op latency percentiles. replay exits with status 1 if any record failed.