使い方

JS モジュールをインポートし、OTLP を設定し、トポロジを読み込んでジャーニーを実行します。

import otelgen from "k6/x/otel-gen";

export function setup() {
  otelgen.configure({
    endpoint: "localhost:4317",
    protocol: "grpc",
    insecure: true,
  });
}

export default function () {
  const topology = otelgen.load("./topology.yaml");
  topology.runRandomJourney();
}

export function teardown() {
  otelgen.flush();
}

load() は setup() ではなく default() の中で呼び出してください。k6 は setup() の 戻り値を JSON シリアライズするため、ハンドルのメソッドが失われてしまいます。load() は テスト実行ごとに 1 度だけ YAML をパース・検証し、以降の呼び出しではキャッシュした ハンドルを返すため、イテレーションごとに呼んでもオーバーヘッドはありません。

otelgen.flush() は teardown() で呼び出してください。各トレースのルートスパンは すべての子スパンの後に終了するため、バッチキューに最後に入ります。最後のフラッシュが ないとプロセス終了時に破棄され、バックエンドは「root span not yet received」と報告 します。flush() はトレース・メトリクス・ログの送信を otel-gen 出力の有効・無効に 依存しない形で行います。エクスポーターを閉じずにバッチプロセッサーを強制フラッシュする ため、--out otel-gen=... の有無にかかわらず安全に呼び出せます(出力が有効な場合は、 その Stop フックが最終的なパイプラインのシャットダウンを実施します)。

時間変化 fault

handle.setFaultIntensity(x) はこの VU の注入 fault 確率、 error_rate_override の値、latency_inflation の振幅をスケールします （0 で注入 fault 無効、1 で full intensity）。default() 内で各ジャーニー 実行の前に設定し、テスト開始からの経過時間に応じてバーン→回復タイムラインを 台本化できます。

import otelgen from "k6/x/otel-gen";
import exec from "k6/execution";

export function setup() {
  otelgen.configure({
    endpoint: "localhost:4317",
    protocol: "grpc",
    insecure: true,
  });
}

export default function () {
  const topology = otelgen.load("./topology.yaml");
  const t = exec.instance.currentTestRunDuration / 1000; // テスト開始からの秒数
  const intensity = t < 60 ? 0 : t < 180 ? 1 : 0; // healthy → incident → recovered
  topology.setFaultIntensity(intensity);
  topology.runRandomJourney();
}

export function teardown() {
  otelgen.flush();
}

YAML の fault target を第 1 引数に渡すと、VU 全体ではなく 1 つの target だけを 上書きできます。

topology.setFaultIntensity("operation:payment.authorize_card", 0.5);

同じバーン→回復タイムラインは、fault の schedule として YAML に直接宣言する こともできます。schedule は engine 開始からの経過時間に対するステップ関数として 評価され、最初の点より前の強度は 0 です。setFaultIntensity(target, x) による target override は YAML schedule より優先されます。

faults:
  - target: operation:payment.authorize_card
    kind: error_rate_override
    severity: { probability: 1.0, value: 0.10 }
    schedule:
      - at: 0s
        intensity: 0
      - at: 1m
        intensity: 1
      - at: 3m
        intensity: 0

シグナルと機能

ジャーニーの実行ごとに、トレースコンテキストを共有する相関した OpenTelemetry シグナルが 生成されます。

• トレース — ジャーニーごとに 1 本、オペレーションと呼び出しごとにスパン。messaging エッジはさらに PRODUCER（publish）と CONSUMER（receive）のスパンを出し、スパンリンクで 連結します。
• メトリクス — 組み込みのリクエスト/所要時間インストルメントに加え、オペレーション単位の カスタムメトリクス（counter / gauge / histogram）。ヒストグラムにはエグゼンプラー （trace_id / span_id）が付き、メトリクス→トレースのドリルダウンができます。
• ログ — オペレーション単位のログに加え、event.name を持つ宣言的な構造化ログイベント。
• プロファイル — profilesEndpoint を設定すると 合成 pprof フレームグラフを Pyroscope へ送ります。

これらはすべてトポロジから駆動されます。各オペレーションは次を宣言できます。

完全な構文は トポロジ YAML リファレンス を参照してください。 カスタムメトリクスとプロファイルは active な fault に反応できるため、インシデント時に出力値や スタックが決定的に変化します。

完全なスクリプトは minimal と astroshop の例を参照してください。