Grafana k6入門:負荷スクリプトと結果の読み方
k6の導入、HTTPスクリプト、VUと到着率、チェックと閾値、依存関係を守るユーザージャーニーを解説。結果出力とアプリケーションのテレメトリーも区別します。
Grafana k6は、コードで負荷を定義してテスト結果を記録するツールです。エンジンはGoで実装され、スクリプトにはJavaScript、現在のバージョンではTypeScriptも使えます。ただしNode.js上では動きません。生成できる負荷はスクリプト、プロトコル、実行機のリソースで変わり、特定のVU数をどの環境でも保証できるわけではありません。
最初にそろえたいのは、何を成功と数えるかです。既定ではHTTP 302も正常な応答として扱われますが、独自の「200である」というチェックには失敗します。VU数も毎秒リクエスト数とは別です。CIの合否判定に使う前に、この違いを確認します。
本記事は公式資料に基づくもので、k6の負荷試験や性能ベンチマークは実施していません。APIとデータはプロジェクト側で用意する必要があります。k6は2021年にGrafana Labsへ加わり(英語)、適切な結果保存先を通じてGrafanaで可視化できます。
k6を選ぶ理由
スクリプトはGitで管理でき、コードレビューやCIに組み込めます。ただしk6だけの特徴ではありません。JMeterは非GUI実行ができ、Locustもスクリプトで動かせます。言語、プロトコル、実行モデル、保守の仕方で比較します。
k6には独自のJS/TS実行環境があります。Node.js組み込みAPIに依存するパッケージを、そのまま持ち込めるとは限りません。以下はプロトコル層のHTTP例であり、ページのJavaScript実行や描画は行いません。ブラウザーテストには対応モジュールと別のリソース予算が必要です。
インストールと実行
次の例をscript.jsとして保存します。実行前に、許可を得たテストAPIのベースアドレスをBASE_URLとしてexportしてください。クエリ文字列やフラグメントは含めません。api.example.comのような名前は説明用であり、公開の負荷試験先ではありません。
# macOSへのインストール
brew install k6
# script.jsとBASE_URLを用意してローカル実行
k6 run script.js
# Dockerの場合:export済みのBASE_URLを渡し、標準入力から読む
docker run --rm -i -e BASE_URL grafana/k6:2.3.0 run - < script.js
Docker例では確認済みの2.3.0タグを指定しています。タグは内容の不変性まで保証しないため、必要なら確認したdigestで固定します。-iはスクリプトを標準入力から渡すための指定です。ローカルファイルや相対モジュールを使う場合は、マウントも必要です。Homebrewの導入バージョンは異なる可能性があるので、k6 versionで確認します。導入(英語) · 実行方法(英語)
最初のスクリプト
import http from 'k6/http';
import { check, sleep } from 'k6';
if (!__ENV.BASE_URL) throw new Error('Set BASE_URL to an authorized test API');
const baseUrl = __ENV.BASE_URL.replace(/\/+$/, '');
export const options = {
vus: 20, // 20 VU。20 RPSという意味ではない
duration: '30s', // 固定VUシナリオの実行時間
thresholds: {
http_req_failed: ['rate<0.01'],
http_req_duration: ['p(95)<500'],
checks: ['rate>0.99'],
},
};
export default function () {
const res = http.get(`${baseUrl}/users`);
check(res, {
'ステータスが200': (r) => r.status === 200,
'所要時間が500ms未満': (r) => r.timings.duration < 500,
});
sleep(1);
}
vusとdurationは固定VUシナリオの簡略設定です。各VUはリクエストとsleepを繰り返すため、固定RPSにはなりません。終了時刻にはgraceful stopなども関わります。/usersと200を返すという契約は、アプリケーション側で用意します。
checkの失敗は記録されますが、それだけでプロセスは失敗終了しません。CIの合否にはthresholdsを使います。この例のrate<0.01は失敗リクエストが厳密に1%未満、p(95)<500は所要時間のP95が厳密に500ms未満という条件です。checksのrate>0.99は、実行した2種類のチェックを合算して99%を上回ることを求めます。各チェックが個別に99%を満たすという意味ではありません。個別に制約するなら、チェックやリクエストのタグで対象を分けます。
http_req_failedは既定で200〜399を期待どおりの応答とする規則に従い、独自のstatus === 200とは一致しません。無条件のhttp_req_duration閾値は、成功だけ、あるいは特定APIだけでなく、そのメトリクスの全リクエストサンプルを対象にします。P95はユーザーの割合でもありません。所要時間は送信・待機・受信の合計で、最初のDNS検索や接続確立などは含みません。
数値は構文の例であり、共通のSLOではありません。所有または許可された分離環境で、少ないVUからデータと実行機の余力を確認します。通常の閾値は即時停止スイッチではなく、早期終了にはabortOnFailなどを明示的に設定します。リソースや費用の制限には、対応する計測や外部制御も必要です。注文はテスト注文と決済サンドボックスで扱います。チェックと閾値(英語) · 期待する応答(英語)
VU数を時間とともに変える
stagesでは、時間に沿ってVU数を変えられます。以下は先ほどのoptionsを置き換える設定です。同じスクリプトで二重に宣言したり、固定シナリオのvus/durationをそのまま重ねたりしません。
export const options = {
stages: [
{ duration: '2m', target: 100 }, // 2分間で100 VUへ増加
{ duration: '5m', target: 100 }, // 100 VUを5分間維持
{ duration: '2m', target: 0 }, // 2分間で0 VUへ減少
],
};
targetはVU数で、リクエスト毎秒ではありません。応答時間、反復内のリクエスト数、思考時間が変われば、VU数が同じでもスループットは変わります。段階的な負荷、スパイク、長時間のsoakなどを表現できます。この置き換え例には前のthresholdsは含まれないため、同じ試験目的に必要な閾値を追加してください。Ramping VUs(英語)
失敗後の操作を止めるユーザージャーニー
複数APIをまたぐ業務にはジャーニーが役立ちます。一方、容量や回帰を調べるためにAPIを単独で測る価値もあります。次は別の独立スクリプトです。例として、ログインはJSONのuser/passを受け取り200と文字列tokenを返し、商品一覧はskuを持つ配列、テスト注文作成は201と文字列idを返す契約を想定しています。k6が提供する公開APIではなく、実際のパスとフィールドへ合わせる必要があります。
BASE_URLに加えてTEST_USER、TEST_PASS、TEST_SKUを用意し、Dockerでは明示的に渡します。例は1回のジャーニーだけを実行します。同時実行へ広げる前に、分離したアカウント、SKU、テストデータを準備します。
import http from 'k6/http';
import { check, sleep } from 'k6';
const required = ['BASE_URL', 'TEST_USER', 'TEST_PASS', 'TEST_SKU'];
if (required.some((key) => !__ENV[key])) {
throw new Error('Set BASE_URL, TEST_USER, TEST_PASS, and TEST_SKU for your test API');
}
const baseUrl = __ENV.BASE_URL.replace(/\/+$/, '');
export const options = { vus: 1, iterations: 1, thresholds: { checks: ['rate==1'] } };
function jsonOrNull(response) {
try { return response.json(); } catch (_) { return null; }
}
export default function () {
const login = http.post(`${baseUrl}/login`, JSON.stringify({
user: __ENV.TEST_USER, pass: __ENV.TEST_PASS,
}), { headers: { 'Content-Type': 'application/json' } });
const loginBody = jsonOrNull(login);
const token = typeof loginBody?.token === 'string' ? loginBody.token : '';
if (!check(login, { 'ログインが200とtokenを返す': (r) => r.status === 200 && token.length > 0 })) {
sleep(1);
return;
}
const params = { headers: {
Authorization: `Bearer ${token}`, 'Content-Type': 'application/json',
} };
const products = http.get(`${baseUrl}/products`, params);
const catalog = jsonOrNull(products);
if (!check(products, { '商品一覧にテストSKUがある': (r) => r.status === 200
&& Array.isArray(catalog) && catalog.some((item) => item?.sku === __ENV.TEST_SKU) })) {
sleep(1);
return;
}
const order = http.post(`${baseUrl}/orders`, JSON.stringify({
sku: __ENV.TEST_SKU, qty: 1,
}), params);
const created = jsonOrNull(order);
check(order, { 'テスト注文が作成された': (r) => r.status === 201
&& typeof created?.id === 'string' && created.id.length > 0 });
sleep(2);
}
jsonOrNullにより、非JSONの応答はトークン解析時の例外ではなく、チェック失敗として扱えます。認証や商品確認に失敗すれば、依存する注文を送らずに終了します。注文結果も確認します。ここでの閾値は実行済みチェックの全件成功を求めますが、業務上の正しさ、データの後片付け、必要なスループットまで定義するものではありません。
結果を母集団ごとに読む
リクエスト、反復、チェックを分けて確認します。
| メトリクス | 意味 |
|---|---|
http_req_duration |
HTTP送信・待機・受信時間の分布。最初のDNS/接続時間を含まず、P90/P95はリクエストサンプルの分位点 |
http_req_failed |
期待する応答の規則による失敗割合。業務エラーのすべてではない |
vus / iterations |
現在アクティブなVU数/累積反復数。1回で複数リクエストを送る場合も、途中で戻る場合もある |
checks |
実行済みチェックの成功割合。リクエスト数やユーザー数とは異なる |
出力と対応する保存先を設定します。現行文書の実験的なexperimental-prometheus-rwは、設定済みのPrometheus remote-write受信先へ送信します。Grafanaはその保存先をクエリして表示するもので、任意の--outを受け取る時系列ストレージではありません。アドレス、認証、TLS、バージョン対応を確認します。組み込みメトリクス(英語) · Prometheus remote write(英語)
各試験の開始・終了、アプリケーションのバージョン、試験識別子を残し、遅延の変化を同じ時間帯のログやリソースと照合します。サーバー内部の呼び出しを調べるには、対象アプリケーションに計装し、GuanceのOpenTelemetry取り込み(英語)を設定して、収集済みの下流Spanを確認します。k6の結果出力とは別の経路です。
k6のタグが自動でログやSpanのフィールドになるわけではありません。試験識別子を渡すには、合意したヘッダーとアプリケーション側の記録が必要です。トレースの関連付けにはコンテキスト伝播、サンプリング、保持期間、権限も確認します。未収集のトレースから試験全体を復元することはできません。
よくある質問
JMeter、Locustとはどう選び分けますか? 言語、対応プロトコル、チームの経験で比較します。k6は独自のJS/TS環境、LocustはPython、JMeterは非GUI実行も可能です。同じシナリオで生成能力を比べます。どのツールも、すべてのスクリプトでより多いVU数を保証するわけではありません。
必ずsleepを入れますか? セッション型なら思考時間を入れる場合があります。到着率executorは反復開始を制御するため、そのレートを調整しようと反復末尾へ追加のsleepを入れることは通常避けます。1反復で複数回HTTP通信を行えば、反復毎秒とHTTP RPSも異なります。VU数は固定RPSではなく、実行機がボトルネックになる場合もあります。
どの環境で試験しますか? 本番に近いステージングが基本です。本番を直接試験する場合は、リスク、負荷制限、停止手段を事前に決めます。ステージングのリソース、データ、依存先が異なれば、その結果を本番容量の保証には使えません。
公式資料
技術資料の確認日:2026年11月5日。例のイメージは2.3.0で、更新時は実行動作と出力対応を再確認します。
