Documentation
¶
Overview ¶
Package benchmarkreport converts captured `go test -bench` text output and a run-metadata sidecar into a deterministic offline JSON report (schemaVersion 1). The converter is purely local: it reads two files, performs no network calls, and emits no telemetry.
Contract notes:
- A benchmark line is a line whose first field begins with "Benchmark". Framework lines `go test` prints around results (goos/goarch/pkg/cpu/ coverage headers, PASS/FAIL/ok/?, and -v banners) are ignored; any other line is rejected so corrupted input fails loudly instead of silently dropping samples.
- The name is kept verbatim, including the "-N" GOMAXPROCS suffix Go appends (for example BenchmarkCLIStatus-10). Dropping it would merge samples taken at different GOMAXPROCS values into one summary.
- ns/op is the mean nanoseconds per operation across that sample's b.N iterations. Summary statistics therefore describe the distribution of sample means, never a per-operation percentile; no p95 is emitted.
- samples are sorted by name ascending (byte-wise); samples sharing a name keep input order (stable sort). summary entries are sorted by name.
- For a name with an even number of samples the median is the arithmetic mean of the two central values; for an odd count it is the middle value.
Index ¶
Constants ¶
const SchemaVersion = 1
SchemaVersion is the report schema this package emits.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Metadata ¶
type Metadata struct {
SourceCommit string `json:"sourceCommit"`
GoVersion string `json:"goVersion"`
GitVersion string `json:"gitVersion"`
OS string `json:"os"`
Arch string `json:"arch"`
Workload string `json:"workload"`
ObservedAt string `json:"observedAt"`
MeasurementCommand string `json:"measurementCommand"`
Note string `json:"note,omitempty"`
}
Metadata is the run sidecar embedded verbatim in the report. Every field except Note is required and must be non-empty; unknown keys are rejected so a typo fails conversion instead of silently dropping data. observedAt should be an RFC 3339 timestamp.
func ParseMetadata ¶
ParseMetadata decodes and validates the metadata sidecar document. It rejects malformed JSON, trailing data, unknown keys, and any missing or blank required field.
type NameSummary ¶
type NameSummary struct {
Name string `json:"name"`
SampleCount int `json:"sampleCount"`
MinMeanNsPerOp float64 `json:"minMeanNsPerOp"`
MedianMeanNsPerOp float64 `json:"medianMeanNsPerOp"`
MaxMeanNsPerOp float64 `json:"maxMeanNsPerOp"`
}
NameSummary aggregates every sample that shares a name. The Min/Median/Max fields are statistics over the samples' nsPerOp means -- the distribution of sample means, not per-operation latencies.
type Report ¶
type Report struct {
SchemaVersion int `json:"schemaVersion"`
Metadata Metadata `json:"metadata"`
Samples []Sample `json:"samples"`
Summary []NameSummary `json:"summary"`
}
Report is the schema v1 document the converter emits.
func BuildReport ¶
BuildReport assembles the report from parsed parts. Samples are sorted by name ascending (stable, so equal names keep input order) and summarized per name in that same order.
type Sample ¶
type Sample struct {
Name string `json:"name"`
Iterations int64 `json:"iterations"`
NsPerOp float64 `json:"nsPerOp"`
}
Sample is one benchmark result line: name, its b.N iterations, and the reported ns/op mean for that run.
func ParseBenchmarks ¶
ParseBenchmarks parses standard `go test -bench` output and returns one Sample per benchmark result line, in input order. It rejects malformed benchmark lines, non-positive iterations, non-positive ns/op values, lines without an ns/op metric, unrecognized lines, and input with no samples.
Source Files