Reporting a performance finding without over-claiming: baseline, incident window, tool and interval

Goal

Write up a performance observation so another agent or operator can judge how much to trust it and reproduce the measurement, without implying a controlled experiment that was not run.

Prerequisites

The raw output, not just a summary, from whichever tools were used during both the normal period and the incident.

Steps

1. State the baseline first: the numbers during a period the system was considered healthy, with the tool, its exact invocation (flags and interval), and the wall-clock window sampled.
2. State the incident numbers the same way, with the same tool and interval where possible; a baseline taken with vmstat 1 5 and an incident reading from a 10-minute sar interval are not directly comparable, and the report should say so rather than implying they are.
3. Name the time window precisely, including timezone or explicit UTC, so a reader can independently pull the same window from any other source (logs, alerts, deploy history) covering the same period.
4. List what was ruled out and how: "CPU was not saturated (1-second mpstat samples stayed under 40% on every core during the window)" is a checked fact at that resolution; "probably not CPU" is a guess and should be labelled as one. An average only rules out what it could have seen: a 10-minute sar interval cannot exclude saturation lasting a few seconds, and low CPU in a guest says nothing about steal unless %steal was read too.
5. Keep the two kinds of statement visibly separate: numbers read directly from a tool's output, versus an interpretation built on top of them — "iowait was elevated" is a reading, "this is caused by the backup job" is a hypothesis unless the backup's own log confirms the timing, and even matching timing shows coincidence, not cause, until changing the suspect changes the measurement.
6. Attach or link the raw captures (a .blg, a perf.data file, a saved sar binary file, a terminal transcript) rather than only the extracted numbers, so the reading can be double-checked later.
7. Note what was not measured and could still explain the finding, instead of implying the investigation was exhaustive, and mention any tool whose own overhead (strace, a high-rate perf record) may have shifted the numbers.
8. If a fix is claimed, show the same measurement before and after under comparable load; a single better run after a change is an observation, not proof.

Expected result

A report a second reader can evaluate on its own terms — same tool, same interval, same window, an explicit ruled-out list — without needing to trust the first investigator's judgement calls.

Limits and test basis

This is a proposed write-up discipline, not a standard; no single format is used universally across tools and teams. It does not by itself validate that the underlying measurements were correct, only that what was measured and what was inferred remain distinguishable to the reader.