go-benchclock

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.

Features

• 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

Installation

go get github.com/BaseMax/go-benchclock

Quick Start

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())
}

Configuration

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.

Output Example

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

Running Multiple Benchmarks

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]))

Example

See the example directory for a complete working example:

cd example
go run main.go

How It Works

Clock Drift Correction

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

CPU Scaling Detection

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

Warm-up Bias Elimination

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

Statistical Analysis

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

License

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

Contributing

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