k6-trend-analysis

k6 の傾向分析

Grafana Cloud k6 テストの複数回の実行にわたってメトリクスの傾向を分析し、しきい値に違反してアラートが発報される前に、劣化を早期に検出します。P95 が 500ms のしきい値に対して 380ms なら今日は「正常」ですが、1 か月前は 250ms だった場合、気付かないうちに何かが劣化しています。このスキルはその変化を明らかにし、対応を提案します。

このスキルでできないこと

• 単一の実行における障害の詳細な調査：k6-cloud-investigate-test を読み込みます
• スクリプトの編集やしきい値の変更：k6-test-maintenance を読み込みます
• 新しいテストスクリプトの作成：適切なテスト作成ワークフローを使用します
• サービス側のメトリクスの直接クエリ：可観測性との相関分析が必要な場合、このスキルは debug-with-grafana に引き継ぎます

依存関係

このスキルは、GCk6 API の仕組みをすべて k6-manage に委ねます。API 呼び出しを実行する前に必ず読んでください。認証、パスの構築（二重の cloud/cloud/ プレフィックス）、@nextLink を使ったページネーション、スピルエンベロープ、メトリクスのクエリ構文について説明しています。この知識をここに重複して記載しないでください。

使用するツール：gcx（k6-manage のパターンに従います）。

---

ワークフロー

以下の手順を順番に実行します。最後に調査結果を提示してください。変更は適用しないでください。

ステップ 1：テストを特定する

ユーザーは次のいずれかを提供します。

• GCk6 URL（パスからロードテスト ID を抽出します）
• テスト ID
• テスト名（gcx k6 tests list または v6 API で検索します）

メタデータを取得して、テストが存在することを確認します。id、name、 project_id、created のタイムスタンプを記録します。複数回の実行にわたるメトリクスのエンドポイントには、実行 ID ではなくロードテスト ID が必要です。

ステップ 2：分析期間を決定する

デフォルトは過去 30 日間です。次の場合は調整します。

• ユーザーが特定の期間を指定した場合
• テストの実行回数が非常に少ない場合（30 日間で 5 回未満）――期間を延長し、その旨を記載します
• テストの実行頻度が非常に高い場合（30 日間で数百回）――サンプリングまたは期間の短縮を検討します。件数が極端に多い場合（200 回超）はユーザーに確認します

期間を明示します：「{start_date} から {end_date} までの実行を分析しています。」

ステップ 3：対象期間内の実行を取得する

v6 API を使用し、$orderby=created desc のページネーションでテストの全実行を一覧表示します（@nextLink を使ったループパターンについては k6-manage のセクション 3 を参照）。分析期間内の実行に絞り込みます。

各実行について、次の情報を記録します。

• id、created、ended
• result（passed/failed/timed_out）
• status（created/queued/initializing/running/finished/aborted）
• note（存在する場合――ユーザーが実行に注釈を付けていることがあります）

ユーザーから明示的に依頼された場合を除き、finished 状態に到達しなかった実行（aborted、timed_out など）は除外します。不完全な実行では信頼性の低いメトリクス集計が生成されます。

実行回数を数えます。利用可能な実行が 3 回未満の場合は、このサンプル数では傾向分析に意味がないことをユーザーに伝え、期間を延長するか、実行回数が増えるまで待つことを提案します。

ステップ 4：すべてのメトリクスとその型を取得する

値をクエリする前に、テストが出力するメトリクスを確認します。複数回の実行に対応したメトリクス一覧エンドポイントを使用します（k6-manage references/metrics.md セクション 2）。

GET /cloud/v5/load_tests/{loadTestId}/metrics(test_run_ids=[{id1},{id2},...])

対象期間に追加または削除された可能性のあるメトリクスを検出できるよう、代表的な実行 ID のサブセット（最初と最後の数件）を渡します。各メトリクスの name と type（counter、gauge、trend、rate）を記録します。

メトリクスを型ごとにグループ化します。クエリ方法はメトリクスの型に合わせる必要があります（metrics.md の「Query methods」を参照）。誤った方法を使用すると、結果が空になります。

ステップ 5：実行ごとの集計値を取得する

各メトリクスについて、マルチ実行集計エンドポイント（metrics.md セクション 8）を使用して、対象期間内のすべての実行にわたる集計値をクエリします。

GET /cloud/v5/load_tests/{loadTestId}/query_aggregate_k6(
  query='<method>',
  metric='<metric_name>',
  test_run_ids=[{id1},{id2},...]
)

具体的な gcx の形式（k6-manage §2 に従ったプロキシプレフィックス。-o json を指定すると spill エンベロープを回避できます）：

LT=<load_test_id>; IDS="123,124,125"
gcx --context <ctx> api "/api/plugins/k6-app/resources/cloud/cloud/v5/load_tests/$LT/query_aggregate_k6(query='histogram_quantile(0.95)',metric='http_req_duration',test_run_ids=[$IDS])" -o json

メトリクスの種類に応じて、集計方法を選択します。

メトリクスの種類	主な方法	取得できる内容
trend	histogram_quantile(0.95)	P95 レイテンシ――最も一般的な SLO の目標値です
trend	histogram_quantile(0.5)	中央値――典型的な動作を示します
trend	histogram_avg	平均値――外れ値の影響を受けやすい値です
counter	increase	実行ごとの合計数
rate	ratio	成功率／失敗率
gauge	max	実行ごとのピーク値

trend 型のメトリクス（レイテンシ）については、複数の分位点（P50、P90、P95、P99）をクエリし、劣化が一様に起きているのか、テール部分に集中しているのかを確認します。

複数のターゲットをテストする場合は、必ずリクエストのグループごとに内訳を取得してください。 テスト全体の p95 だけでは、特定のエンドポイントやページに限られたリグレッションが見えなくなります。多くの URL にアクセスするテストでは、ある URL の速度が 3 倍遅くなっても、テストレベルの p95 には表れないことがあります。デフォルトでは、グループ化したクエリを使用してください。

メトリクスのパターン	デフォルトのグループ化	理由
browser_web_vital_*（LCP、FCP、CLS、TTFB、INP、FID）	by (url)	ナビゲーションごとに個別の Web Vital が記録されるため、URL ごとの傾向を確認すれば、特定のページにおけるリグレッションを特定できます。
http_req_duration、http_req_failed、http_reqs	リクエストに name タグが付いている場合は by (name, status)。それ以外の場合は by (url, status)	エンドポイントごとにベースラインが異なるため、混在させるとエンドポイントごとの変化が見えにくくなります。
iteration_duration（複数シナリオのテスト）	by (scenario)	ブラウザーのシナリオとプロトコルのシナリオでは所要時間が大きく異なるため、混在させても意味がありません。
タグ付きのカスタム trend	by (<the tag>)	ユーザーがタグを付けた項目は、ユーザーが関心を持っている項目だと考えられます。

グループ化したクエリを作成する前に、labels エンドポイント（metrics.md §4）と label-values エンドポイント（metrics.md §5）を使用して、利用可能なラベルを確認してください。スクリプトを読んだだけでラベルを決めつけないでください。タグ名の変更やリファクタリングにより、ラベルの範囲が気付かないうちに変わることがあります。例：

# List labels for a specific metric on a representative run
GET /cloud/v5/test_runs/{id}/labels?match[]=browser_web_vital_lcp

# Then enumerate values for a useful label
GET /cloud/v5/test_runs/{id}/label/url/values

グループ化しても情報が増えないメトリクス（例：vus、load_generator_cpu_percent、すべてのリクエストが同じ URL にアクセスする単一ターゲットのテスト）に限り、グループ化しない基本の集計に切り替えてください。

応答には test_run_id がラベルとして含まれます。この値を使って、各値をステップ 3 の実行タイムスタンプに対応付けます。グループ化したクエリは、（グループ、実行）の組み合わせごとに 1 つの系列を返します。ステップ 7 で傾向を計算するため、これを「rid x group」の整然としたテーブルに整形してください。

1 つの URL に収まらないほど実行 ID が多い場合（数百件）、クエリを 50 個の実行 ID ごとのグループに分けて実行し、結果を統合します。

ステップ 6：しきい値を抽出する

しきい値は、「合格」の基準を定義します。k6-manage セクション 5 を使用してテストの現在のスクリプトを取得し、export const options = { thresholds: {...} } ブロックを解析します。各しきい値について、次の項目を記録してください。

• メトリクス名とセレクター（例：http_req_duration{name:homepage}）
• 条件（例：p(95)<500）
• abortOnFail が設定されているかどうか

また、実行データから直近の実行のしきい値結果を確認し、現在どのしきい値が合格または不合格かを把握してください。

すべてのメトリクスにしきい値が設定されているとは限りません。問題ありません。しきい値のないメトリクスも傾向分析の対象になりますが、余裕度の計算は行われません。

ステップ 7：傾向を算出する

変曲点を検出し、スクリプトの変更を確実に除外します。 リグレッションについて結論を出す前に、メトリクス値の不連続な変化、つまり、同じ日付に複数のメトリクスで同時に見られる急激な増減がないか確認します。そのような変化が見つかった場合、スクリプトが変更されたかどうかを推測してはいけません。実行に紐づくスクリプトエンドポイントを使えば、数秒で確実に判断できます。

1. 境界でバンドルされたスクリプトの sha256 を比較します。 最後の「変更前」の実行と最初の「変更後」の実行から、GET /cloud/v6/test_runs/{id}/script を使ってスナップショットを取得します（k6-manage §5、「2 つの異なるスクリプトエンドポイント」――負荷テスト用ではなく、実行単位のエンドポイントを使用してください。負荷テスト用エンドポイントには現在のバージョンしか表示されないためです）。shasum -a 256 で比較します。

   gcx --context <ctx> api /api/plugins/k6-app/resources/cloud/cloud/v6/test_runs/<before_id>/script > /tmp/before.bin
   gcx --context <ctx> api /api/plugins/k6-app/resources/cloud/cloud/v6/test_runs/<after_id>/script > /tmp/after.bin
   shasum -a 256 /tmp/before.bin /tmp/after.bin
   

   複数の実行にまたがる変曲点を徹底的に調べるには、移行期間中の各実行をハッシュ化します。連続する N 回の実行で同じハッシュが共有され、その後の N 回で別のハッシュが共有されていれば、変更前後の境界を明確に特定できます。途中でハッシュが変わる場合、テストは複数回編集されています。

2. sha256 が異なる場合、テストスクリプトが変更されています。その変曲点は、サービスのリグレッションではなく、テスト側の影響である可能性があります。境界で分析を時期ごとに分け、それぞれの時期の傾向を個別に算出します。スクリプト変更をまたいだメトリクスの比較は、誤解を招く傾向につながります。たとえば、スクリプトが遅いエンドポイントへのアクセスをやめただけなら、P95 が 3,000ms から 150ms に低下しても「改善」ではありません。レポートでは各時期を明記し、推奨事項は直近の時期に焦点を当ててください。

3. sha256 が一致する場合、スクリプトはバイト単位で同一であり、リグレッションの原因はテスト外（サービス側、インフラストラクチャ、または負荷ゾーン）にあります。これは信頼性の高い情報です。「テストが変更されたか？」という疑問を未解決のままにせず、ステップ 9（サービス側との相関）に引き継いでください。

この sha256 の差分チェックは、膨大な数の原因を除外できる、5 秒で終わる確実な確認です。検出したすべての変曲点で実行してください。ユーザーに尋ねられた場合だけ行うのではありません。

各メトリクスについて、（run_timestamp、value）のペアを時系列順に並べます。 次に、以下を算出します。

基本統計量：

• すべての実行における平均、標準偏差、最小値、最大値
• 現在値（最も新しい実行）
• ベースライン値（期間内で最も古い実行の値、または安定性を考慮して最初の 3 回の実行の平均）

傾向の方向： 実行を時間枠の前半と後半に分け、それぞれの平均を比較します。

• 悪化：後半の平均が 10％を超えて悪化している（レイテンシー／エラーでは高いほど悪く、成功率では低いほど悪い）
• 改善：後半の平均が 10％を超えて改善している
• 安定：変化が 10％以内
• 変動あり：方向に関係なく、標準偏差が平均の 25％を超えている

10％と 25％のしきい値は出発点です。ユーザーのテストの許容範囲が非常に狭い場合や、メトリクスのノイズが非常に大きい場合は、しきい値を調整し、その理由を説明してください。

変化率： 週あたりの変化率をパーセンテージで表します：((recent_mean - baseline_mean) / baseline_mean) * 100 / weeks_in_window。これにより、期間の長さが異なる場合でも正規化できます。

異常検出： メトリクス値が全体の平均から標準偏差の 2 倍を超えて離れている実行にフラグを立てます。これらは個別に調査する価値のある変曲点の候補です。

ステップ 8：余裕度を分析する

しきい値が定義されているメトリクス（ステップ 6 で設定）について、余裕度を算出します。

headroom_pct = ((threshold_value - current_value) / threshold_value) * 100

余裕度を分類します。

• 余裕あり（50％超）：制限を十分に下回っています
• 適正（20～50％）：健全ですが、監視する価値があります
• わずか（20％未満）：傾向が続けば、しきい値を超えるリスクがあります
• 超過（0％未満）：すでに失敗しています

余裕度がわずかな悪化中のメトリクスについて、現在の変化率が続いた場合にしきい値を超える時期を推定します。

weeks_until_breach = headroom_absolute / rate_of_change_per_week

これは大まかな推定であり、予測ではありません。「現在の悪化率が続くと、このメトリクスは約 N 週間後にしきい値を超える可能性があります」と提示してください。

ステップ 9：サービス側との相関分析（必要な場合）

ステップ 7 で性能低下が確認された場合は、サービス側のデータとの相関分析を提案します（自動では実行しません）。これにより、サービスの性能低下（サービスを修正）、テスト環境の変更（ロードゾーンのレイテンシ、LG の枯渇）、スクリプトの変更（編集による低速化）を切り分けます。調査結果を提示し、まずユーザーに確認してください。

debug-with-grafana（gcx 経由）に引き継ぎ、同じ時間帯のサービスの Prometheus メトリクスと Loki ログを照会します。サービスのエラー率の変化、上流のレイテンシ、リソースの逼迫（CPU／メモリ／プール）、変化点と同時期のデプロイを確認します。

サービスにオブザーバビリティがない場合（サードパーティまたは別チームのサービスで、Prometheus ジョブ、Loki ストリーム、プローブがない場合）は、回帰箇所を特定できるクライアント側のシグナルを使います。

• ブラウザーテスト： Tempo のイテレーション・トレース（k6-manage §7、/api/v1/tempo/api/search + /traces/{id}）を比較し、実行前後の変化を確認します。スパン名の集計、最も遅いスパン、URL ごとのナビゲーション所要時間から、回帰が発生した URL、ロケーター操作、またはアセットを特定できます。Web Vitals は web_vital.* スパン属性として記録されるため、直接読み取ってください。
• プロトコルテスト： http_req_duration by (name, status) と http_req_failed by (name, status) を比較します。名前付きリクエストの 1 つで回帰があれば、そのエンドポイントが原因として考えられます。http_req_waiting（サーバー処理時間）と http_req_receiving（転送時間）を分けて、処理の遅延とダウンロードの遅延を切り分けます。
• ペイロードによる裏付け（両方）：data_received／browser_data_received を照会します。レイテンシとペイロードの両方が増加している場合は、サーバーコンテンツの変更が考えられます。レイテンシが増加し、ペイロードが安定している場合は、サーバー処理の変更が考えられます。ペイロードが断続的に変化する場合は、不安定なキャッシュまたは A/B テストが考えられます。

利用可能であれば、サーバー側との相関分析を優先してください。直接「なぜ」を明らかにできます。フォールバックでは「どこで」「どのような変更があったか」を特定でき、担当チームへのチケット作成にも役立ちます。

ステップ 10：レポートを提示する

調査結果は必ず構造化されたレポートとして提示してください。変更を直接適用してはいけません。

---

レポートのテンプレート

この構成を使用します。該当しないセクションは省略してください（例：異常が検出されなかった場合は「異常」セクションを省略します）。

# Trend Analysis: {test_name}

**Test ID**: {test_id}
**Analysis window**: {start_date} to {end_date} ({N} runs analyzed)
**Overall health**: {Healthy | Watch | Degrading | Critical}

## Run Summary

| Period | Runs | Passed | Failed | Pass Rate |
|--------|------|--------|--------|-----------|
| First half | N | N | N | N% |
| Second half | N | N | N | N% |

## Metric Trends

| Metric | Type | Current | Baseline | Change | Trend | Threshold | Headroom |
|--------|------|---------|----------|--------|-------|-----------|----------|
| http_req_duration (P95) | trend | 380ms | 250ms | +52% | Degrading | 500ms | 24% |
| http_req_failed | rate | 0.8% | 0.3% | +167% | Degrading | 1% | 20% |
| http_reqs | counter | 15,230 | 15,100 | +0.9% | Stable | - | - |

## Flagged Issues

### 1. {metric_name}: {classification}
- **Current**: {value} | **Baseline**: {value} | **Change**: {pct}%
- **Threshold**: {threshold} | **Headroom**: {pct}%
- **Rate of change**: {pct}% per week
- **Projected breach**: ~{N} weeks at current rate
- **Anomalous runs**: {run_ids with dates, if any}

## Threshold Recommendations

| Metric | Current Threshold | Recommended | Rationale |
|--------|-------------------|-------------|-----------|
| http_req_duration | p(95)<500 | p(95)<420 | Current P95 is 380ms; tightening to 420ms gives 10% headroom from current performance while surfacing further degradation early |

## Suggested Next Steps

- [ ] **Investigate service side**: P95 latency has increased 52% -- consider
      loading `debug-with-grafana` to check service health
- [ ] **Deep-dive run {run_id}**: anomalous P95 spike on {date} -- consider
      loading `k6-cloud-investigate-test` for this run
- [ ] **Tighten thresholds**: 2 metrics have >30% headroom that could be
      tightened -- consider loading `k6-test-maintenance` to apply changes

全体的な健全性の分類

最悪のケースのメトリクスに基づいて全体的な健全性を判定します。

• 健全：すべてのメトリクスが安定または改善しており、余裕が十分または適切にある
• 要注意：少なくとも 1 つのメトリクスが悪化しているものの、余裕は十分にある
• 悪化中：少なくとも 1 つのメトリクスが悪化しており、余裕がわずかである
• 重大：少なくとも 1 つのメトリクスがしきい値を超過している、または複数のメトリクスが余裕の少ない状態で悪化している

---

しきい値の推奨事項

しきい値の変更を推奨する場合は、以下の原則に従ってください。

• ユーザーからの依頼がない限り、しきい値は厳しくするだけにし、緩和しないでください。 しきい値を緩和すると、問題が見えにくくなります。
• メトリクスの直近の P95 を 10～20％上回る余裕を目標にします。 通常の変動を許容しつつ、実際の性能低下を検出できるだけの余裕を確保します。
• 基準値には、直近の実行 1 回分ではなく後半の平均値を使います。 直近の実行が外れ値の可能性があるためです。
• ユーザーの意図を尊重します。 現在のしきい値に十分な余裕がある（>100％）場合、意図的に寛容な設定にしている可能性があります。厳しくする機会については伝えますが、強く勧めないでください。ユーザーは自分の状況を把握しています。
• グループ化されたしきい値を検討します。 テストでタグベースのしきい値（例：http_req_duration{name:homepage}）を使っている場合、エンドポイント間で傾向が異なるときは、エンドポイントごとのしきい値を推奨します。

---

注意事項

問題	詳細
観測値がゼロのしきい値	観測値がゼロのしきい値は、k6 ではデフォルトで合格になります。メトリクスが合格しているように見えてもデータがない場合は、その旨を指摘してください。しきい値は実際には評価されていません。
実行間でのメトリクス型の変化	実行間でメトリクスの型が変わった場合（例：スクリプトのリファクタリング）、複数実行の集計エンドポイントでは最新の型が使われます。以前の実行を誤ったメソッドでクエリすると、結果は空になります。検出した場合は指摘してください。
不完全な実行による傾向の偏り	中断またはタイムアウトした実行は、通常、実行時間が短く反復回数も少ないため、メトリクス値が実態を反映しません。デフォルトでは除外してください。
LG リソースのメトリクス	load_generator_cpu_percent と load_generator_file_handles の増加傾向は、サービスの劣化ではなく、負荷生成器への割り当てをテストが上回りつつあることを示している可能性があります。この点は別途指摘してください。
レートメトリクスの方向	ratio 型のレートメトリクス（チェック合格率など）では、「劣化」は値の低下（合格数の減少）を意味します。これはレイテンシメトリクスとは逆の方向です。