Writing Benchmarks in Go

Create benchmarks for your Go codebase using the testing package

The Go integration is still in early development, and only some go test CLI flags are supported. See the compatibility section for more information on how to ensure your benchmarks work with CodSpeed.

Additionally, only the walltime instrument is currently supported

If you have any feedback, please reach out to us via Discord or email our support.

Integrating CodSpeed into your Go codebase requires no modification. You can continue using go test and the testing package as you normally would. When running your benchmarks in CI with CodSpeed, your benchmarks will automatically be built and the reports will be sent to CodSpeed.

Creating benchmarks

You can just use the testing package to write benchmarks in Go. If the benchmarks are working with go test, then they will also automatically be detected by CodSpeed without any additional configuration.

Here’s an example of a simple Fibonacci function benchmark:

fib_test.go

package example

import "testing"

func BenchmarkFibonacci10(b *testing.B) {
  for b.Loop() {
    fib(10)
  }
}

We recommend using b.Loop() as it’s more precise and efficient.

Still, for i := 0; i < b.N; i++ is also supported for backward compatibility (before Go 1.24):

func BenchmarkFibonacci20(b *testing.B) {
  for i := 0; i < b.N; i++ {
    fib(20)
  }
}

For a deeper dive into Go benchmarking, see the dedicated guide:

How to Benchmark Go with the testing Package

An in-depth guide to writing Go benchmarks: sub-benchmarks, parallel benchmarks, benchstat, pprof, and CodSpeed CI integration.

Testing the benchmarks locally

To run the benchmarks with CodSpeed locally, you need to install the codspeed runner:

terminal

curl -fsSL https://codspeed.io/install.sh | sh

You can then run your go test command with CodSpeed:

terminal

$ codspeed run --skip-upload -- go test -bench=.
►►► Running the benchmarks
[INFO  go_runner] Discovered 1 package
[INFO  go_runner] Total benchmarks discovered: 2
[INFO  go_runner] Found BenchmarkFibonacci10           in "fib_test.go"
[INFO  go_runner] Found BenchmarkFibonacci20           in "fib_test.go"
[INFO  go_runner] Generating custom runner for package: example
[INFO  go_runner] Running benchmarks for package: example
Running with CodSpeed instrumentation
goos: linux
goarch: amd64
cpu: 12th Gen Intel(R) Core(TM) i7-1260P @ 1215.790MHz
BenchmarkFibonacci10-16         	 1348328	       361.9 ns/op
BenchmarkFibonacci20-16         	  106713	       47947 ns/op
PASS
[INFO  go_runner] Parsed 2 raw results
[INFO  go_runner] Results written to "/tmp/profile.qPQgi6h0iK.out/results/231603.json"

This will print all the benchmarks that can be run with CodSpeed and warnings if some benchmarks are not supported.

Running the benchmarks in your CI

To generate performance reports, you need to run the benchmarks in your CI. This allows CodSpeed to automatically run benchmarks and warn you about regressions during development.

If you want more details on how to configure the CodSpeed action, you can check out the Continuous Reporting section.

Here is an example of a GitHub Actions workflow that runs the benchmarks and reports the results to CodSpeed on every push to the main branch and every pull request:

Incomplete flamegraphs on ARM64?

If your flamegraphs appear incomplete on ARM64 (e.g., on CodSpeed Macro runners), try setting the CODSPEED_PERF_UNWINDING_MODE environment variable to fp:

- uses: CodSpeedHQ/action@v4
  with:
    run: go test -bench=.
    instruments: walltime
  env:
    CODSPEED_PERF_UNWINDING_MODE: fp

This switches from DWARF-based unwinding to frame-pointer-based unwinding, which produces more reliable call stacks for Go on ARM64. CodSpeed tries to detect this automatically, but it cannot catch every case.

Recipes

Sharding benchmarks in parallel CI jobs

If your benchmarks are taking too much time to run under the CodSpeed action, you can run them in parallel to speed up the execution.

To parallelize your benchmarks, simply add filters to the go test command to only run a subset of benchmarks in each job.

Compatibility

We only support the following flags for go test:

• -bench (required)

If you run into issues or require certain features, please open an issue or join our Discord to get help.

Next steps

Walltime instrument

Learn more about the Walltime instrument and how to use it.

How to Benchmark Go with the testing Package

An in-depth guide to writing Go benchmarks with CodSpeed.

Dive into performance changes

Learn more about profiling and how to read flamegraphs.

Example repository with benchmarks

The example GitHub repository for this Gin Gonic API with benchmarks.