THE GITHTML FIELD GUIDE
Performance investigation report template with reproducible evidence
A performance report should state the question, workload, environment, measurement method, and uncertainty before recommending a change. Separate observations from explanations and compare like with like. Include enough detail for another engineer to repeat the investigation, while keeping raw traces and sensitive payloads out of a casually shared document.
Write a question that can be answered
Replace make it faster with a scoped question such as whether report rendering spends most of its time waiting for a dependency under a specified test workload. This is an illustrative investigation, not a benchmark result. Define the user-visible interval being measured and identify the relevant code revision. OpenTelemetry's observability primer distinguishes telemetry signals that can support an investigation; your report should explain which signal answers which question. A trace, a counter, and a screenshot of a chart do not automatically establish the same fact.
Record the measurement envelope
Include device or host characteristics, runtime configuration, input size, concurrency, warmup assumptions, and the number of observations actually collected. Explain exclusions and unusual events. Present the baseline and candidate under comparable conditions, preserving unsuccessful or inconclusive trials. Do not invent a percentage improvement to make the report feel complete. If the investigation lacks representative data, say that the result is provisional and specify the missing experiment. Keep a direct connection between a numerical claim and the underlying measurement window.
- Question: identify the exact interval or resource under investigation.
- Method: describe workload, environment, revision, and collection procedure.
- Result: report the observed distribution and limitations rather than one favorable sample.
Separate recommendations from proof
A plausible cause is a hypothesis until evidence supports it. Propose the smallest follow-up that could distinguish competing explanations, and note any risk of running that experiment on a live service. Summarize the decision at the top of the HTML report: proceed, collect more evidence, or reject the proposed change. Put detailed traces in an appendix or linked artifact with suitable access controls. The document should help a mobile reviewer understand the confidence of the conclusion, not require them to infer confidence from the report's visual polish.
Sources and further reading
AI-assisted writing with source-linked guidance and illustrative examples. Read our editorial approach or report a correction.