k6-cloud-investigate-test

k6 Cloud テスト調査

Grafana Cloud k6 のテストまたは実行を調査するための、構造化された9ステップのワークフローです。

このスキルはワークフロー専用です。すべての API 呼び出しは、プラグインプロキシに対して gcx api を使用し、REST には v6、メトリクスには v5 を使用します。仕組みの詳細（gcx の認証、パスの規則、エンドポイントの検出、ログクエリ、スクリプト編集、しきい値の意味、注意点）については、k6-manage スキルを参照してください。以下の各ステップでは、同スキルを参照しています。

このスキル固有の内容は次のとおりです。

• 調査の手順（以下のステップ1～9）
• 日付の整合性チェック（「過去7日間」≠「直近7回の実行」）
• 3層の合否判定（result と status と、クエリで確認する個別の checks）
• 実際的な数値を使った例（references/worked-example.md）

基本原則

1. 書き込み前に読み取ります。 PUT の前には必ずスクリプトを GET してください。gcx k6 load-tests update-script は、指定したファイルの内容で実行中のスクリプトを置き換える書き込み操作です。「アクセスする URL を確認するためだけ」に実行した結果、本番環境のスクリプトを失ったユーザーもいます。URL を確認する必要がある場合は、代わりに -vvv --log-http-payload を付けて、変更を加えないコマンドを実行してください。
2. 実行を列挙する場合はページネーションを使います。 /test_runs エンドポイントは最大1000行に制限されており、gcx k6 runs list --limit 0 は @nextLink を自動的にたどりません。k6-manage §3 に記載されている gcx api のループを使ってください。
3. 日付の範囲を確認します。 ユーザーが「過去7日間」「今週」「最近の実行」と言った場合は、最も新しい実行の created が実際にその期間内にあるか確認してください。期間から外れている場合は、その隔たりを明示してください。
4. check() は実行を失敗させません。失敗させるのは thresholds だけです。 また、観測値が0のしきい値は ✓ 合格と報告されます。詳しくは、以下の「しきい値の意味」を参照してください。ステップ5の個別の checks メトリクスクエリで、どちらのケースも検出できます。

前提条件

ユーザーのスタックに対して gcx がインストールされ、認証されていること。k6-manage §1 を参照してください。次のコマンドで確認します。

gcx --context <stack> config check    # expect "✔ Connectivity: online"

調査ワークフロー

ステップ1：テストと対象の実行を特定する

ユーザーの URL から判断します。

• /a/k6-app/tests/<id> → ロードテスト（複数の実行の親）
• /a/k6-app/runs/<id> → 特定の実行

実行からテストを特定するには、gcx api で実行を取得してください。パスの形式に関する規則は k6-manage §2 を参照してください。

gcx --context <stack> api /api/plugins/k6-app/resources/cloud/cloud/v6/test_runs/<run_id>

レスポンスから .test_id を読み取ります。テストの実行一覧を取得する方法については、ステップ3を参照してください。

ステップ2：テストのメタデータとスクリプトを取得する

gcx --context <stack> k6 load-tests get <test_id> -o json

スクリプトについては、k6-manage §5 の安全な編集手順のうち GET の部分に従ってください。後で編集する予定がある場合は、バックアップを保存してください。

スクリプトのエンドポイントは2つあり、調査ではその違いが重要です。 k6-manage §5 では、現在のロードテストスクリプトと、実際に実行された各実行時点のスナップショットの両方について説明しています。実行後にスクリプトが編集されるたびに、両者の内容に差が生じます。「何が変わったか」「この実行が失敗した理由は何か」を調べる場合や、数日以上前の実行を調査する場合は、k6-manage §5 の実行スクリプト用エンドポイントを使って、実行に含まれるスナップショットも取得し、現在のロードテストスクリプト（または別の実行のスナップショット）と差分を比較してください。過去の実行を分析するうえで、現在のロードテストスクリプトは適切な成果物ではありません。

ステップ3：ページネーションを使って実行を一覧表示する

k6-manage §3 に記載されている gcx api と @nextLink のループパターンを、/cloud/v6/load_tests/<test_id>/test_runs に対して使ってください。all_runs を収集した後：

print(f"Total: {len(all_runs)}")
runs_sorted = sorted(all_runs, key=lambda r: r['created'], reverse=True)
for r in runs_sorted[:10]:
    print(f"  {r['created']:30s} id={r['id']:>8} status={r['status']:<10} result={r.get('result','?')}")

ユーザーに実行の総数、日付の範囲、最新の実行日を報告します。「最新の実行」が1日以上前の場合は、そのことを明示してください。スケジュールが実行されていると思い込んでいる可能性があります。

ステップ4：ユーザーの意図と日付が一致しているか確認する

ユーザーが「過去7日間」「今週」「最近」と尋ねた場合は、行数ではなく日付の範囲で絞り込みます。「直近の7回の実行」が対象とする期間は、テストの実行頻度によって1日にも1年にもなり得ます。

last7 = [r for r in all_runs if r['created'] >= '<today_minus_7_days_iso>']

len(last7) == 0 の場合は、すぐにユーザーに伝えてください。古いデータを使って先に進んではいけません。

ステップ 5：合格／不合格のステータスを判定する

各実行について、独立した次の 3 つのレイヤーを確認します。

レイヤー	フィールド	意味
実行レベルの結果	result（passed／failed／error／aborted）	しきい値に違反したかどうか
実行レベルのステータス	status（completed／aborted）	実行が正常に終了したかどうか
スクリプト内のチェック	v5 の checks メトリクス。check ラベルで集計	各チェックの成功率

ユーザーが「失敗している」と考えているのに result: passed と報告される場合は、3 つ目のレイヤーを確認します。よくあるパターンは、すべてのイテレーションで check() が false を返すものの、checks にしきい値が設定されていないため、実行は「合格」するというものです。詳しくは、以下の「しきい値のセマンティクス」を参照してください（ゼロ観測の落とし穴、abortOnFail のクラウド遅延、演算子のサポート）。

チェックごとの内訳を v5 経由で取得します（query_aggregate_k6 の形式については、k6-manage/references/metrics.md の §7 を参照してください）。

gcx --context <stack> api \
  "/api/plugins/k6-app/resources/cloud/cloud/v5/test_runs/<run_id>/query_aggregate_k6(query='ratio by (check)',metric='checks')"

レスポンスの各結果エントリには、チェック名が入った check ラベルと、成功率（0.0～1.0）を示す単一の値が含まれます。成功／失敗の生の件数を取得するには、increase_nz by (check)（成功数）と increase_z by (check)（失敗数）もクエリします。

ステップ 6：実行のメトリクスを取得する

k6-manage/references/metrics.md に記載されている v5 メトリクスエンドポイントを使用します。一般的なワークフローは次のとおりです。

# 6a. List metrics available for the run (metrics.md §1)
gcx --context <stack> api /api/plugins/k6-app/resources/cloud/cloud/v5/test_runs/<run_id>/metrics

# 6b. List labels for a metric to know what's available to filter/group by (metrics.md §4)
gcx --context <stack> api \
  "/api/plugins/k6-app/resources/cloud/cloud/v5/test_runs/<run_id>/labels?match[]=http_req_duration"

# 6c. Time-series — pick a query method that matches the metric's type (metrics.md §6)
gcx --context <stack> api \
  "/api/plugins/k6-app/resources/cloud/cloud/v5/test_runs/<run_id>/query_range_k6(query='histogram_quantile(0.95) by (name,status)',metric='http_req_duration',step=10)"

# 6d. Scalar aggregate over the whole run (metrics.md §7)
gcx --context <stack> api \
  "/api/plugins/k6-app/resources/cloud/cloud/v5/test_runs/<run_id>/query_aggregate_k6(query='increase',metric='http_reqs')"

メトリクスの種類ごとに適切なクエリ方法を選ぶことが重要です。k6-manage/references/metrics.md の「クエリ方法」の表を参照してください。ブラウザテストでは、URL／ステータスの内訳は labels と label/{name}/values（metrics.md の §4／§5）から取得します。別のタグエンドポイントから取得するわけではありません。

ステップ 7：実行のログを取得する

k6-manage §4 の Loki の手順に従います（/api/plugins/k6-app/resources/logs/... への gcx api、{test_run_id="<id>"} セレクター、必須の X-K6TestRun-Id ヘッダー、run.created／run.ended に合わせた start／end の指定）。レスポンスを /tmp/run_<id>_logs.json に保存し、記載された手順に従ってファイルから要約します。

ステップ 8：（依頼された場合）スクリプトを安全に編集する

k6-manage §5 の安全な編集手順を一通り使用します（GET → バックアップ → 編集 → k6 inspect → 1 イテレーションのスモークテスト → Content-Type: application/octet-stream を指定して PUT → sha256 検証）。

編集にしきい値が関係する場合は、「しきい値のセマンティクス」も参照し、ゼロ観測の落とし穴、abortOnFail のクラウド遅延、演算子のサポート（ドキュメントには記載されていませんが、==／!= は機能します）について確認します。

ステップ 9：報告する

質問の内容に合わせてテンプレートを選びます。

単一実行の調査（「実行 X で何が起きていますか」）の場合：

Test: <name> (id <test_id>)
Run:  <run_id> @ <created> → <ended>, load_zone=<zone>, result=<result>

Logs (<n> streams, <m> lines):
  - <stream summary>

Metrics (key indicators):
  - <metric>: <method> = <value> (n=<count>)
  ...

Per-check breakdown:
  - <check name>: <success_rate> (succ=<n>, fail=<n>)
  ...

Diagnosis: <one-paragraph>

複数実行の比較（「合格した実行と失敗した実行で何が違いますか」「この変更が失敗の原因ですか」）の場合：

Question: <one-line restatement of what the user is trying to attribute>

Run timeline (relevant window):

| Run ID | Created (UTC) | Result | exec_duration | processing_duration | k6 build | error code | key check ratios |
|---|---|---|---|---|---|---|---|
| ... | ... | passed | 60s | 195s | <build> | — | 1.0/1.0/1.0 |
| ... | ... | failed | 27s | 193s | <build> | — | 0.0/n=0/n=0 |
| ... | ... | error  | 51s | 3601s aborted | <build> | 8016 | 1.0/1.0/1.0 |

Differences that matter:
  - <field>: <value-in-passing> vs <value-in-failing> — <interpretation>
  ...

Script diff (if relevant): <bundled-script diff between a representative passing and failing run, summarised>

Diagnosis: <one-paragraph attributing the change to test-side, SUT-side, or platform-side, with the supporting evidence>

この表を使うと、並べて比較した際の異常がすぐに分かります（合格した実行と失敗した実行で同じ列があれば、その項目が原因である可能性は低く、値が切り替わる列があれば原因候補になります）。

ユーザーが生データのダンプを求めている場合は、/tmp/k6inv/run<id>/ にも保存し、ファイルパスを伝えます。

しきい値のセマンティクス

実行の result を決めるのは check() の呼び出しではなく、しきい値です。初めて調査する人が誤解しやすい、いくつかの分かりにくい点があるため、ここにまとめています。ステップ 5（「合格／不合格のステータスを判定する」）とステップ 8（「スクリプトを安全に編集する」）は、どちらもこのセクションの内容に依存します。

result の意味

result の値	意味
passed	すべてのしきい値を通過した（または、しきい値が定義されていない）
failed	1 つ以上のしきい値を満たさなかった
error	スクリプトが完了前にクラッシュした（例：ブラウザーを起動できなかった）、または k6 Cloud がプラットフォーム側で実行を中止した。どちらかを判別するには、実行の status_history[*].extra.code を確認してください。null 以外のコードがあれば、プラットフォーム側で中止されています（例：8016 = processing_metrics 中の「テスト実行の最大実行時間を超過」）。プラットフォーム側の中止は error として表示されますが、コードに起因するものではありません。
aborted	ユーザーまたはシステムが実行を中止した

check() の呼び出しは、result に直接影響しません。組み込みの checks レートメトリクスに観測値を出力し、その後、しきい値で評価できます。checks を参照するしきい値がない場合、失敗したチェックは実行レベルの result に反映されません。

「観測値ゼロ = 合格」の落とし穴

k6 は、基盤となるメトリクスのサンプルがゼロの場合、しきい値の式が通常なら false と評価される場合でも、しきい値を ✓ 合格として報告します。

checks{check:response is 200}
✓ 'rate==1.0' rate=0.00%       ← ✓ pass!?

スクリプトが該当する check() の呼び出しに到達する前に例外をスローすると、この問題が発生します。catch ブロックでチェックの観測値を強制的に出力し、しきい値に何らかの値が渡されるようにしてください。

try {
  const r = await page.goto(URL);
  check(r, { "response is 200": x => x.status() === 200 });
  // ... rest of iteration body
  check(true, { "script completed without exception": () => true });
} catch (e) {
  console.error(e);
  check(null, { "script completed without exception": () => false });
} finally {
  await page.close();
}

次に、しきい値に 'checks{check:script completed without exception}': ['rate==1.0'] を追加します。これにより、ナビゲーションの失敗と、その後の段階で発生する例外の両方を検出できます。

abortOnFail のクラウドでの遅延

k6 がクラウドで実行される場合、しきい値は 60 秒ごとに評価されます。abortOnFail 機能は最大 60 秒遅延する可能性があります。

60 秒未満の実行では、イテレーションが自然に完了する前に abortOnFail が作動しない場合があります。実行終了時にはしきい値が評価され、result は failed に変わりますが、中止によって実行時間が短縮されることはありません。

演算子

ドキュメントでは <、>、<=、>= が示されています。ドキュメントには記載されていませんが、== と != も使用できます。rate メトリクス（値は 0.00～1.00）の場合、rate==1.0 は「すべての観測値がゼロ以外」、rate==0 は「すべての観測値がゼロ」を意味します。

ワークフロー固有の注意点

正規の注意点リスト（認証の有効期限切れ、cloud/cloud/ の二重化、スクリプト PUT での 415、Loki での X-K6TestRun-Id 欠落、スクリプト PUT で updated が更新されない、gcx k6 runs list --limit 0 で @nextLink をたどらない）については、k6-manage §7 を参照してください。以下の項目は、この調査ワークフローに固有のものです。

症状	原因	修正方法
「最新の実行は 6 か月前」と表示されるが、スケジュールは毎日になっている	/test_runs のページネーションを行っていない	k6-manage §3（ステップ 3）の @nextLink ループを使用します
「過去 7 日間」のレポートに古い実行しか含まれていない	日付ではなく行数でフィルタリングしている	created >= <iso_date> で再度フィルタリングします（ステップ 4）
しきい値のレポートでは ✓ 合格となるが、チェックは失敗する	チェックの観測結果がゼロ。check() が実行される前にイテレーションが中断された	上記の「しきい値のセマンティクス」を参照してください
result: error だが、スクリプトのログやメトリクスに問題がないように見える	プラットフォームによる中断の可能性があります（例：processing_metrics が 1h の上限を超過し、code 8016 が発生）。実行自体は正常に完了しています。	実行の status_history[*].extra.code を確認します。プラットフォームコードが null 以外の場合、コードに問題があるわけではありません。「しきい値のセマンティクス」を参照してください
過去の実行を調査する際に、現在の負荷テストスクリプトを読んでいる	実行後にスクリプトが編集されている可能性があり、読んでいる内容と実行された内容が異なる	結論を出す前に、実行ごとのエンドポイント（k6-manage §5）から実行時のバンドルされたスクリプトを GET し、現在の負荷テストスクリプトと diff を取ります
ユーザーのスクリプトを上書きしてしまった	「URL を確認する」ために update-script を実行した	ステップ 2 で取得したバックアップから復元します。書き込みを行わずに URL を確認するには、変更を伴わないコマンドで -vvv --log-http-payload を使用します。
CLI の --iterations 1 でブラウザーシナリオが壊れる	シナリオブロック全体が上書きされる	sed でファイル内の iterations: を編集します

参考資料

• references/worked-example.md — 現実的な調査結果を含む架空の調査例です。ステップ 9 のレポートのテンプレートとして役立ちます。