kvtop 0.1.0__tar.gz

kvtop-0.1.0/Cargo.lock

@@ -0,0 +1,7 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 3
+
+[[package]]
+name = "kvtop"
+version = "0.1.0"

kvtop-0.1.0/Cargo.toml

@@ -0,0 +1,20 @@
+[package]
+name = "kvtop"
+version = "0.1.0"
+edition = "2021"
+rust-version = "1.74"
+description = "Read-only CLI for inspecting KV-cache metrics from Prometheus snapshots"
+license = "MIT"
+readme = "README.md"
+keywords = ["llm", "kv-cache", "observability", "cli", "prometheus"]
+categories = ["command-line-utilities", "development-tools::profiling"]
+include = ["src/**", "Cargo.toml", "Cargo.lock", "README.md", "PUBLISH.md", "LICENSE", "examples/**", "pyproject.toml"]
+
+[[bin]]
+name = "kvtop"
+path = "src/main.rs"
+
+[profile.release]
+lto = true
+strip = true
+codegen-units = 1

kvtop-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kvtop contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kvtop-0.1.0/PKG-INFO

@@ -0,0 +1,55 @@
+Metadata-Version: 2.4
+Name: kvtop
+Version: 0.1.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Programming Language :: Rust
+Classifier: Topic :: System :: Monitoring
+License-File: LICENSE
+Summary: Read-only Rust CLI for inspecting KV-cache metrics from Prometheus snapshots
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+
+# kvtop
+
+A small, read-only Rust CLI for inspecting KV-cache metrics from Prometheus text snapshots.
+
+Version 0.1.0 reads a UTF-8 file or stdin, selects KV-related metrics, and emits a terminal table or JSON. It is useful with a serving engine's existing metrics endpoint; it does not attach to CUDA or modify a running engine. The Rust executable has no third-party crate dependencies.
+
+## Use
+
+```sh
+curl -fsS http://localhost:8000/metrics | kvtop
+kvtop --file snapshot.prom
+kvtop --file snapshot.prom --json
+kvtop --file snapshot.prom --match prefix_cache
+```
+
+Default name filters cover `kv_cache`, `prefix_cache`, `kv_block`, `kv_transfer`, `cached_tokens`, `prompt_tokens_cached`, and `prefill_kv_computed`. `--match` replaces those filters and can be repeated. The input limit is 16 MiB. Empty or missing measurements return an error instead of zero.
+
+Values retain the producer's units and labels. In particular, vLLM's `kv_cache_usage_perc` uses 1 for 100%, and prefix-cache counters count tokens, not requests. Samples from different workers are kept separate. This tool does not infer physical bytes from generic GPU usage, derive interval hit rates from cumulative counters, or claim a causal performance saving.
+
+JSON has `schema_version: 1` and a `samples` array. Each sample contains `name`, a raw Prometheus `labels` string, `value`, and `raw_value`. Nonfinite values have JSON `null` plus their explicit `raw_value`; very large numeric values may lose precision in `value`, so use `raw_value` when exact representation matters. Timestamps and exemplars are not included in this first version. This is a metric-snapshot inspector, not a general Prometheus validator.
+
+## Build and test
+
+```sh
+cargo test
+cargo build --release
+cargo run -- --file examples/vllm.prom --json
+```
+
+The fixture is synthetic. An actual engine integration and real GPU performance measurements have not been validated by this release preparation.
+
+## Distribution
+
+The package is configured for Cargo and for a Python wheel containing the same Rust executable, using Maturin's `bin` mode. Publishing preparation is not evidence that either registry currently hosts this project. See `PUBLISH.md` in the source delivery for the commands and publication status.
+
+## Existing command with the same name
+
+This is an independent project, unaffiliated with `ovg-project/kvcached`, which already distributes a Python command named `kvtop`. Their command inspects kvcached shared-memory records; this program reads Prometheus snapshots. Installing both commands into one environment may overwrite or shadow one entrypoint. Use a separate virtual environment or an explicit executable path. This project does not replace, patch, or depend on kvcached.
+
+## License
+
+MIT.
+

kvtop-0.1.0/PUBLISH.md

@@ -0,0 +1,66 @@
+# Publication handoff
+
+Prepared on 2026-09-22. Nothing has been uploaded to PyPI or crates.io.
+
+Public registry checks at preparation time:
+- `https://pypi.org/pypi/kvtop/json`: HTTP 404, `Not Found`.
+- `https://pypi.org/simple/kvtop/`: HTTP 404.
+- `https://crates.io/api/v1/crates/kvtop`: HTTP 404, `crate kvtop does not exist`.
+- `https://index.crates.io/kv/to/kvtop`: HTTP 404.
+
+Absence from public endpoints does not guarantee first-upload eligibility: a registry can reserve or prohibit a name, and its state can change.
+
+The preparation environment did not contain Cargo or PyPI publishing credentials. Never paste an API token into chat or commit it to this source tree.
+
+## Verify the release
+
+```sh
+cargo test
+cargo package --list
+cargo publish --dry-run
+```
+
+## crates.io
+
+On your authenticated machine, `cargo login` prompts for your own crates.io publishing token. Then:
+
+```sh
+cargo publish
+```
+
+The crate contains a binary named `kvtop`. Check the published project and use a fresh install to verify it:
+
+```sh
+cargo install kvtop --version 0.1.0 --locked
+kvtop --version
+```
+
+## PyPI
+
+Install Maturin and Twine in a release environment. Build the same Rust binary into a wheel:
+
+```sh
+python -m pip install 'maturin>=1.8,<2' twine
+maturin build --release --bindings bin --compatibility pypi --out dist
+maturin sdist --out dist
+python -m twine check dist/*
+```
+
+Publish using your locally configured PyPI authentication, Trusted Publishing, or Twine's interactive token prompt. For the token prompt, the username is `__token__` and the password is your API token:
+
+```sh
+python -m twine upload dist/*
+```
+
+First release: a Linux x86_64 wheel and source distribution. Other operating systems require their own wheels or a Rust toolchain for source builds. Do not advertise prebuilt macOS/Windows support until those builds exist.
+
+In a fresh environment, verify installation and functionality:
+
+```sh
+python -m venv /tmp/kvtop-release-check
+/tmp/kvtop-release-check/bin/python -m pip install kvtop==0.1.0
+/tmp/kvtop-release-check/bin/kvtop --version
+/tmp/kvtop-release-check/bin/kvtop --file examples/vllm.prom --json
+```
+
+Keep this installation separate from kvcached to avoid its existing `kvtop` entrypoint.

kvtop-0.1.0/README.md

@@ -0,0 +1,42 @@
+# kvtop
+
+A small, read-only Rust CLI for inspecting KV-cache metrics from Prometheus text snapshots.
+
+Version 0.1.0 reads a UTF-8 file or stdin, selects KV-related metrics, and emits a terminal table or JSON. It is useful with a serving engine's existing metrics endpoint; it does not attach to CUDA or modify a running engine. The Rust executable has no third-party crate dependencies.
+
+## Use
+
+```sh
+curl -fsS http://localhost:8000/metrics | kvtop
+kvtop --file snapshot.prom
+kvtop --file snapshot.prom --json
+kvtop --file snapshot.prom --match prefix_cache
+```
+
+Default name filters cover `kv_cache`, `prefix_cache`, `kv_block`, `kv_transfer`, `cached_tokens`, `prompt_tokens_cached`, and `prefill_kv_computed`. `--match` replaces those filters and can be repeated. The input limit is 16 MiB. Empty or missing measurements return an error instead of zero.
+
+Values retain the producer's units and labels. In particular, vLLM's `kv_cache_usage_perc` uses 1 for 100%, and prefix-cache counters count tokens, not requests. Samples from different workers are kept separate. This tool does not infer physical bytes from generic GPU usage, derive interval hit rates from cumulative counters, or claim a causal performance saving.
+
+JSON has `schema_version: 1` and a `samples` array. Each sample contains `name`, a raw Prometheus `labels` string, `value`, and `raw_value`. Nonfinite values have JSON `null` plus their explicit `raw_value`; very large numeric values may lose precision in `value`, so use `raw_value` when exact representation matters. Timestamps and exemplars are not included in this first version. This is a metric-snapshot inspector, not a general Prometheus validator.
+
+## Build and test
+
+```sh
+cargo test
+cargo build --release
+cargo run -- --file examples/vllm.prom --json
+```
+
+The fixture is synthetic. An actual engine integration and real GPU performance measurements have not been validated by this release preparation.
+
+## Distribution
+
+The package is configured for Cargo and for a Python wheel containing the same Rust executable, using Maturin's `bin` mode. Publishing preparation is not evidence that either registry currently hosts this project. See `PUBLISH.md` in the source delivery for the commands and publication status.
+
+## Existing command with the same name
+
+This is an independent project, unaffiliated with `ovg-project/kvcached`, which already distributes a Python command named `kvtop`. Their command inspects kvcached shared-memory records; this program reads Prometheus snapshots. Installing both commands into one environment may overwrite or shadow one entrypoint. Use a separate virtual environment or an explicit executable path. This project does not replace, patch, or depend on kvcached.
+
+## License
+
+MIT.

kvtop-0.1.0/examples/vllm.prom

@@ -0,0 +1,11 @@
+# Synthetic fixture using vLLM metric names, not measurements from a real server.
+# HELP vllm:kv_cache_usage_perc KV-cache usage. 1 means 100 percent usage.
+# TYPE vllm:kv_cache_usage_perc gauge
+vllm:kv_cache_usage_perc{model_name="example-model",engine="0"} 0.42
+vllm:kv_cache_usage_perc{model_name="example-model",engine="1"} 0.17
+# TYPE vllm:prefix_cache_queries_total counter
+vllm:prefix_cache_queries_total{model_name="example-model"} 10000
+# TYPE vllm:prefix_cache_hits_total counter
+vllm:prefix_cache_hits_total{model_name="example-model"} 6000
+vllm:request_prefill_kv_computed_tokens_sum{model_name="example-model"} 4000
+vllm:num_requests_running{model_name="example-model"} 3

kvtop-0.1.0/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["maturin>=1.8,<2"]
+build-backend = "maturin"
+
+[project]
+name = "kvtop"
+dynamic = ["version"]
+description = "Read-only Rust CLI for inspecting KV-cache metrics from Prometheus snapshots"
+readme = "README.md"
+requires-python = ">=3.9"
+license = {file = "LICENSE"}
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Programming Language :: Rust",
+    "Topic :: System :: Monitoring",
+]
+
+[tool.maturin]
+bindings = "bin"

kvtop-0.1.0/src/main.rs

@@ -0,0 +1,207 @@
+use std::env;
+use std::fs::File;
+use std::io::{self, Read, Write};
+
+const VERSION: &str = env!("CARGO_PKG_VERSION");
+const MAX_BYTES: u64 = 16 * 1024 * 1024;
+const DEFAULT_PATTERNS: &[&str] = &[
+    "kv_cache", "prefix_cache", "kv_block", "kv_transfer", "cached_tokens",
+    "prompt_tokens_cached", "prefill_kv_computed",
+];
+
+#[derive(Debug, PartialEq)]
+struct Sample {
+    name: String,
+    labels: String,
+    raw_value: String,
+}
+
+fn parse_sample(line: &str) -> Result<Sample, String> {
+    let mut quoted = false;
+    let mut escaped = false;
+    let mut depth = 0u8;
+    let mut end = None;
+    for (i, c) in line.char_indices() {
+        if quoted {
+            if escaped { escaped = false; }
+            else if c == '\\' { escaped = true; }
+            else if c == '"' { quoted = false; }
+            continue;
+        }
+        match c {
+            '"' if depth == 1 => quoted = true,
+            '{' if depth == 0 => depth = 1,
+            '}' if depth == 1 => depth = 0,
+            '{' | '}' | '"' => return Err("invalid label delimiters".into()),
+            c if c.is_whitespace() && depth == 0 => { end = Some(i); break; }
+            _ => {}
+        }
+    }
+    if quoted || depth != 0 { return Err("unterminated label set".into()); }
+    let end = end.ok_or("missing sample value")?;
+    let identity = &line[..end];
+    let (name, labels) = match identity.find('{') {
+        Some(i) if identity.ends_with('}') => (&identity[..i], &identity[i..]),
+        Some(_) => return Err("invalid sample identity".into()),
+        None => (identity, ""),
+    };
+    if name.is_empty() || !name.chars().enumerate().all(|(i, c)| {
+        c.is_ascii_alphabetic() || c == '_' || c == ':' || (i > 0 && c.is_ascii_digit())
+    }) { return Err("invalid metric name".into()); }
+    let raw_value = line[end..].split_whitespace().next().ok_or("missing sample value")?;
+    if !matches!(raw_value, "+Inf" | "-Inf" | "Inf" | "NaN") {
+        let value = raw_value.parse::<f64>().map_err(|_| "invalid numeric value")?;
+        if !value.is_finite() { return Err("numeric value overflow or invalid spelling".into()); }
+    }
+    Ok(Sample { name: name.into(), labels: labels.into(), raw_value: raw_value.into() })
+}
+
+fn select(input: &str, patterns: &[String]) -> Result<Vec<Sample>, String> {
+    let mut samples = Vec::new();
+    for (index, line) in input.lines().enumerate() {
+        let line = line.trim();
+        if line.is_empty() || line.starts_with('#') { continue; }
+        let name = line.split(|c: char| c == '{' || c.is_whitespace()).next().unwrap_or("");
+        if !patterns.iter().any(|p| name.contains(p)) { continue; }
+        samples.push(parse_sample(line).map_err(|e| format!("line {}: {}", index + 1, e))?);
+    }
+    if samples.is_empty() {
+        return Err("no matching KV-cache metrics; check the input or supply --match SUBSTRING".into());
+    }
+    Ok(samples)
+}
+
+fn json_string(value: &str) -> String {
+    let mut out = String::from("\"");
+    for c in value.chars() {
+        match c {
+            '"' => out.push_str("\\\""),
+            '\\' => out.push_str("\\\\"),
+            c if c <= '\u{1f}' => out.push_str(&format!("\\u{:04x}", c as u32)),
+            c => out.push(c),
+        }
+    }
+    out.push('"');
+    out
+}
+
+fn render(samples: &[Sample], json: bool) -> String {
+    if json {
+        let rows = samples.iter().map(|s| {
+            let value = s.raw_value.parse::<f64>().ok().filter(|v| v.is_finite())
+                .map(|v| v.to_string()).unwrap_or_else(|| "null".into());
+            format!("{{\"name\":{},\"labels\":{},\"value\":{},\"raw_value\":{}}}",
+                json_string(&s.name), json_string(&s.labels), value, json_string(&s.raw_value))
+        }).collect::<Vec<_>>().join(",");
+        format!("{{\"schema_version\":1,\"source_format\":\"prometheus\",\"samples\":[{}]}}\n", rows)
+    } else {
+        let mut out = String::from("KV/cache metric snapshot — raw producer units\nVALUE\tMETRIC\tLABELS\n");
+        for s in samples {
+            out.push_str(&format!("{}\t{}\t{}\n", s.raw_value, s.name, s.labels.escape_debug()));
+        }
+        out
+    }
+}
+
+fn usage() -> String {
+    format!("kvtop {VERSION} — read-only KV-cache metric inspector\n\n\
+Usage: kvtop [--file PATH] [--json] [--match SUBSTRING]...\n\
+       curl -fsS http://localhost:8000/metrics | kvtop\n\n\
+Reads a Prometheus text snapshot from stdin or a UTF-8 file (maximum 16 MiB).\n\
+--match replaces the default KV-cache name filters; repeated filters use OR.\n\
+Values retain producer units. Counters are cumulative, not interval hit rates.\n\
+Missing data is an error, never a fabricated zero. No inference process is modified.\n\
+This independent Rust application is not kvcached's Python kvtop command.\n")
+}
+
+fn run(args: Vec<String>) -> Result<String, String> {
+    let mut file = None;
+    let mut json = false;
+    let mut patterns = Vec::new();
+    let mut args = args.into_iter();
+    while let Some(arg) = args.next() {
+        match arg.as_str() {
+            "--help" | "-h" => return Ok(usage()),
+            "--version" | "-V" => return Ok(format!("kvtop {VERSION}\n")),
+            "--json" => json = true,
+            "--file" => {
+                if file.is_some() { return Err("--file may only be supplied once".into()); }
+                file = Some(args.next().ok_or("--file requires a path")?);
+            }
+            "--match" => {
+                let value = args.next().ok_or("--match requires a substring")?;
+                if value.is_empty() { return Err("--match cannot be empty".into()); }
+                patterns.push(value);
+            }
+            _ => return Err(format!("unknown argument: {}; see --help", arg.escape_debug())),
+        }
+    }
+    if patterns.is_empty() { patterns = DEFAULT_PATTERNS.iter().map(|s| s.to_string()).collect(); }
+    let reader: Box<dyn Read> = match file {
+        Some(path) => Box::new(File::open(path).map_err(|e| format!("cannot open input: {e}"))?),
+        None => Box::new(io::stdin()),
+    };
+    let mut input = String::new();
+    reader.take(MAX_BYTES + 1).read_to_string(&mut input).map_err(|e| format!("cannot read UTF-8 input: {e}"))?;
+    if input.len() as u64 > MAX_BYTES { return Err("snapshot exceeds the 16 MiB limit".into()); }
+    Ok(render(&select(&input, &patterns)?, json))
+}
+
+fn main() {
+    match run(env::args().skip(1).collect()) {
+        Ok(output) => {
+            if let Err(e) = io::stdout().lock().write_all(output.as_bytes()) {
+                if e.kind() != io::ErrorKind::BrokenPipe { eprintln!("kvtop: {e}"); std::process::exit(1); }
+            }
+        }
+        Err(e) => { eprintln!("kvtop: {e}"); std::process::exit(2); }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    fn patterns() -> Vec<String> { DEFAULT_PATTERNS.iter().map(|s| s.to_string()).collect() }
+    #[test]
+    fn parses_realistic_snapshot_without_aggregating_replicas() {
+        let s = select(include_str!("../examples/vllm.prom"), &patterns()).unwrap();
+        assert_eq!(s.len(), 5);
+        assert_eq!(s[0].raw_value, "0.42");
+        assert_ne!(s[0].labels, s[1].labels);
+        assert!(!s.iter().any(|s| s.name.contains("requests_running")));
+    }
+    #[test]
+    fn quoted_spaces_braces_and_escapes_do_not_split_identity() {
+        let s = parse_sample(r#"kv_cache_bytes{model="a } \" b",replica="1"} 2e3 1234"#).unwrap();
+        assert_eq!(s.name, "kv_cache_bytes");
+        assert_eq!(s.raw_value, "2e3");
+        assert!(s.labels.contains("replica"));
+    }
+    #[test]
+    fn missing_metrics_and_bad_samples_are_errors() {
+        assert!(select("# HELP a example\nother_metric 0", &patterns()).is_err());
+        assert!(select("kv_cache_bytes nope", &patterns()).is_err());
+        assert!(parse_sample("kv_cache_bytes{broken=\"x} 1").is_err());
+        assert!(parse_sample("kv_cache_bytes 1e999").is_err());
+    }
+    #[test]
+    fn nonfinite_values_remain_explicit() {
+        let samples = ["NaN", "+Inf", "-Inf"].iter().map(|v| parse_sample(&format!("kv_cache_bytes {v}")).unwrap()).collect::<Vec<_>>();
+        let output = render(&samples, true);
+        assert_eq!(output.matches("\"value\":null").count(), 3);
+        assert!(output.contains("\"raw_value\":\"NaN\""));
+    }
+    #[test]
+    fn custom_filters_override_defaults() {
+        let s = select("kv_cache_bytes 1\ncustom_metric 2", &["custom_".into()]).unwrap();
+        assert_eq!(s.len(), 1);
+        assert_eq!(s[0].name, "custom_metric");
+    }
+    #[test]
+    fn escapes_json_and_rejects_unknown_cli_options() {
+        assert_eq!(json_string("x\n\"\\"), "\"x\\u000a\\\"\\\\\"");
+        assert!(run(vec!["--unknown".into()]).is_err());
+        assert!(run(vec!["--file".into()]).is_err());
+        assert!(run(vec!["--match".into(), "".into()]).is_err());
+    }
+}