gcmon-results

Published benchmark results for the gcmon GC monitor. This repo hosts the analysis pipeline (extraction, notebook execution, compression) and the historical gallery of runs across CPython versions and benchmark configurations.

What lives here

gcmon-results/
├── gcmon_results/         # the installable Python package
├── notebooks/             # source notebooks (cyclotron, pyperformance)
└── runs/                  # published runs, one folder per (date, dataset)
    ├── README.md          # auto-regenerated gallery
    └── YYYY-MM-DD/
        └── <dataset>/
            ├── meta.json
            ├── <trace>.pftrace.zst
            ├── <dataset>.ipynb       # executed notebook
            ├── slices.csv.zst
            ├── workers.csv.zst
            ├── figs/*.png
            ├── summary/*.csv
            └── README.md

Quick start

# Install dependencies and the package into a project-local .venv/
poetry install

# Verify the install
poetry run gcmon-results --help

CLI

gcmon-results exposes three subcommands.

gcmon-results prepare <dataset> --trace <path> --benchmarks <path> --out <dir>

Extracts GC trace data into --out:

• slices.csv.zst — per-event slice table (zstd)
• workers.csv.zst — per-benchmark workers (zstd)

poetry run gcmon-results prepare cyclotron \
  --trace /path/to/cyclotron.pftrace \
  --benchmarks /path/to/cyclotron-results.json \
  --out runs/2026-07-02/cyclotron

poetry run gcmon-results prepare pyperformance \
  --trace /path/to/trace.pftrace \
  --benchmarks /path/to/pyperf-results.json \
  --out runs/2026-07-02/pyperformance

--trace accepts both .pftrace (uncompressed) and .pftrace.zst (zstd-compressed) files. Compressed input is decompressed to a temp file in --out and removed when the run completes.

gcmon-results publish <dataset> --trace <path> [...]

Orchestrates the full publish flow:

1. prepare the trace (subprocess to the CLI)
2. Papermill-execute notebooks/<dataset>.ipynb into the dataset folder
3. jupyter nbconvert --to markdown the executed notebook to README.md
4. Always recompress the trace to <stem>.pftrace.zst at zstd level 19
5. Compute SHA-256 of the uncompressed trace bytes
6. Write meta.json (date, dataset, gcmon version, host, sizes, hash, embedded metadata)
7. Rebuild runs/README.md
8. git add, git commit, git push (push skipped with --no-push)

poetry run gcmon-results publish cyclotron \
  --trace /path/to/cyclotron.pftrace \
  --benchmarks /path/to/cyclotron-results.json \
  --gcmon-version v0.3.1 \
  --no-push

Flags:

• --out-date YYYY-MM-DD — publication date (default: today UTC)
• --gcmon-version VER — version string recorded in meta.json
• --results-root DIR — runs directory (default: ./runs)
• --notebooks-root DIR — notebooks directory (default: ./notebooks)
• --no-push — skip the git push step
• --force — overwrite runs/<date>/<dataset>/ if it exists

gcmon-results list [--runs-dir DIR] [--rebuild-index]

Prints a table of published runs in the current checkout, one row per (date, dataset) pair, including gcmon_version, worker count, and event count.

Where do my traces live?

Traces live wherever the user keeps them on disk. publish takes any path via --trace. This repo contains no working inputs directory.

Browse results

Open runs/README.md to see the table of contents. Each date block has a bullet per dataset linking to the executed notebook.

Schema

slices.csv.zst

Zstd-compressed, semicolon-separated CSV. One row per gc.* slice event in the trace.

Columns:

• upid (int) — unique process id in the trace
• pid (int) — OS process id (one worker per pid)
• name (str) — short name for the worker (cyclotron: e.g. "cs10-eb0-lo100"; pyperformance: e.g. "richards")
• slice_name (str) — phase name, e.g. "GC Pause"
• gen (int) — 0/1/2; null for non-gen phases
• start_ts (int) — nanoseconds since trace start
• end_ts (int) — start_ts + dur, in nanoseconds
• args (str) — debug args joined as "k=v, k=v" (may be empty)

workers.csv.zst

Zstd-compressed, semicolon-separated CSV. One row per benchmark worker.

Common columns (both datasets):

• upid (int) — unique process id in the trace
• pid (int) — OS process id
• cmdline (str) — full command line of the worker process
• start_ts (int) — nanoseconds since trace start
• benchmark_name (str) — short name for the benchmark
• benchmark_duration (float) — wall-clock duration from results JSON, ms
• perfetto_duration (float) — perfetto-tracked duration, ms

Pyperformance-only columns:

• benchmark_description (str) — description of the benchmark variant
• is_calibration (int) — 1 if calibration run, 0 otherwise

meta.json

One per dataset, written by publish. Fields:

• date_utc (str) — "YYYY-MM-DD"
• dataset (str) — "cyclotron" or "pyperformance"
• gcmon_version (str) — user-supplied, e.g. "v0.3.1"
• host (str) — platform.node()
• python_version (str) — platform.python_version()
• trace_sha256 (str) — SHA-256 of the uncompressed .pftrace bytes
• trace_bytes_uncompressed (int)
• trace_bytes_compressed (int) — size of the published .pftrace.zst
• trace_metadata (dict) — always present; may be empty {} until gcmon starts embedding metadata

summary/*.csv

Written by the notebooks. Files differ by dataset:

Cyclotron:

• pause_stats.csv — name, gen, slice_name, count, mean, median, std, min, p50, p95, p99, max, sum
• slice_share.csv — slice_name, share_pct
• gen2_tail.csv — name, slice_name, count, mean, p99, max
• boxplot_stats.csv — cs, eb, lo, gen, slice_name, count, mean, median, p50, p95, p99, max
• per_run_metrics.csv — pid, name, gen, slice_name, count, dur
• g0_worst_run.csv — name, count, dur, ...

Pyperformance:

• pause_stats.csv — benchmark_name, gen, slice_name, n_runs, count, mean, median, std, min, p50, p95, p99, max, sum
• slice_share.csv — slice_name, share_pct
• gen2_tail.csv — benchmark_name, slice_name, count, mean, p99, max
• boxplot_stats.csv — benchmark_name, gen, slice_name, count, mean, median, p50, p95, p99, max
• per_run_metrics.csv — upid, pid, name, gen, slice_name, count, dur
• per_benchmark_summary.csv

runs/README.md

Auto-regenerated table of contents. Newest date first; one ## <date> heading per published date with a bullet per dataset linking to the executed notebook <date>/<dataset>/gc_pause_analysis.ipynb.

Requirements

• Python 3.13+
• Poetry 2.x for dependency management
• All runtime dependencies are declared in pyproject.toml and installed into a project-local .venv/ by poetry install

License

MIT — see LICENSE.