Goku

Goku

Goku は、ウェブサービスのベンチマークとパフォーマンス分析を目的に設計された、高性能でスケーラブルな HTTP 負荷テストツールです。Drill や Vegeta などのツールに着想を得ており、エンジニアが効率よくトラフィックをシミュレートして分析できるよう、最新の機能とシンプルさを備えています。

機能

• 高速でスケーラブルな HTTP 負荷テスト
• 長時間のテスト中にリアルタイムで統計情報を表示
• 一定レートの負荷プロファイルに対応するレート制限（--rps）
• 複数ステップの連続シナリオ（1 回のテストで複数のエンドポイントを実行）
• URL と本文での変数テンプレート（{{uuid}}、{{seq}}、{{random_int}}、…）
• 認証機能を内蔵（Bearer トークン、Basic 認証）
• テキスト出力での ASCII レイテンシーヒストグラム
• 2 回のベンチマーク実行結果を比較する compare サブコマンド
• ファイルへの出力（--output-file）とリクエストごとのログ（--results-log）
• HTTP/1.1、HTTP/2 に対応
• 複数の出力形式：text、json、csv
• LLM／エージェントとの連携に対応する MCP（Model Context Protocol）サーバー
• 実行履歴を保存して比較できるよう、結果を Observability Insight に送信

---

CLI のインストール

自動ダウンロード（Linux、OSX、WSL）

curl -sSL https://raw.githubusercontent.com/jcaromiq/goku/v3.0.0/scripts/install.sh | sh

Cargo を使用

cargo install goku-bench
goku --version

手動ダウンロード

Goku の GitHub Releases ページにアクセスし、お使いのシステム向けの最新の .tar.gz をダウンロードしてください。

• Linux（x86_64、arm64）
• macOS（x86_64）
• Windows（x86_64）

ソースからビルド

cargo build --release

---

Observability Insight との連携

Goku は、各実行の最終結果を Observability Insight のプロジェクトに送信できます。ここではパフォーマンステストの履歴を確認し、実行結果を比較して性能の劣化を検出できます。まず、プロジェクトで Goku コネクターを有効にしてください。

ログイン（ローカルマシン）

goku login

Goku がブラウザーを開くので、ログインしてプロジェクトを選択してください。そのプロジェクトの Goku コネクター用トークンが ~/.config/goku/credentials.json に保存されます（権限は 0600。macOS／Windows では OS の設定ディレクトリが使用されます）。URL のみを表示するには --no-browser を、別のポータルを指定するには --portal-url を使用してください。

結果の送信

goku -c 50 -d 30 --target https://api.example.com/users --report --report-name "users list" --report-tag nightly

送信されるのは最終サマリー（スループット、レイテンシーパーセンタイル、ステータスコード、テスト設定）のみです。送信前に、対象 URL のクエリー文字列と認証情報は削除されます。レポートを送信できない場合、Goku はゼロ以外の終了ステータスで終了します。

CI

CI ではブラウザーを使用できません。プロジェクトの Goku コネクター設定でトークンを作成し、GOKU_OI_TOKEN として設定してください（別のポータルを使用する場合は、必要に応じて GOKU_OI_URL も設定します）。環境変数は認証情報ファイルより優先されます。コミットとブランチは GitHub Actions および GitLab CI で検出されます。

- run: goku -c 20 -d 60 --target https://staging.example.com --report --report-name "staging smoke"
  env:
    GOKU_OI_TOKEN: ${{ secrets.GOKU_OI_TOKEN }}

ステータスとログアウト

goku status   # project, connector and token in use
goku logout   # removes the local credentials file

goku logout はローカルファイルを削除するだけです。トークンを無効にするには、ポータルの Goku コネクター設定で取り消してください。

---

MCP（Model Context Protocol）への対応

Goku は Model Context Protocol（MCP） と連携します。任意の LLM エージェントまたは MCP 対応クライアントから、プログラムで Goku を使用できます。

できること

• LLM または AI エージェントから Goku を使用できます。CLI を手動で操作する必要はありません。
• 負荷テストを自動化されたワークフローと組み合わせ、エージェントやスクリプト内からテストを実行し、メトリクスを収集して結果を分析できます。
• より広範なツールチェーンやエージェントパイプラインにシームレスに統合できます。

LLM での使用例

Goku を MCP ツールとして登録したら、LLM に次のように依頼できます。

"https://api.example.com/users に対して、HTTP/2 を使用し、同時クライアント数 50、30 秒間の負荷テストを実行して、p95 と p99 のレイテンシを教えてください。"

LLM は run_benchmark MCP ツールを呼び出し、構造化された完全なレポートを返します。

MCP サーバーのインストール

# Automatic download
curl -sSL https://raw.githubusercontent.com/jcaromiq/goku/v3.0.0/scripts/install_mcp.sh | sh

# Or via Cargo
cargo install goku-mcp

MCP ツール：run_benchmark

MCP サーバーは、次のパラメーターを持つ統合ツールを 1 つ公開します。

パラメーター	型	必須	説明
target	string	✅	メソッドのプレフィックスを任意で付けた URL。例："POST http://api.example.com/users"
clients	number	✅	同時に実行するワーカーの数
requests	number	—	リクエストの合計数（duration_secs が設定されている場合は無視されます）
duration_secs	number	—	テスト時間（秒単位。requests の代わりに指定します）
body	string	—	POST/PUT/PATCH のリクエストボディ
headers	string[]	—	"Name:Value" 形式のヘッダー
http2	boolean	—	HTTP/2 の事前知識を使用する
ramp_up	number	—	ワーカーの起動を分散させる時間（秒）
timeout_ms	number	—	リクエストのタイムアウト（ミリ秒、デフォルト：30000）
insecure	boolean	—	無効な TLS 証明書を許可する
rps	number	—	1 秒あたりの最大リクエスト数（レート制限）

すべてのレイテンシパーセンタイル、スループット、ステータスコードの内訳を含む、完全な JSON レポートを返します。

---

バージョン管理

CLI は SemVer v2.0.0 に従ってバージョン管理されています。

貢献

CONTRIBUTING.md を参照してください。

---

使用マニュアル

Usage: goku [OPTIONS] --target <TARGET>
       goku compare <BASELINE> <CANDIDATE>
       goku login | logout | status

Options:
  -v, --verbose                        Runs in verbose mode
  -t, --target <TARGET>                URL to request. Format: [METHOD] <url>  [default: GET]
                                       Example: "POST http://localhost:3000/api"
  -r, --request-body <REQUEST_BODY>    Path to file to use as request body
  -c, --clients <CLIENTS>              Number of concurrent workers [default: 1]
  -i, --iterations <ITERATIONS>        Total number of requests [default: 1]
  -d, --duration <DURATION>            Duration of the test in seconds (alternative to --iterations)
      --headers <HEADERS>              Headers in "Name:Value" format (repeatable)
      --scenario <SCENARIO>            Path to a YAML scenario file
      --timeout <timeout_ms>           Request timeout in ms [default: 30000]
      --http2                          Enable HTTP/2 prior knowledge
      --ramp-up <seconds>              Seconds to spread the start of workers
      --rps <RPS>                      Max requests per second across all clients
      --output <text|json|csv>         Output format [default: text]
      --output-file <PATH>             Write results to file instead of stdout
      --results-log <PATH>             Write per-request CSV log (timestamp, status, latency)
      --live-stats <seconds>           Print live stats every N seconds during the test
      --insecure                       Accept invalid/self-signed TLS certificates
      --auth-bearer <TOKEN>            Set Authorization: Bearer <TOKEN> header
      --auth-basic <USER:PASS>         Set Authorization: Basic <base64> header
      --pool-idle-timeout <seconds>    Connection pool idle timeout [default: 90]
      --disable-keepalive              Disable HTTP keep-alive / connection reuse
      --report                         Send the final results to Observability Insight
      --report-name <NAME>             Name of the run in Observability Insight (requires --report)
      --report-tag <TAG>               Tag for the run in Observability Insight (repeatable, requires --report)
  -h, --help                           Print help
  -V, --version                        Print version

Subcommands:
  compare <BASELINE> <CANDIDATE>       Compare two JSON result files and show a diff table
  login [--portal-url URL] [--no-browser]  Link this machine to an Observability Insight project
  logout                               Remove the stored Observability Insight credentials
  status                               Show the project this machine reports to

---

フラグのリファレンス

--target -t

HTTP メソッドと URL を指定します。メソッドを指定しない場合は、デフォルトで GET になります。

goku --target "GET http://localhost:3000/"
goku --target "POST http://localhost:3000/api"
goku --target http://localhost:3000          # implicit GET

--request-body -r 任意

リクエストボディとして送信する内容を格納したファイルへのパスです。

--clients -c

同時に実行するワーカーの数です。デフォルトは 1 です。

--iterations -i

すべてのワーカーで実行するリクエストの合計数です。デフォルトは 1 です。--duration と併用できません。

--duration -d

固定のリクエスト数ではなく、指定した秒数だけテストを実行します。

--headers 任意

リクエストヘッダーを 1 つ以上追加します。繰り返し指定できます。形式：Name:Value。

goku --headers Content-Type:application/json --headers X-Api-Key:secret ...

--http2 任意

HTTP/2 の事前知識を強制的に使用します（HTTP/1.1 へのアップグレード交渉を省略します）。

--ramp-up 任意

ワーカーの起動を N 秒間に分散させ、段階的なトラフィックの急増をシミュレートします。

--rps 任意

すべてのクライアントを合わせた 1 秒あたりのリクエスト数を制限します。一定レートの負荷プロファイル（Vegeta と同様）に便利です。

goku -c 10 -i 10000 --rps 200 --target http://localhost:3000

--output 任意

出力形式です。有効な値は text（デフォルト）、json、csv です。

--output-file 任意

結果を stdout ではなくファイルに書き込みます。--output のすべての形式で使用できます。

goku -c 50 -i 1000 --output json --output-file results.json --target http://localhost:3000

--results-log 任意

timestamp_ms,num_client,execution,status,latency_ms の列を含む、リクエストごとの CSV ログを書き込みます。

goku -c 50 -i 1000 --results-log requests.csv --target http://localhost:3000

--live-stats 任意

テストの実行中、N 秒ごとに部分的なメトリクス（リクエスト数、RPS、p50、p95）を stderr に出力します。

goku -c 50 --duration 60 --live-stats 5 --target http://localhost:3000
  [live] requests=1250 rps=250.0 p50=45ms p95=120ms

--insecure 任意

無効または自己署名 TLS 証明書を許可します。デフォルトでは無効です。

--auth-bearer 任意

Authorization: Bearer <TOKEN> ヘッダーを自動的に挿入します。

goku --auth-bearer "eyJhbGci..." --target http://api.example.com

--auth-basic 任意

user:password の認証情報から Authorization: Basic <base64> ヘッダーを挿入します。

goku --auth-basic "admin:secret" --target http://api.example.com

--pool-idle-timeout 任意

プールされた接続のアイドルタイムアウト（秒）です。デフォルトは 90 です。

--disable-keepalive 任意

HTTP Keep-Alive と接続の再利用を完全に無効にします。

--scenario 任意

YAML シナリオファイルへのパスです。このオプションを使用すると、--output を除くすべてのフラグが無視され、設定はファイルから読み込まれます。

compare サブコマンド

2 つのベンチマーク JSON 結果ファイルを比較し、色付きの差分テーブルを表示します。

goku compare before.json after.json

---

シナリオファイル形式

target: POST http://localhost:3000/
clients: 50
requests: 1000
duration: 60          # alternative to requests
http2: true
ramp_up: 5
rps: 500              # optional rate limit
output: json
insecure: false
live_stats: 10        # print live stats every 10s
pool_idle_timeout: 30
disable_keepalive: false

headers:
  - key: "Content-Type"
    value: "application/json"
  - key: "X-Api-Key"
    value: "secret"

body: '{"firstName": "Terry", "lastName": "Medhurst", "age": 50}'

# Optional: built-in authentication
auth:
  type: bearer
  token: "my-token"

# Optional: write results to a file
output_file: results.json
results_log: requests.csv

複数ステップのシナリオ

ワーカーごとに複数のエンドポイントを順番に実行します。

clients: 20
duration: 60

steps:
  - target: "GET http://api.example.com/users"
  - target: "POST http://api.example.com/orders"
    body: '{"item": "widget", "qty": 1}'
    headers:
      - key: "Content-Type"
        value: "application/json"
  - target: "GET http://api.example.com/orders/latest"

各ワーカーはすべてのステップを順番に実行し、テストの実行中はそのシーケンスを繰り返します。

変数のテンプレート化

URL と本文で動的なプレースホルダーを使用します。

変数	説明
{{seq}}	リクエストの連番
{{client}}	ワーカー ID
{{timestamp}}	Unix タイムスタンプ（ミリ秒）
{{uuid}}	疑似ランダムな UUID v4
{{random_int(min,max)}}	[min, max] の範囲のランダムな整数

goku -c 10 -i 100 \
  --target "GET http://api.example.com/users/{{random_int(1,500)}}"

goku -c 10 -i 100 \
  --target "POST http://api.example.com/events" \
  --request-body body.json
# body.json: {"id": "{{uuid}}", "seq": {{seq}}, "ts": {{timestamp}}}

---

例

シンプルなターゲット

goku --target "GET http://localhost:3000"
goku --target http://localhost:3000?foo=bar
goku -c 50 -i 1000 --target http://localhost:3000
goku -c 50 --duration 60 --target http://localhost:3000

カスタムヘッダーを指定する場合

goku --target "GET http://localhost:3000" \
     --headers Content-Type:application/json \
     --headers X-Api-Key:secret

リクエスト本文を指定する場合

goku -c 50 -i 1000 -r body.json --target "POST http://localhost:3000"

認証を使用する場合

goku --auth-bearer "my-token" -c 20 -i 500 --target "GET http://api.example.com/protected"
goku --auth-basic "admin:pass" -c 10 -i 100 --target "GET http://api.example.com/admin"

レート制限付きのテスト

goku -c 20 --duration 60 --rps 200 --target http://localhost:3000

ランプアップとファイルへの JSON 出力を指定する場合

goku -c 100 -i 5000 --ramp-up 10 --output json --output-file results.json --target http://localhost:3000

2 回の実行結果を比較する

goku -c 50 -i 1000 --output json --output-file before.json --target http://localhost:3000
# deploy new version...
goku -c 50 -i 1000 --output json --output-file after.json --target http://localhost:3000
goku compare before.json after.json

出力（テキスト）

Concurrency level    50
Time taken           4 seconds
Total requests       1000
Requests/sec         250.00 req/s
Mean                 169.90 ms
Min                  5 ms
Max                  415 ms
p50 (median)         155 ms
p95                  319 ms
p99                  360 ms
p99.9                367 ms

Status codes
  2xx  998
  5xx  2

Latency distribution
      10ms  ████████████████████████████████████████  450
      25ms  █████████████████████████                 280
      50ms  ████████████████                          150
     200ms  ████████                                   80
     415ms  ██                                         40

出力（JSON）

{
  "concurrency": 50,
  "duration_secs": 4.12,
  "total_requests": 1000,
  "requests_per_sec": 242.72,
  "mean_ms": 169.90,
  "min_ms": 5,
  "max_ms": 415,
  "p50_ms": 155,
  "p95_ms": 319,
  "p99_ms": 360,
  "p999_ms": 367,
  "status_2xx": 998,
  "status_4xx": 0,
  "status_5xx": 2,
  "status_other": 0,
  "network_errors": 0
}

---

ライセンス

LICENSE を参照してください。

寄付

このプロジェクトでの取り組みに感謝いただける場合は、少額の寄付を歓迎します。