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: 適切なアプローチを選択

言語とユーザーがベンチマークしたいことに基づいて、適切な harness を選択します:

言語固有の harness (利用可能な場合は推奨)

これらは 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 harness (ユニバーサル)

任意の言語、またはプログラム全体をベンチマークしたい場合 (個別関数ではなく):

• codspeed exec -m <mode> -- <command> を一度限りのベンチマークに使用
• または codspeed.yml でベンチマーク定義を作成し、再利用可能なセットアップに

Exec harness はコード変更を必要としません — バイナリを外部からインストルメントします。以下の場合に理想的です:

• 専用 CodSpeed 統合のない言語
• エンドツーエンドベンチマーク (完全なプログラム実行)
• コマンドのパフォーマンスを追跡したいだけの場合の高速セットアップ

シミュレーション vs ウォールタイムモードの選択

• シミュレーション (Rust, Python, Node.js, C/C++ のデフォルト): 確定的 CPU シミュレーション、分散 <1%、自動フレームグラフ。CPU バウンドコード向け。システムコールや I/O を測定しません。
• ウォールタイム (Go のデフォルト): I/O、スレッド、システムコールを含む実行時間を測定します。I/O 集約的またはマルチスレッドコード向け。一貫性のあるハードウェアが必要 (CI で CodSpeed Macro Runners を使用)。
• メモリ: ヒープアロケーションを追跡します。メモリ使用量削減向け。Rust, C/C++ with libc/jemalloc/mimalloc でサポート。

ステップ 3: harness をセットアップ

Rust with divan (推奨)

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() {
    // ベンチマークしたい関数を呼び出します
    // divan::black_box() を使ってコンパイラの最適化を防ぎます
    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

Rust with criterion

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 と同じようにビルド/実行します。

Python with pytest-codspeed

1. インストール:

pip install pytest-codspeed
# または
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)
    # 結果に対してアサートできます
    assert result is not None

# または pedantic API を使ってセットアップ/ティアダウン:
def test_with_setup(benchmark):
    data = prepare_data()
    benchmark.pedantic(my_module.process, args=(data,), rounds=100)

3. 実行:

codspeed run -m simulation -- pytest --codspeed

Node.js with vitest (推奨)

1. インストール:

npm install -D @codspeed/vitest-plugin
# または
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 のデフォルト):

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

C/C++ with Google Benchmark

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 harness (任意の言語)

コード変更なしでプログラム全体をベンチマーク:

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

または一度限りの場合:

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

ステップ 4: 優れたベンチマークを書く

優れたベンチマークは代表的で、隔離され、安定しています。ガイドラインは以下の通りです:

• 実際のワークロードをベンチマーク: 現実的な入力データとサイズを使用します。10 要素のソートベンチマークは 1000 万要素でどうなるかについて何も教えてくれません。

• セットアップをベンチマークしない: フレームワークのセットアップ/ティアダウンメカニズムを使用して、初期化を測定から除外します。

• デッドコード排除を防ぐ: black_box() (Rust)、benchmark.pedantic() (Python)、または同等のものを使用してコンパイラ/ランタイムが測定している作業を最適化しないようにします。

• クリティカルパスをカバー: ユーザーにとって最も重要な関数 — 頻繁に呼ばれるか、ホットパスにあるもの — をベンチマークします。

• 複数のシナリオをテスト: 異なる入力サイズ、異なるデータ分布、エッジケース。パフォーマンス特性はスケールで変わることが多いです。

• ベンチマークを高速に: 個別のベンチマークはミリ秒から低秒で完了する必要があります。CodSpeed はウォームアップと繰り返しを処理します — 単一イテレーションを提供します。

ステップ 5: 検証と実行

セットアップ後:

1. ローカルでベンチマークを実行して動作を確認:

# 言語固有の harness の場合
cargo codspeed build -m simulation && codspeed run -m simulation -- cargo codspeed run
# または
codspeed run -m simulation -- pytest --codspeed
# または
codspeed run -m simulation -- npx vitest bench
# など

# exec harness の場合
codspeed run -m walltime

2. 出力を確認: 結果テーブルと CodSpeed レポートへのリンクが表示されるはずです。

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

4. ユーザーに通知してセットアップ内容を説明し、最初の結果を示し、次のステップを提案します (例えば CI 統合の追加、optimize スキルの実行)。