A precision benchmarking utility for Go that corrects for clock drift, CPU scaling, and warm-up bias. Provides statistically meaningful measurements with confidence intervals and variance metrics.

• Clock Drift Correction: Automatically detects and corrects for timing measurement overhead
• CPU Scaling Detection: Identifies CPU frequency scaling effects on benchmark results
• Warm-up Bias Elimination: Discards initial iterations to ensure accurate measurements
• Statistical Analysis:
  • Mean, median, min, max durations
  • Standard deviation and variance
  • 95% and 99% confidence intervals
• Flexible Configuration: Customizable iteration counts, durations, and analysis parameters
• Easy to Use: Simple API similar to standard Go benchmarks

go get github.com/BaseMax/go-benchclock

package main import ( "fmt" "github.com/BaseMax/go-benchclock" ) func main() { // Create a benchmark bench := benchclock.New("MyBenchmark", func() { // Code to benchmark sum := 0 for i := 0; i < 1000; i++ { sum += i } }) // Run the benchmark result, err := bench.Run() if err != nil { panic(err) } // Print the results fmt.Println(result.String()) }

Customize benchmark behavior with a custom configuration:

config := &benchclock.Config{ MinIterations: 100, // Minimum number of iterations MaxIterations: 100000, // Maximum number of iterations MinDuration: time.Second, // Minimum benchmark duration WarmupIterations: 10, // Warm-up iterations to discard CorrectClockDrift: true, // Enable clock drift correction DetectCPUScaling: true, // Enable CPU scaling detection } bench := benchclock.New("MyBenchmark", fn).WithConfig(config)

Note: The tool automatically provides both 95% and 99% confidence intervals in the output.

Benchmark: String Builder Iterations: 2156 Mean: 932.5µs Median: 925.1µs StdDev: 45.2µs Variance: 2043.04 ns² Min: 850.3µs Max: 1.12ms 95% Confidence Interval: [910.3µs, 954.7µs] 99% Confidence Interval: [895.1µs, 969.9µs] Clock Drift Correction: 125 ns CPU Scaling Factor: 1.0234 Warmup Iterations Discarded: 20 

benchmarks := []*benchclock.Benchmark{ benchclock.New("Benchmark1", func1), benchclock.New("Benchmark2", func2), } results, err := benchclock.RunMultiple(benchmarks) if err != nil { panic(err) } // Compare results fmt.Println(benchclock.Compare(results[0], results[1]))

See the example directory for a complete working example:

cd example go run main.go

The tool measures the overhead of calling time.Now() repeatedly and subtracts this overhead from benchmark measurements to provide more accurate timing.

Runs a simple computational benchmark multiple times to detect CPU frequency scaling by analyzing the coefficient of variation in execution times.

Executes the benchmark function multiple times before starting measurements to ensure the CPU cache is warm and the JIT compiler has optimized the code.

• Calculates mean, median, standard deviation, and variance
• Provides 95% and 99% confidence intervals using z-scores
• Tracks minimum and maximum observed durations

This project is licensed under the GPL-3.0 License - see the LICENSE file for details.

Contributions are welcome! Please feel free to submit a Pull Request.