Documentation
¶
Overview ¶
Package nodes_bench provides bench.run (measure latency distribution of an action), bench.save (write results to a file), and bench.compare (diff against a stored baseline).
Typical use:
{ action: "log.info", iterations: 100, payload: { message: "x" } } -> bench.run
{ file: "bench/baseline.json" } -> bench.save
{ baseline: "bench/baseline.json", tolerance_pct: 5 } -> bench.compare
Index ¶
Constants ¶
const ID = "nodes_bench"
Variables ¶
var BenchCompare = action.New("bench.compare", func(_ context.Context, req BenchCompareReq) (BenchCompareRes, error) {
return runCompare(req)
}).Description("Compare current benchmark against a baseline file").
Tag("bench", "compare").
Build()
BenchCompare diffs the current benchmark against a stored baseline. A non-zero tolerance allows small fluctuations to pass.
var BenchRun = action.New("bench.run", func(ctx context.Context, req BenchRunReq) (BenchRunRes, error) { resolver := contracts.ActionResolverFromContext(ctx) if resolver == nil { return BenchRunRes{}, xerr.Internal("bench.run: no action resolver in context") } return runBenchmark(ctx, resolver, req) }).Description("Run an action N times and report latency distribution"). Tag("bench", "perf"). Build()
var BenchSave = action.New("bench.save", func(_ context.Context, req BenchSaveReq) (BenchSaveRes, error) { clean, err := xfs.Rel(req.File) if err != nil { return BenchSaveRes{}, err } data, err := json.MarshalIndent(req.BenchRunRes, "", " ") if err != nil { return BenchSaveRes{}, xerr.Internal("bench.save: marshal", err) } if dir := filepath.Dir(clean); dir != "" && dir != "." { if err := os.MkdirAll(dir, 0o755); err != nil { return BenchSaveRes{}, xerr.Internal("bench.save: mkdir", err) } } if err := os.WriteFile(clean, data, 0o600); err != nil { return BenchSaveRes{}, xerr.Internal("bench.save: write", err) } return BenchSaveRes{ File: clean, Bytes: len(data), BenchRunRes: req.BenchRunRes, }, nil }).Description("Write benchmark results to a JSON file"). Tag("bench", "io"). Build()
BenchSave writes benchmark results to a JSON file. The path is validated through xfs.Rel, so it must be relative and cannot escape the working directory.
Functions ¶
Types ¶
type BenchCompareReq ¶
type BenchCompareReq struct {
Baseline string `json:"baseline" validate:"required"`
TolerancePct float64 `json:"tolerance_pct,omitempty"`
BenchRunRes
}
BenchCompareReq is a BenchRunRes compared against a baseline file. TolerancePct is the allowed regression percentage; a lower reading for RPS or a higher reading for latency metrics counts as regression.
type BenchCompareRes ¶
type BenchCompareRes struct {
Baseline string `json:"baseline"`
Pass bool `json:"pass"`
Regressions []string `json:"regressions,omitempty"`
Metrics map[string]Metric `json:"metrics"`
}
BenchCompareRes aggregates every metric and the overall verdict.
type BenchRunReq ¶
type BenchRunRes ¶
type BenchRunRes struct {
Action string `json:"action"`
Iterations int `json:"iterations"`
Warmup int `json:"warmup"`
Errors int `json:"errors"`
MinMs float64 `json:"min_ms"`
MaxMs float64 `json:"max_ms"`
MeanMs float64 `json:"mean_ms"`
P50Ms float64 `json:"p50_ms"`
P95Ms float64 `json:"p95_ms"`
P99Ms float64 `json:"p99_ms"`
RPS float64 `json:"rps"`
ElapsedMs int64 `json:"elapsed_ms"`
}
type BenchSaveReq ¶
type BenchSaveReq struct {
File string `json:"file" validate:"required"`
BenchRunRes
}
BenchSaveReq is a BenchRunRes plus a target file. The embedded result is written as-is.
type BenchSaveRes ¶
type BenchSaveRes struct {
File string `json:"file"`
Bytes int `json:"bytes"`
BenchRunRes
}
BenchSaveRes reports what was written. The embedded result is propagated so a pipeline can chain save into compare.
Source Files