Writing Benchmarks with criterion.rs

​

Installation

Install the criterion.rs compatibility layer:

cargo add --dev codspeed-criterion-compat --rename criterion

Or directly change your Cargo.toml if you already have criterion installed:

[dev-dependencies]
criterion = { package = "codspeed-criterion-compat", version = "*" }

This will install the codspeed-criterion-compat crate and rename it to criterion in your Cargo.toml. This way, you can keep your existing imports and the compatibility layer will take care of the rest.

​

Usage

​

Creating benchmarks

As an example, let’s follow the example from the Criterion.rs documentation: a benchmark suite for the Fibonacci function:

use criterion::{black_box, criterion_group, criterion_main, Criterion};

fn fibonacci(n: u64) -> u64 {
    match n {
        0 => 1,
        1 => 1,
        n => fibonacci(n-1) + fibonacci(n-2),
    }
}

pub fn criterion_benchmark(c: &mut Criterion) {
    c.bench_function("fib 20", |b| b.iter(|| fibonacci(black_box(20))));
}

criterion_group!(benches, criterion_benchmark);
criterion_main!(benches);

The last step in creating the Criterion benchmark is to add the new benchmark target in your Cargo.toml:

[[bench]]
name = "my_benchmark"
harness = false

And that’s it! You can now run your benchmark suite with CodSpeed

​

Testing the benchmarks locally

$ cargo codspeed build
    Finished release [optimized] target(s) in 0.12s
    Finished built 1 benchmark suite(s)

$ cargo codspeed run
   Collected 1 benchmark suite(s) to run
     Running my_benchmark
Using codspeed-criterion-compat v1.0.0 compatibility layer
NOTICE: codspeed is enabled, but no performance measurement will be made since it's running in an unknown environment.
Checked: benches/bencher_example.rs::fib_20 (group: benches)
        Done running bencher_example
    Finished running 1 benchmark suite(s)

Congrats ! 🎉 You can now run those benchmark in your CI to get the actual performance measurements 👇.

​

Running the benchmarks in your CI

To generate performance reports, you need to run the benchmarks in your CI. This allows CodSpeed to detect the CI environment and properly configure the instrumented environment.

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:

name: CodSpeed

on:
  push:
    branches:
      - "main" # or "master"
  pull_request:
  # `workflow_dispatch` allows CodSpeed to trigger backtest
  # performance analysis in order to generate initial data.
  workflow_dispatch:

jobs:
  benchmarks:
    name: Run benchmarks
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup rust toolchain, cache and cargo-codspeed binary
        uses: moonrepo/setup-rust@v1
        with:
          channel: stable
          cache-target: release
          bins: cargo-codspeed

      - name: Build the benchmark target(s)
        run: cargo codspeed build

      - name: Run the benchmarks
        uses: CodSpeedHQ/action@v3
        with:
          run: cargo codspeed run
          token: ${{ secrets.CODSPEED_TOKEN }}

​

Recipes

​

Running benchmarks in parallel CI jobs

With Rust, if you use multiple packages, a first sharding optimization is to split your benchmarks across these packages.

For example, using Github Actions:

jobs:
  benchmarks:
    name: Run benchmarks
    runs-on: ubuntu-latest
    strategy:
      matrix:
        package:
          - my-first-package
          - my-second-package
    steps:
      - uses: actions/checkout@v4

      - name: Setup rust toolchain, cache and cargo-codspeed binary
        uses: moonrepo/setup-rust@v1
        with:
          channel: stable
          cache-target: release
          bins: cargo-codspeed

      - name: Build the benchmark target(s)
        run: cargo codspeed build -p ${{ matrix.package }}

      - name: Run the benchmarks
        uses: CodSpeedHQ/action@v3
        with:
          # Note: it is not required to pass a `-p` flag as only the benchmarks
          # built by `cargo codspeed build` will be run
          run: cargo codspeed run
          token: ${{ secrets.CODSPEED_TOKEN }}

For more information about multiple packages, check the cargo-codspeed docs.

With Criterion, there is currently no way to split your benchmarks automatically, but you can use a filter expression (view docs).

Learn more about benchmark sharding and how to integrate with your CI provider.