Implementation:LMCache LMCache Analyze Chunk Hashes

Knowledge Sources	LMCache
Domains	Chunk Statistics, Cache Analysis
Last Updated	2026-02-09 00:00 GMT

Overview

This module reads chunk hash JSONL files generated by the LMCache file_hash strategy and produces statistics about chunk reuse patterns, time-series distributions, and memory estimates.

Description

The analyze_chunk_hashes.py script is a command-line analysis tool in the LMCache examples that processes chunk hash records written by the file_hash chunk statistics strategy. It computes overall reuse rates, per-request statistics, frequency distributions, hourly time-series breakdowns, and memory requirement estimates. Results can be printed to the console or exported to a JSON file.

Usage

Use this script after running an LMCache workload with the file_hash chunk statistics strategy enabled. It reads the generated chunk_hashes_*.jsonl files from a directory and provides insights into how frequently KV cache chunks are reused.

Code Reference

Source Location

• Repository: LMCache
• File: examples/chunk_statistics/analyze_chunk_hashes.py
• Lines: 1-423

Signature

def load_chunk_hashes(input_dir: Path) -> List[Dict]: ...

def analyze_chunk_hashes(records: List[Dict], top_n: int = 10) -> Dict: ...

def print_analysis(analysis: Dict, verbose: bool = False) -> None: ...

def analyze_time_series(records: List[Dict]) -> Dict: ...

def estimate_memory(
    unique_chunks: int, chunk_size: int = 256, bytes_per_token: int = 2
) -> Dict: ...

def export_results(
    analysis: Dict, output_file: Path,
    include_time_series: bool = False,
    records: Optional[List[Dict]] = None,
) -> None: ...

def print_time_series(time_series: Dict) -> None: ...

def print_memory_estimation(memory_est: Dict) -> None: ...

def main(): ...

Import

# This is a standalone script; run directly:
# python examples/chunk_statistics/analyze_chunk_hashes.py --input-dir ./chunk_hashes

I/O Contract

Inputs

Name	Type	Required	Description
--input-dir	Path	No	Directory containing chunk hash JSONL files (default: ./chunk_hashes)
--output	Path	No	Output JSON file path for analysis results
--top-n	int	No	Number of top reused chunks to display (default: 10)
--verbose	flag	No	Show detailed per-request and frequency distribution statistics
--time-series	flag	No	Include hourly time-series analysis
--memory-estimation	flag	No	Show memory estimation for caching unique chunks
--chunk-size	int	No	Chunk size in tokens for memory estimation (default: 256)
--bytes-per-token	int	No	Bytes per token for memory estimation (default: 2)

Outputs

Name	Type	Description
analysis	Dict	Dictionary containing total_records, total_chunks, unique_chunks, duplicate_chunks, reuse_rate, top_reused_chunks, request_stats, frequency_distribution
time_series	Dict	Hourly breakdown of total_chunks, unique_chunks, and reuse_rate
memory_estimation	Dict	Estimated memory in bytes, MB, and GB for caching unique chunks
return value	int	Exit code: 0 on success, 1 on error

Usage Examples

# Basic analysis from the command line:
# python examples/chunk_statistics/analyze_chunk_hashes.py --input-dir ./chunk_hashes

# Verbose analysis with time series and memory estimation:
# python examples/chunk_statistics/analyze_chunk_hashes.py \
#     --input-dir ./chunk_hashes --verbose --time-series --memory-estimation

# Export results to JSON:
# python examples/chunk_statistics/analyze_chunk_hashes.py \
#     --input-dir ./chunk_hashes --output results.json --time-series

# Programmatic usage:
from pathlib import Path
from examples.chunk_statistics.analyze_chunk_hashes import (
    load_chunk_hashes, analyze_chunk_hashes, estimate_memory,
)

records = load_chunk_hashes(Path("./chunk_hashes"))
analysis = analyze_chunk_hashes(records, top_n=5)
print(f"Reuse rate: {analysis['reuse_rate']:.2%}")

mem = estimate_memory(analysis["unique_chunks"], chunk_size=256)
print(f"Estimated memory: {mem['total_memory_gb']:.2f} GB")