wehub-resource-sync
103 lines
3.0 KiB
ReStructuredText
103 lines
3.0 KiB
ReStructuredText
lmcache trace
|
|
=============
|
|
|
|
The ``lmcache trace`` command inspects and replays LMCache storage-level
|
|
trace files (``.lct``). It has two sub-commands:
|
|
|
|
.. code-block:: bash
|
|
|
|
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
|
|
:doc:`server`).
|
|
|
|
|
|
info
|
|
----
|
|
|
|
Print a one-screen summary of a trace file: header metadata plus per-qualname
|
|
record counts.
|
|
|
|
.. code-block:: bash
|
|
|
|
lmcache trace info path/to/trace.lct
|
|
|
|
.. code-block:: text
|
|
|
|
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.
|
|
|
|
.. code-block:: bash
|
|
|
|
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
|
|
~~~~~~~
|
|
|
|
.. list-table::
|
|
:header-rows: 1
|
|
:widths: 30 70
|
|
|
|
* - 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.
|