codspeed-setup-harness

ハーネスのセットアップ

パフォーマンスエンジニアとして、プロジェクトのベンチマークと CodSpeed 連携をセットアップします。目標は、実用的で代表性のあるベンチマークを作成し、CodSpeed でパフォーマンスを測定・追跡できるように設定することです。

ステップ 1：プロジェクトを分析する

ベンチマークコードを書く前に、対象となるプロジェクトを把握します。

1. 言語とビルドシステムを検出する：プロジェクトの構成、パッケージファイル（Cargo.toml、package.json、pyproject.toml、go.mod、CMakeLists.txt）、ソースファイルを確認します。

2. 既存のベンチマークを特定する：ベンチマークファイル、codspeed.yml、CodSpeed またはベンチマークに言及している CI ワークフローを確認します。

3. ホットパスを特定する：コードベースを確認し、パフォーマンスが重要なコードを把握します。公開 API 関数、データ処理パイプライン、I/O 負荷の高い操作、アルゴリズムコードが適した候補です。

4. CodSpeed の認証を確認する：codspeed auth login を実行済みであることを確認します。

ステップ 2：適切なアプローチを選ぶ

言語とベンチマーク対象に応じて、適切なハーネスを選びます。

言語別ハーネス（利用可能な場合に推奨）

これらは CodSpeed と深く連携し、ベンチマークごとのフレームグラフ、きめ細かな比較、シミュレーションモードのサポートを提供します。

言語	フレームワーク	セットアップ方法
Rust	divan（推奨）、criterion、bencher	cargo add --rename を使って codspeed-<framework>-compat を依存関係に追加します
Python	pytest-benchmark	pytest-codspeed をインストールし、@pytest.benchmark または benchmark フィクスチャを使用します
Node.js	vitest（推奨）、tinybench v5、benchmark.js	@codspeed/<framework>-plugin をインストールし、vitest／テストの設定で構成します
Go	go test -bench	パッケージは不要です。CodSpeed が go test -bench を直接計測します
C/C++	Google Benchmark	CMake でビルドします。CodSpeed は valgrind-codspeed 経由で計測します

Exec ハーネス（汎用）

あらゆる言語で使用できます。また、個々の関数ではなくプログラム全体をベンチマークする場合にも使えます。

• 単発のベンチマークには codspeed exec -m <mode> -- <command> を使用します
• または、再現可能なセットアップのためにベンチマーク定義を含む codspeed.yml を作成します

Exec ハーネスではコードの変更は不要です。バイナリを外部から計測します。以下の場合に最適です。

• 専用の CodSpeed 連携がない言語
• エンドツーエンドのベンチマーク（プログラム全体の実行）
• コマンドのパフォーマンスを手早く追跡したい場合

シミュレーションモードと実時間モードの選択

• Simulation（Rust、Python、Node.js、C/C++ でデフォルト）：決定論的な CPU シミュレーションで、ばらつきは 1% 未満、フレームグラフは自動生成されます。CPU 負荷の高いコードに最適です。システムコールや I/O は測定しません。
• Walltime（Go でデフォルト）：I/O、スレッド処理、システムコールを含む実際の実行時間を測定します。I/O 負荷の高いコードやマルチスレッドコードに最適です。一貫したハードウェアが必要です（CI では CodSpeed Macro Runners を使用してください）。
• Memory：ヒープ割り当てを追跡します。メモリ使用量の削減に最適です。libc／jemalloc／mimalloc を使用する Rust、C/C++ でサポートされています。

ステップ 3：ハーネスをセットアップする

divan を使った Rust（推奨）

1. 依存関係を追加します。

cargo add divan
cargo add codspeed-divan-compat --rename divan --dev

2. benches/ にベンチマークファイルを作成します。

// benches/my_bench.rs
use divan;

fn main() {
    divan::main();
}

#[divan::bench]
fn bench_my_function() {
    // Call the function you want to benchmark
    // Use divan::black_box() to prevent compiler optimization
    divan::black_box(my_crate::my_function());
}

3. Cargo.toml に追加します。

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

4. ビルドして実行します。

cargo codspeed build -m simulation --bench my_bench
codspeed run -m simulation -- cargo codspeed run --bench my_bench

criterion を使った Rust

1. 依存関係を追加します。

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

2. benches/ にベンチマークを作成します。

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

fn bench_my_function(c: &mut Criterion) {
    c.bench_function("my_function", |b| {
        b.iter(|| my_crate::my_function())
    });
}

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

3. Cargo.toml に追加し、divan と同じ方法でビルド／実行します。

pytest-codspeed を使った Python

1. インストールします。

pip install pytest-codspeed
# or
uv add --dev pytest-codspeed

2. ベンチマークテストを作成します。

# tests/test_benchmarks.py
import pytest

def test_my_function(benchmark):
    result = benchmark(my_module.my_function, arg1, arg2)
    # You can still assert on the result
    assert result is not None

# Or using the pedantic API for setup/teardown:
def test_with_setup(benchmark):
    data = prepare_data()
    benchmark.pedantic(my_module.process, args=(data,), rounds=100)

3. 実行します。

codspeed run -m simulation -- pytest --codspeed

vitest を使用した Node.js（推奨）

1. インストールします。

npm install -D @codspeed/vitest-plugin
# or
pnpm add -D @codspeed/vitest-plugin

2. vitest を設定します（vitest.config.ts）。

import { defineConfig } from "vitest/config";
import codspeed from "@codspeed/vitest-plugin";

export default defineConfig({
  plugins: [codspeed()],
});

3. ベンチマークファイルを作成します。

// bench/my.bench.ts
import { bench, describe } from "vitest";

describe("my module", () => {
  bench("my function", () => {
    myFunction();
  });
});

4. 実行します。

codspeed run -m simulation -- npx vitest bench

Go

パッケージは不要です。CodSpeed は go test -bench を直接計測します。

1. ベンチマークテストを作成します。

// my_test.go
func BenchmarkMyFunction(b *testing.B) {
    for i := 0; i < b.N; i++ {
        MyFunction()
    }
}

2. 実行します（Go では walltime がデフォルトです）。

codspeed run -m walltime -- go test -bench . ./...

Google Benchmark を使用した C/C++

1. Google Benchmark をインストールします（CMake FetchContent またはシステムパッケージを使用）。

2. ベンチマークを作成します。

#include <benchmark/benchmark.h>

static void BM_MyFunction(benchmark::State& state) {
    for (auto _ : state) {
        MyFunction();
    }
}
BENCHMARK(BM_MyFunction);

BENCHMARK_MAIN();

3. CodSpeed でビルドして実行します。

cmake -B build && cmake --build build
codspeed run -m simulation -- ./build/my_benchmark

Exec ハーネス（任意の言語）

コードを変更せずにプログラム全体をベンチマークする場合：

1. codspeed.yml を作成します。

$schema: https://raw.githubusercontent.com/CodSpeedHQ/codspeed/refs/heads/main/schemas/codspeed.schema.json

options:
  warmup-time: "1s"
  max-time: 5s

benchmarks:
  - name: "My program - small input"
    exec: ./my_binary --input small.txt

  - name: "My program - large input"
    exec: ./my_binary --input large.txt
    options:
      max-time: 30s

2. 実行します。

codspeed run -m walltime

または、1 回だけ実行する場合：

codspeed exec -m walltime -- ./my_binary --input data.txt

ステップ 4：適切なベンチマークを作成する

適切なベンチマークは、実際の状況を反映し、分離され、安定しています。以下のガイドラインを参考にしてください。

• 実際のワークロードをベンチマークする：現実的な入力データとサイズを使用します。10 個の要素をソートするベンチマークでは、1,000 万個の要素のパフォーマンスは分かりません。

• セットアップのベンチマークを避ける：初期化処理を測定対象から除外するため、フレームワークのセットアップ／ティアダウン機能を使用します。

• デッドコードの削除を防ぐ：コンパイラーが未使用の結果を最適化で削除しないよう、black_box()（Rust）、benchmark::DoNotOptimize（C++）、または Blackhole.consume（JMH）を使用します。

• クリティカルパスを対象にする：ユーザーにとって最も重要な関数、つまり頻繁に呼び出される関数やホットパス上の関数をベンチマークします。

• 複数のシナリオをテストする：入力サイズ、データ分布、エッジケースを変えてテストします。パフォーマンス特性は、規模によって変化することがよくあります。

• ベンチマークを短時間で実行できるようにする：個々のベンチマークは、数ミリ秒から数秒程度で完了するようにします。CodSpeed がウォームアップと反復を処理するため、単一の反復を用意してください。

ステップ 5：検証して実行する

セットアップが完了したら、次の操作を行います。

1. ベンチマークをローカルで実行して、正常に動作することを確認します。

# For language-specific harnesses
cargo codspeed build -m simulation && codspeed run -m simulation -- cargo codspeed run
# or
codspeed run -m simulation -- pytest --codspeed
# or
codspeed run -m simulation -- npx vitest bench
# etc.

# For exec harness
codspeed run -m walltime

2. 出力を確認します：結果の表と CodSpeed レポートへのリンクが表示されます。

3. フレームグラフを検証します：シミュレーションモードの場合は、レポートのリンクにアクセスするか、query_flamegraph MCP ツールを使用して、フレームグラフが生成されていることを確認します。

4. セットアップした内容をユーザーに伝え、最初の結果を示し、次のステップ（CI 連携の追加や optimize スキルの実行など）を提案します。