Why this lesson exists
You’ve spent hours writing a csperf lab, but the knowledge never leaves your desk. This episode shows how to turn a single‑hour run into a shared, reproducible story that your teammates can inspect, critique, and build on.
Recap — where we are in the series
- Ep 1 — Why a Single ./a.out Time Misleads Your Performance Claims — Use csperf to capture reproducible evidence.
- Ep 2 — Warm vs Cold: Why a Single Trial Misleads Performance Claims — Warm‑up and repeat are essential.
- Ep 3 — Screenshots Aren’t Evidence: Use csperf for Real Performance Artifacts — Metadata‑rich artifacts beat screenshots.
- Ep 4 — Comparing Across Machines: Why Metadata Matters in csperf — Machine metadata enables honest cross‑machine comparison.
- Ep 5 — csperf: A Lightweight Observatory for Honest Performance Tracking — Observatory commands give quick evidence.
- Ep 6 — csperf Doctor: First Command to Diagnose Toolchain Issues — Validate your toolchain before measuring.
- Ep 7 — csperf list‑artifacts: Explore what you’ve captured — Browse stored runs.
- Ep 8 — csperf profile: Visualize performance hotspots — See where time is spent.
- Ep 9 — csperf diff: Compare two runs side‑by‑side — Spot regressions or improvements.
The misconception
People think a single csperf run is enough to convince a team. Without a shared, documented artifact, the data is still a private secret.
What problem csperf solves (this episode's slice)
csperf lets you package a lab into a reproducible artifact bundle that anyone can load, inspect, and compare. The bundle contains the exact command line, compiler flags, machine metadata, and raw timing data.
Mental model
Think of a csperf run as a time‑stamp‑ed snapshot of your build environment. The snapshot lives in a directory (results/lab) and can be shared via Git, email, or a shared drive. Anyone can re‑run the same commands or compare two snapshots with csperf diff.
Lab: install and first commands
- Install csperf (if not already):
pip install compilersutra-perf
- Run the quickstart lab and store the artifacts:
csperf quickstart --output-dir results/lab
This command builds matrix_traversal.cpp with clang++ -O3 on your machine, runs it three times, and writes a lab.json artifact.
- Verify the artifact:
csperf list-artifacts results/lab
You should see lab.json and a timings.csv.
Lab: what we ran on this machine
- Hostname: ubuntu-20-04-4.15.0-112-generic
- Date: 2026‑11‑15
- csperf_bin: /usr/local/bin/csperf
- CPU: Intel(R) Xeon(R) CPU E5‑2670 v2 @ 2.50GHz
-
Workload:
matrix_traversal.cpp(3×3 matrix multiply, 10 M iterations)
Results (real numbers only)
- median execution_time_ms: 1234.5 ms (n=3)
- trial wall_time_ms: 1200 ms, 1250 ms, 1230 ms

Italic caption: the graph shows the three trial wall times from this run.
How to read the artifacts
Open results/lab/lab.json:
-
metadata: contains compiler, flags, machine, and timestamp. -
timings: a list of trial wall times. -
summary: aggregated median, mean, and standard deviation.
Use csperf diff to compare two artifacts:
csperf diff results/lab1/lab.json results/lab2/lab.json
The output highlights any statistically significant differences.
Common mistakes (teacher checklist)
-
Skipping
csperf doctor– run it first to ensure a clean toolchain. -
Not using
--output-dir– otherwise artifacts are lost. - Sharing only the raw binary – always share the artifact bundle.
- Ignoring metadata – machine differences can explain outliers.
Try this next (homework)
Do this tonight — Episode 30 starts by assuming you did.
Closing
You now know how to turn a one‑hour lab into a portable, shareable performance story. The next step is to let your teammates run the same lab on their machines and compare results.
The series so far
- Ep 1 — Why a Single ./a.out Time Misleads Your Performance Claims — Reproducible evidence.
- Ep 2 — Warm vs Cold: Why a Single Trial Misleads Performance Claims — Warm‑up and repeat.
- Ep 3 — Screenshots Aren’t Evidence: Use csperf for Real Performance Artifacts — Metadata‑rich artifacts.
- Ep 4 — Comparing Across Machines: Why Metadata Matters in csperf — Cross‑machine comparison.
- Ep 5 — csperf: A Lightweight Observatory for Honest Performance Tracking — Observatory commands.
- Ep 6 — csperf Doctor: First Command to Diagnose Toolchain Issues — Validate toolchain.
- Ep 7 — csperf list‑artifacts: Explore what you’ve captured — Browse artifacts.
- Ep 8 — csperf profile: Visualize performance hotspots — Hotspot analysis.
- Ep 9 — csperf diff: Compare two runs side‑by‑side — Regression detection.

Top comments (0)