HTML Reports: Share Performance Artifacts Your Team Will Actually Open

Why this lesson exists

Performance teams often hand off raw JSON or screenshots and expect the other side to understand the story. The reality is that most developers skim or ignore the data because it is noisy, hard to read, and not linked to the code that produced it. This episode shows how to turn a csperf JSON artifact into a clean, human‑friendly HTML dashboard that anyone on the team can open, explore, and trust.

Recap — where we are in the series

Ep 1: single‑shot timings are misleading; use csperf for reproducible evidence.
Ep 2: warm‑up and repeat runs give credible data.
Ep 3: screenshots mislead; csperf provides metadata‑rich artifacts.
Ep 4: metadata enables cross‑machine comparison.
Ep 5: observatory commands give quick evidence.
Ep 6: doctor command validates toolchain.
Ep 7: quickstart for a reproducible artifact.
Ep 8: JSON is the source of truth.
Ep 9: choose the right backend.
Ep 10: stability metrics expose volatility.
Ep 11: quantify warm‑up impact.
Ep 12: measure locality.
Ep 13: validate optimizer claims.
Ep 14: enable and read Linux perf counters.
Ep 15: isolate noise sources.
Ep 16: evidence levels separate truth from hype.
Ep 17: diff two runs without spreadsheets.

The misconception

Many teams still believe that a single JSON file is enough for collaboration. The file is large, contains raw numbers, and lacks context. When a teammate opens it, they often look for a single “best” value and miss the story of variance, hardware counters, and build metadata.

What problem csperf solves (this episode's slice)

csperf’s visualize command turns the raw JSON into an interactive HTML report that:

1. Groups metrics by category.
2. Highlights outliers.
3. Links back to the exact source file and compiler flags.
4. Provides a clean, printable view.

Mental model

Think of the JSON as a database dump. The HTML report is a query interface that lets you filter, sort, and drill down. It is the same data, but presented in a way that a non‑expert can read and act on.

Lab: install and first commands

1. Ensure you have a recent csperf (≥ 0.3.0). If not, upgrade:

   pip install --upgrade csperf

1. Run a sample workload to generate a JSON artifact:

   csperf run --input examples/cpp/matrix_traversal.cpp \
             --backend cpu \
             --output results/r.json

This produces results/r.json.

1. Visualize the artifact:

   csperf visualize results/r.json \
                 --format html \
                 --output results/report

The command creates results/report/index.html.

Lab: what we ran on this machine

We executed the matrix traversal example on an AMD Ryzen 7 9700X running Ubuntu 24.04. The machine metadata is captured in csperf/machine.txt. The JSON artifact (csperf/r.json) contains five trials, a mean execution time of 5.1368 ms, and a standard deviation of 0.0066 ms.

Results (real numbers only)

Metric	Value	Unit
Execution time (mean)	5.1368	ms
Execution time (min)	5.129	ms
Execution time (max)	5.145	ms
Stdev	0.006573	ms
CPU cycles	5,998,796	cycles
IPC	2.052114
Cache misses	93,797
L1 cache misses	232,309
L2 cache misses	101,054

The HTML report visualizes these numbers in tables and charts.

How to read the artifacts

Open results/report/index.html in a browser. The page is split into sections:

1. Overview – shows the run date, compiler, and build flags.
2. Timing – a table of per‑trial times and a histogram of the distribution.
3. Counters – a bar chart of key hardware counters.
4. Metadata – links to the source file and the exact command line.

Hovering over a metric reveals the underlying JSON value, making the link between the visual and the source explicit.

Common mistakes (teacher checklist)

• Skipping the --format html flag – you’ll get a JSON‑only output.
• Using a non‑existent output directory – csperf will error; create the folder first.
• Not committing the HTML to source control – the artifact is valuable for future reference.
• Assuming the first row is the best – always look at the distribution.

Try this next (homework)

Generate a report for a different backend (e.g., --backend cuda) and compare the CPU vs GPU timings in the same HTML dashboard. Do this tonight — Episode 19 starts by assuming you did.

Closing

By moving from raw JSON to a human‑friendly HTML report, you lower the barrier for collaboration. Team members can quickly spot regressions, understand variance, and trace back to the exact build that produced the numbers.

The series so far

• Ep 1: Why a Single ./a.out Time Misleads Your Performance Claims (this article)
• Ep 2: Warm vs Cold: Why a Single Trial Misleads Performance Claims
• Ep 3: Screenshots Aren't Evidence: Use csperf for Real Performance Artifacts
• Ep 4: Comparing Across Machines: Why Metadata Matters in csperf
• Ep 5: csperf: A Lightweight Observatory for Honest Performance Tracking
• Ep 6: csperf Doctor: First Command to Diagnose Toolchain Issues
• Ep 7: csperf Quickstart: 30‑Second First Win
• Ep 8: Reading csperf JSON: The Real Performance Artifact
• Ep 9: Backends 101: Choosing the Right Measurement Surface
• Ep 10: Stability Metrics: Min, Max, and Standard Deviation as First-Class Citizens
• Ep 11: Warmup Deep Dive: What You’re Throwing Away and Why
• Ep 12: Row vs. Column: Measuring Locality with csperf
• Ep 13: Unmasking the O‑3 Myth: Real‑World Optimizer Impact with csperf
• Ep 14: Turning on Linux perf Counters with csperf (honestly)
• Ep 15: Noise Sources: Affinity, Frequency, and Background Load — How to isolate and quantify non‑compiler variance with csperf
• Ep 16: Evidence Levels: What a Single JSON Can and Cannot Claim
• Ep 17: csperf Diff: Comparing Two Runs Without Spreadsheet Chaos

Teaser for next episode

We’ll dive into regression language: when a slower mean is actionable and how to set thresholds before you start crying about regressions.