canbench

canbench is a tool for benchmarking canisters on the Internet Computer.

Background

Canister smart contracts on the Internet Computer consume compute and memory resources.
Since resources are finite, execution of a message (transaction) must remain within specific bounds:

1. Instructions: A monotonically increasing counter correlated with compute and memory usage.
2. Dirty Pages: The number of memory pages written to.

If a message exceeds these limits, it is aborted. canbench gives developers insights into how their code consumes instructions and memory. Support for reporting dirty pages will be added once the IC exposes that information.

Use Cases

• Analyze instruction, heap, and stable memory usage of canisters
• Detect performance regressions in local or CI environments
• Identify potential performance bottlenecks

Features

• Relevant metrics

  Traditional benchmarking tools rely on repeated runs and averaging time.
  On the deterministic Internet Computer, this is neither necessary nor insightful.
  canbench reports instruction count and memory changes directly.

• Regression detection

  Persist benchmark results in your repo.
  canbench compares results over time to highlight performance regressions.

• High instruction limits

  While regular messages are capped at a few billion instructions, canbench supports up to 10 trillion, allowing deep benchmarking.

• Language-agnostic

  While currently Rust-focused, canbench is designed to support canisters written in any language.

Installation

cargo install canbench

Quickstart (Rust)

See the crate's documentation.

GitHub CI Support

You can integrate canbench into your GitHub CI pipeline to catch regressions automatically.

You’ll need:

1. Benchmark scripts (see scripts/ directory)

2. A workflow that posts benchmarking results as PR comments (canbench-post-comment.yml)

3. A job to upload the PR number (see upload-pr-number in ci.yml)

4. The benchmark job itself (e.g. benchmark-fibonacci-example in ci.yml)

Once configured, the job will fail on regressions and pass otherwise. It will also leave a PR comment with detailed results. See this PR example.