旧バージョンのドキュメントを参照しています。 最新のドキュメントはこちらをご参照ください。

パフォーマンステストフレームワークリファレンス

注 : Kong Gateway 3.5.xの時点で、この機能は非推奨になりました。3.4.x以降ではサポートされていません。

perf.use_defaults()

構文：perf.use_defaults()

デフォルトのパラメータを使用します。この関数では次の項目が設定されます。

• PERF_TEST_DRIVER 環境変数を検索し、perf.use_driverを呼び出します。
• PERF_TEST_DRIVER が terraform なら PERF_TEST_TERRAFORM_PROVIDER を検索します。各プロバイダーに渡すことができる環境変数については perf.use_driver を参照してください。
• perf.set_log_levelを呼び出し、レベルを"debug"に設定します。
• 再試行回数を3に設定します。
• PERF_TEST_USE_DAILY_IMAGE環境変数を検索し、その変数をドライバーオプションに渡します。

perf.use_driver

構文：perf.use_driver(name,options?)

ドライバー名を使用します。ドライバー名は「local」、「docker」、または「terraform」のいずれかである必要があります。追加のドライバーのパラメータは、オプションでLuaテーブルとして指定できます。エラーがある場合はスローします。

DockerおよびTerraformドライバーでは、オプションパラメータに次のキーが含まれている必要があります。

• use_daily_image : デイリーイメージを使用するかどうかを決めるブール値。 マスターブランチの未リリースのコミットをテストするときに便利です。Enterpriseデイリーイメージをダウンロードするには、有効なDockerログインが必要です。

Terraformドライバーの通常の設定では、次の任意のキーがオプションで含まれています

• provider サービスプロバイダーの名前で、現在は “equinix-metal” のみです。
• tfvars 以下のような、LuaテーブルとしてのTerraform変数。環境変数は、perf.use_defaults()が呼び出された場合にのみ使用されます。

perf.set_log_level

構文：perf.set_log_level(level)

ログレベルを設定します。ただし次のいずれかを除きます："debug"、"info"、"notice"、"warn"、"error"、"crit"。 デフォルトのログレベルは、"info"です。ただし、perf.use_defaultsが呼び出され、"debug"に設定されている場合を除きます。

perf.set_retry_count

構文：perf.set_retry_count(count)

各「ドライバ」操作の再試行時間を設定します。デフォルトでは、すべての操作が3回再試行されます。

perf.setup

構文: helpers = perf.setup()

Kong Gatewayを除く基本環境を準備し、 spec.helpersモジュールを返します。エラーがある場合は、エラーをスローします。

このフレームワークでは、spec.helpersモジュールをインポートする前に、環境変数がいくつか設定されます。 返されるヘルパーは、通常のspec.helpersモジュールです。ユーザーは統合テストで同じパターンを使用して、Kongにエンティティを設定できます。 現在、DBレスモードは実装されていません。

perf.setup_kong

構文：helpers = perf.setup_kong(version)

基本環境を準備し、versionを使用してKong Gatewayをインストールしてから、 spec.helpersモジュールを返します。 エラーがある場合は、エラーをスローします。この関数を呼び出すと、perf.setup()も呼び出されます。

Gitハッシュまたはタグを選択するには、バージョンとして"git:<hash id="sl-md0000000">"を使用します。そうでなければ、フレームワークは versionをリリースバージョンとして扱い、バイナリパッケージをKongの配布ウェブサイトからダウンロードします。

このフレームワークでは、spec.helpersモジュールをインポートする前に、環境変数がいくつか設定されます。 返されるヘルパーは、通常のspec.helpersモジュールです。ユーザーは統合テストで同じパターンを使用して、Kongにエンティティを設定できます。 現在、DBレスモードは実装されていません。

perf.start_worker

構文：upstream_uri = perf.start_worker(nginx_conf_blob, port_count?）

指定されたnginx_conf_blobを使用してアップストリーム （Nginx/OpenResty）を開始します。Kong Gatewayのビューからアクセス可能なアップストリームURIを返します。エラーがある場合はスローします。

port_countが設定されていて1より大きい場合、フレームワークは複数のポートでアップストリームを開始し、それらをテーブルで返します。

perf.start_kong

構文：perf.start_kong(kong_configs?, driver_configs?)

Kong Gatewayをkong_configsの構成でLuaテーブルとして開始します。エラーがある場合はスローします。

driver_configsは、次のキーを含む可能性のあるLuaテーブルです。

• name：異なる Kong Gateway インスタンスを区別する文字列。1つのKong Gatewayインスタンスのみが起動される場合は必要ありません。これは、あるKong Gatewayインスタンスから別のインスタンスにアクセスするためのDNS名として使用できます。
• ports：公開ポートを設定するためのテーブル。このテーブルを尊重するのは、dockerドライバーのみです。

perf.stop_kong

構文: perf.stop_kong()

すべてのKongインスタンスを停止します。エラーがある場合はスローします。

perf.teardown

構文：perf.teardown(full?)

ティアダウンを行います。エラーがある場合はスローします。Terraformドライバーでは、fullをtrueに設定するとすべてのインフラを終了させますが、 デフォルトでは、連続した実行を高速化するためだけにクリーンアップを行います。

perf.start_stapxx

構文：perf.start_stapxx(stapxx_file_name, arg?, driver_configs?)

available stapxx scripts にあるstapxx_file_name と追加のCLI引数でStap++スクリプトを開始します。該当する場合は、エラーがスローされます。

この関数は、 SystemTapモジュールが完全に準備され、カーネルに挿入されるまでテストの実行をブロックします。 これは、perf.start_loadの前に呼び出す必要があります。

driver_configs は、次のキーを含むLuaテーブルです。

• name：プローブする個々のKong Gatewayインスタンスを区別するための文字列。

perf.start_load

構文：perf.start_load(options?)

wrkを使用してKongへの負荷の送信を開始します。エラーがある場合はスローします。Optionsは、次のものを含む可能性のあるLuaテーブルです。

• path 文字列のリクエストパス。デフォルトは/です。
• uri ベースURI例外パス。デフォルトはhttp://kong-ip:kong-port/です。
• connections 接続数。デフォルトの上限は1000です。
• threads スレッド数のリクエスト。デフォルトの上限は5です。
• duration パフォーマンステストの所要時間を秒単位で表します。デフォルトは10です。
• script wrkスクリプトの内容を文字列として指定します。デフォルトはnilです。
• wrk2 wrkの代わりにwrk2を使用するためのブール値です。デフォルトはfalseです。
• rate 送信する毎秒リクエスト数。wrk2を使用する場合は必要ですが、wrkを使用する場合は無効です。
• kong_name 負荷の送信先としてKong Gatewayを起動するときにdriver_confsによって指定されたname 。これが指定されていない場合、フレームワークはプロキシポートを公開する最初の Kong Gateway インスタンスを選択します。

perf.get_admin_uri

構文：perf.get_admin_uri(kong_name?)

Admin APIのURLを返します。URLにアクセスできるのは ロードジェネレーターのみであり、一般に公開されていません。フレームワークは 管理ポートを公開する最初の Kong Gatewayインスタンスを選択します。Kong Gatewayの起動時にdriver_confsで指定されたnameにマッチするKong Gatewayインスタンスを選択するようにkong_nameを設定する必要があります。

perf.wait_result

構文: result = perf.wait_result(options?)

ロードテストが終了するまで待機し、結果を文字列として返します。エラーがある場合はスローします。

現在、この関数は無期限、またはwrkと Stap++プロセスの両方が終了するまで待機します。

perf.combine_results

構文: combined_result = perf.combine_results(results, suite?）

perf.wait_resultによって返された複数の結果を計算し、その平均と最小値/最大値を返します。 エラーがある場合はスローします。suite文字列はチャートに表示するテストスイートを識別し、 X軸ラベルとして使用されます。スイートが指定されていない場合、フレームワークはテスト名を使用します。

同じファイルの結果が相関している場合、ユーザーは suite を数値に設定して次のオプションを追加することで、 トレンドライン付きの折れ線グラフを描くことができます。

local charts = require "spec.helpers.perf.charts"
charts.options({
  suite_sequential = true,
  xaxis_title = "Upstreams count",
})

このオプションが設定されていない場合、チャートは同じテストファイル内の結果を独立したテストとして扱い、棒グラフを描画します。

perf.generate_flamegraph

構文：perf.generate_flamegraph(path,title?)

タイトル付きのFlameGraphが生成され、パスに保存されます。該当する場合は、エラーがスローされます。

perf.save_error_log

構文：perf.save_error_log(path)

Kongのエラーログをパスに保存します。エラーがある場合はスローします。

perf.enable_charts

構文: perf.enable_charts(on?)

チャートの生成を有効にし、エラーがある場合はスローします。

デフォルトでは、チャートは有効になっています。チャートのデータはperf.combine_resultsによって供給されます。 チャートを作成するために生成されたJSONの結果は、outputディレクトリに保存されます。

perf.save_pgdump

構文：perf.save_pgdump(path)

Blueprintを使用してKongをセットアップした後、PostgreSQLデータベースのダンプをパスに保存します。エラーがある場合はスローします。

perf.load_pgdump

構文: perf.load_pgdump(path, dont_patch_service)

パスからpgdumpをロードし、Kongデータベースをロードされたデータに置き換えます。この関数は dont_patch_serviceがfalseに設定されていない限り、アップストリームへのサービスアドレスもパッチします。 これはperf.start_upstreamの後に呼び出す必要があります。エラーがある場合はスローします。

カスタマイズ

新しいテストスイートの追加

すべてのテストはKongリポジトリのspec/04-perf/01-rpsとspec/04-perf/02-flamegraphに保存されます。 いずれかのディレクトリの下に新しいファイルを追加し、テストの説明に#tagsを追加します。

Terraformで新しいプロバイダーを追加する

ユーザーは、Terraformによってサポートされている限り、ほとんどの主要サービスプロバイダーでTerraformドライバーを使用できます。 フレームワークとTerraformモジュールの間で次の契約が結ばれます。

Terraformのファイルは spec/fixtures/perf/terraform/<provider id="sl-md0000000"> に保存されています。

3つのインスタンスがプロビジョニングされており、1つはKongの実行用、もう1つはPostgreSQLデータベースの実行用、そして最後の1つはアップストリームとロード（ワーカー）を実行するためのものです。ファイアウォールは、3つのインスタンス間の双方向トラフィックおよび公共のインターネットからのトラフィックを許可します。どちらのインスタンスもUbuntu 20.04/focalを実行します。

両方のインスタンスにログインするためのSSHキーが spec/fixtures/perf/terraform/<provider id="sl-md0000000">/id_rsaに存在するか、あるいは作成されます。ログインしたユーザーにはルート権限またはsudo権限があります。

以下はTerraform出力の変数です。

• kong-ip ：KongノードのパブリックIP。
• kong-internal-ip ：Kongノードの内部IP（利用できない場合は、kong-ipを指定）。
• worker-ip ：ワーカーノードのパブリックIP。
• worker-internal-ip : ワーカーノードの内部IP（利用できない場合は、 worker-ipを指定します）。
• db-ip ：データベースノードのパブリックIP。
• db-internal-ip : データベースノードの内部IP（利用できない場合は、 db-ipを指定します）。