alibabacloud-pts-ops

Alibaba Cloud PTS 負荷テストシナリオの管理

このスキルを使用すると、Alibaba Cloud PTS（Performance Testing Service）で負荷テストシナリオを作成、管理できます。PTS ネイティブの HTTP/HTTPS 負荷テストと、JMeter ベースの負荷テストの両方に対応しています。

シナリオの説明

PTS（Performance Testing Service）は、アプリケーションのパフォーマンス、容量、安定性の検証に役立つ、Alibaba Cloud のフルマネージド型パフォーマンステストプラットフォームです。このスキルでは、以下に対応しています。

1. PTS ネイティブの負荷テスト - API、シリアルリンク、負荷モデルを設定して、HTTP/HTTPS 負荷テストシナリオを作成します
2. JMeter 負荷テスト - JMeter スクリプトをアップロードし、分散負荷生成で実行します

アーキテクチャ

User → Aliyun CLI → PTS Service → Target Application
                         ↓
                   Stress Testing Report

事前確認

事前確認：Aliyun CLI 3.3.1 以降が必要です aliyun version を実行して、バージョンが 3.3.1 以降であることを確認します。未インストールの場合、またはバージョンが古い場合は、 インストール手順について references/cli-installation-guide.md を参照してください。 次に、自動プラグインインストールを有効にするため、[必須] aliyun configure set --auto-plugin-install true を実行してください。

# Verify CLI version
aliyun version

# Enable auto plugin installation
aliyun configure set --auto-plugin-install true

タイムアウト設定

ハングを防ぐため、すべての CLI コマンドにタイムアウトパラメーターを指定してください。

# Recommended timeout settings for PTS operations
--read-timeout 60 --connect-timeout 10

• read-timeout：60 秒（負荷テストの操作には、より長い時間がかかる場合があります）
• connect-timeout：10 秒

環境変数

CLI 認証以外に必要な環境変数はありません。

パラメーターの確認

重要：パラメーターの確認 — コマンドまたは API 呼び出しを実行する前に、 ユーザーがカスタマイズ可能なすべてのパラメーター（例：RegionId、シナリオ名、ターゲット URL、 同時実行数、実行時間、JMX ファイルなど）をユーザーに確認する必要があります。 明示的な承認を得ずに値を推測したり、デフォルト値を使用したりしないでください。

ユーザーがカスタマイズ可能なパラメーター

パラメーター名	必須	説明	デフォルト値
RegionId	いいえ	PTS サービスのリージョン	cn-hangzhou
シナリオ名	はい	負荷テストシナリオの名前	-
ターゲット URL	はい	負荷テストの対象 URL	-
HTTP メソッド	はい	GET、POST、PUT、DELETE など	GET
同時実行数	はい	同時に実行するユーザー数	-
実行時間	はい	テストの実行時間（秒）	-
JMX ファイル	はい（JMeter）	JMeter スクリプトファイルのパス	-
モード	いいえ	CONCURRENCY または TPS	CONCURRENCY

認証

このスキルでは、Aliyun CLI のデフォルトの認証情報チェーンを使用します。使用する前に、CLI が認証済みであることを確認してください。

現在の認証状態を確認します。

aliyun configure get

CLI がまだ設定されていない場合は、セットアップ手順について references/cli-installation-guide.md を参照してください。

RAM ポリシー

ユーザーには適切な PTS 権限が必要です。詳しいポリシーについては、references/ram-policies.md を参照してください。

冪等性

PTS API は ClientToken ベースの冪等性をサポートしていません。シーン名は一意ではありません。複数の PTS シナリオや JMeter シナリオで同じ SceneName を使用できるため、「同じ名前」を同一のリソースとして扱わないでください。安定した識別子として、常に API が返す SceneId を使用してください。

タイムアウトやエラー後に再試行する際、重複したリソースや意図しない副作用を防ぐため、書き込み操作の前には必ず、次の確認してから実行するパターンを使用してください。

操作	実行前の確認	既に存在する／実行中の場合
PTS シーンの作成（save-pts-scene）	名前による重複排除はしないでください。成功後、SceneId を記録します。	直前の呼び出し結果が不明な場合、再試行する前にユーザーと一緒に list-pts-scene を使用して判別してください。保存をむやみに再試行しないでください（再試行のたびに別のシーンが作成される可能性があります）。
JMeter シーンの作成（save-open-jmeter-scene）	PTS と同様に、名前は重複する可能性があるため、SceneId のみを使用します。	再試行する前に、list-open-jmeter-scenes とユーザーとの確認を組み合わせる、同じパターンを使用してください。
PTS テストの開始（start-pts-scene）	get-pts-scene-running-status でステータスを確認します	RUNNING または SYNCING の場合はスキップし、再度開始しないでください
JMeter テストの開始（start-testing-jmeter-scene）	get-open-jmeter-scene でステータスを確認します	既に実行中の場合はスキップし、再度開始しないでください
PTS シーンの削除（delete-pts-scene）	対象の SceneId がまだ存在することを確認します（例：list-pts-scene／get-pts-scene）	その SceneId が存在しない場合は、成功（削除済み）として扱います
JMeter シーンの削除（remove-open-jmeter-scene）	対象の SceneId がまだ存在することを確認します	その SceneId が存在しない場合は、成功（削除済み）として扱います

コアワークフロー

重要：パラメーターの確認 — コマンドまたは API 呼び出しを実行する前に、ユーザーが変更できるパラメーター（例：RegionId、シーン名、ターゲット URL、同時実行数、実行時間など）をすべてユーザーに確認する必要があります。 明示的な承認を得ずに、値を推測したり、デフォルト値を使用したりしないでください。

ワークフロー 1：PTS ネイティブの負荷テストの作成と実行

タスク 1.1：PTS シナリオの作成

注： create-pts-scene ではなく save-pts-scene を使用してください。--scene パラメーターには、Scene フィールドでラップされていない JSON オブジェクトを直接指定します。

冪等性： シナリオ間で SceneName が重複する場合があります。名前だけを基準に、作成を省略したり、シーンを選択したりしないでください。save-pts-scene の成功後、後続のすべての手順で使用するため、返された SceneId を記録してください。コマンドが失敗するか、タイムアウトして結果が不明な場合は、再試行する前に list-pts-scene をユーザーと一緒に使用して、対象の SceneId を特定してください。シーンが余分に作成される可能性があるため、むやみに再試行しないでください。

aliyun pts save-pts-scene \
  --scene '{
    "SceneName": "<SCENE_NAME>",
    "RelationList": [
      {
        "RelationName": "serial-link-1",
        "ApiList": [
          {
            "ApiName": "api-1",
            "Url": "<TARGET_URL>",
            "Method": "<HTTP_METHOD>",
            "TimeoutInSecond": 10,
            "RedirectCountLimit": 10,
            "HeaderList": [
              {
                "HeaderName": "User-Agent",
                "HeaderValue": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
              }
            ],
            "CheckPointList": [
              {
                "CheckPoint": "",
                "CheckType": "STATUS_CODE",
                "Operator": "eq",
                "ExpectValue": "200"
              }
            ]
          }
        ]
      }
    ],
    "LoadConfig": {
      "TestMode": "concurrency_mode",
      "MaxRunningTime": <DURATION_MINUTES>,
      "AutoStep": false,
      "Configuration": {
        "AllConcurrencyBegin": <CONCURRENCY>,
        "AllConcurrencyLimit": <CONCURRENCY>
      }
    },
    "AdvanceSetting": {
      "LogRate": 1,
      "ConnectionTimeoutInSecond": 5
    }
  }' \
  --user-agent AlibabaCloud-Agent-Skills

パラメーターに関する注意：

• MaxRunningTime：時間の単位は分です（秒ではありません）。範囲は [1-1440] です
• TestMode：同時ユーザーテストには concurrency_mode、RPS テストには tps_mode を使用します
• TimeoutInSecond：リクエストのタイムアウト（秒）。推奨値：10
• RedirectCountLimit：リダイレクトの最大許容回数（通常は 10、無効にする場合は 0）
• HeaderList：HTTP ヘッダー。互換性を高めるため、User-Agent の指定を推奨します
• CheckPointList：レスポンス検証用のアサーション（STATUS_CODE、BODY_JSON など）
• AdvanceSetting.LogRate：ログのサンプリングレート（1～100）
• AdvanceSetting.ConnectionTimeoutInSecond：接続タイムアウト（推奨値：5）

フィールドをすべて含む完全な JSON 構造（POST リクエスト、ファイルパラメーター、グローバル変数など）については、references/pts-scene-json-reference.md を参照してください。

タスク 1.2：ストレステストを開始する

[MUST] 実行前の安全確認 — ストレステストを開始すると、対象システムに大量のトラフィックが送信されます。start-pts-scene を実行する前に、以下の確認事項をすべて満たす必要があります。

1. 冪等性ガード — get-pts-scene-running-status --scene-id <SCENE_ID> を実行します。 ステータスが RUNNING または SYNCING の場合、テストはすでに進行中です。開始コマンドをスキップし、監視に進んでください。 テストを重複して開始しないでください。
2. シナリオ設定を取得して検証する — get-pts-scene --scene-id <SCENE_ID> を実行し、 応答に有効な SceneName、空でない Url を持つ RelationList エントリが少なくとも 1 つ、 および有効な LoadConfig（MaxRunningTime と同時実行数が 0 以外）が含まれていることを確認します。 いずれかのフィールドが欠落しているか空の場合は、中止してユーザーに通知してください。
3. テストの概要を提示し、ユーザーの明示的な確認を求める — 以下をユーザーに提示し、 明示的な承認（例：「yes」／「確認」）を待ちます。
   • 対象 URL
   • 同時実行数
   • テスト期間
   • テストモード（同時実行数／TPS）
   ユーザーから明示的な「開始してよい」という確認がない限り、先に進まないでください。

# Idempotency guard: Skip if test is already running
aliyun pts get-pts-scene-running-status \
  --scene-id <SCENE_ID> \
  --user-agent AlibabaCloud-Agent-Skills
# ↑ If status is RUNNING or SYNCING, skip start-pts-scene and go to monitoring.

# Pre-flight check: Verify scene configuration is complete
aliyun pts get-pts-scene \
  --scene-id <SCENE_ID> \
  --user-agent AlibabaCloud-Agent-Skills

# Start stress testing (only after all checks pass and user confirms)
aliyun pts start-pts-scene \
  --scene-id <SCENE_ID> \
  --user-agent AlibabaCloud-Agent-Skills

タスク 1.3：テスト状況を監視する

aliyun pts get-pts-scene-running-status \
  --scene-id <SCENE_ID> \
  --user-agent AlibabaCloud-Agent-Skills

タスク 1.4：テストレポートを取得する

aliyun pts get-pts-report-details \
  --scene-id <SCENE_ID> \
  --plan-id <PLAN_ID> \
  --user-agent AlibabaCloud-Agent-Skills

ワークフロー 2：JMeter ストレステストを作成して実行する

タスク 2.1：JMeter シナリオを作成する

冪等性： JMeter シナリオ間で SceneName が重複する場合があります。名前による重複排除は行わないでください。 save-open-jmeter-scene が成功したら、返された SceneId を記録してください。失敗したかどうかが不確かな場合は、再試行する前にユーザーとともに list-open-jmeter-scenes を使用して特定してください。

aliyun pts save-open-jmeter-scene \
  --open-jmeter-scene '{
    "SceneName": "<SCENE_NAME>",
    "TestFile": "<JMX_FILENAME>",
    "Duration": <DURATION>,
    "Concurrency": <CONCURRENCY>,
    "Mode": "CONCURRENCY"
  }' \
  --user-agent AlibabaCloud-Agent-Skills

タスク 2.2：JMeter テストを開始する

[MUST] 実行前の安全確認 — JMeter ストレステストを開始すると、対象システムに大量のトラフィックが送信されます。 start-testing-jmeter-scene を実行する前に、以下の確認事項をすべて満たす必要があります。

1. 冪等性ガード — get-open-jmeter-scene --scene-id <SCENE_ID> を実行し、 シナリオのステータスを確認します。テストがすでに実行中の場合は、開始コマンドをスキップし、 監視に進んでください。テストを重複して開始しないでください。
2. シナリオ設定を検証する — 同じ応答に、有効な SceneName、空でない TestFile、 および 0 以外の Duration と Concurrency が含まれていることを確認します。 いずれかのフィールドが欠落しているか空の場合は、中止してユーザーに通知してください。
3. テストの概要を提示し、ユーザーの明示的な確認を求める — 以下をユーザーに提示し、 明示的な承認（例：「yes」／「確認」）を待ちます。
   • シナリオ名と JMX ファイル
   • 同時実行数
   • テスト期間
   ユーザーから明示的な「開始してよい」という確認がない限り、先に進まないでください。

# Idempotency guard + pre-flight check: Verify scene config and check if already running
aliyun pts get-open-jmeter-scene \
  --scene-id <SCENE_ID> \
  --user-agent AlibabaCloud-Agent-Skills
# ↑ If already running, skip start command. If config is incomplete, abort.

# Start JMeter testing (only after all checks pass and user confirms)
aliyun pts start-testing-jmeter-scene \
  --scene-id <SCENE_ID> \
  --user-agent AlibabaCloud-Agent-Skills

タスク 2.3：JMeter レポートを取得する

aliyun pts get-jmeter-report-details \
  --report-id <REPORT_ID> \
  --user-agent AlibabaCloud-Agent-Skills

ワークフロー 3：シナリオを管理する

タスク 3.1：すべての PTS シナリオを一覧表示する

aliyun pts list-pts-scene \
  --page-number 1 \
  --page-size 10 \
  --user-agent AlibabaCloud-Agent-Skills

タスク 3.2：すべての JMeter シナリオを一覧表示する

aliyun pts list-open-jmeter-scenes \
  --page-number 1 \
  --page-size 10 \
  --user-agent AlibabaCloud-Agent-Skills

タスク 3.3：シナリオの詳細を取得する

# PTS scenario
aliyun pts get-pts-scene \
  --scene-id <SCENE_ID> \
  --user-agent AlibabaCloud-Agent-Skills

# JMeter scenario
aliyun pts get-open-jmeter-scene \
  --scene-id <SCENE_ID> \
  --user-agent AlibabaCloud-Agent-Skills

タスク 3.4：シナリオをデバッグする（PTS のみ）

aliyun pts start-debug-pts-scene \
  --scene-id <SCENE_ID> \
  --user-agent AlibabaCloud-Agent-Skills

タスク 3.5：実行中のテストを停止する

# Stop PTS test
aliyun pts stop-pts-scene \
  --scene-id <SCENE_ID> \
  --user-agent AlibabaCloud-Agent-Skills

# Stop JMeter test
aliyun pts stop-testing-jmeter-scene \
  --scene-id <SCENE_ID> \
  --user-agent AlibabaCloud-Agent-Skills

成功確認方法

重要： start-pts-scene は、ストレステストの起動に実際は失敗していても（対象サイトの保護機能や設定不足などにより）、Success: true を返す場合があります。実際の実行状況を必ず確認してください。

各操作の後、references/verification-method.md に記載されている確認コマンドを使用して、成功を検証してください。

シナリオ作成を確認する：

# Use list-pts-scene instead of get-pts-scene (more reliable)
aliyun pts list-pts-scene \
  --page-number 1 \
  --page-size 10 \
  --user-agent AlibabaCloud-Agent-Skills

ストレステストが実際に実行中であることを確認する：

# Check running status first
aliyun pts get-pts-scene-running-status \
  --scene-id <SCENE_ID> \
  --user-agent AlibabaCloud-Agent-Skills

# Then verify with running data (requires plan-id from start-pts-scene)
aliyun pts get-pts-scene-running-data \
  --scene-id <SCENE_ID> \
  --plan-id <PLAN_ID> \
  --user-agent AlibabaCloud-Agent-Skills

実行が成功したことを示す主な指標：

• Status：RUNNING または SYNCING であること（直ちに STOPPED になっていないこと）
• AliveAgents：0 より大きいこと
• Concurrency：設定した値と一致すること
• TotalRequestCount：増加し続けていること

クリーンアップ

不要になったシナリオを削除します。

[MUST] 削除前の安全確認 — シナリオを削除する前に、以下のすべての確認に合格する必要があります。

1. 冪等性ガード — 対象の**SceneId**（名前ではありません）を使用して、シナリオがまだ存在することを確認します（例：list-pts-scene / list-open-jmeter-scenes または get-*）。SceneId が存在しない場合は、削除済みとして扱い、削除コマンドを実行しないでください。
2. シナリオが現在実行中かどうかの確認 — get-pts-scene-running-status --scene-id <SCENE_ID>（PTS）を実行するか、JMeter シナリオのステータスを確認します。シナリオのステータスが RUNNING または SYNCING の場合は、まず stop-pts-scene / stop-testing-jmeter-scene を使用して停止し、完全に停止するまで待ってから削除する必要があります。実行中のシナリオを削除しないでください。
3. ユーザーの明示的な確認が必要 — シーン名と ID をユーザーに表示し、削除することを明示的に確認してください（例：「yes」/「确认删除」）。ユーザーの明示的な承認なしに続行しないでください。

# Pre-delete check: Verify scenario is not running
aliyun pts get-pts-scene-running-status \
  --scene-id <SCENE_ID> \
  --user-agent AlibabaCloud-Agent-Skills

# Delete PTS scenario (only after confirming it is not running and user approves)
aliyun pts delete-pts-scene \
  --scene-id <SCENE_ID> \
  --user-agent AlibabaCloud-Agent-Skills

# Delete JMeter scenario (only after confirming it is not running and user approves)
aliyun pts remove-open-jmeter-scene \
  --scene-id <SCENE_ID> \
  --user-agent AlibabaCloud-Agent-Skills

API とコマンドの表

API と CLI コマンドの完全なリファレンスについては、references/related-apis.md を参照してください。

ベストプラクティス

1. シーン設定を完全に指定する - 信頼性の高いテスト実行のため、常に TimeoutInSecond、HeaderList（User-Agent を含む）、CheckPointList、AdvanceSetting を指定します
2. パラメーターを必ず確認する - 実行前に、対象 URL、同時実行数、期間をユーザーに確認します
3. 低い同時実行数から開始する - 低い同時実行数から始め、徐々に増やしてパフォーマンスのしきい値を特定します
4. 実際の実行を確認する - start-pts-scene の Success: true を鵜呑みにしないでください。必ず --plan-id を指定して get-pts-scene-running-data を確認します
5. まずデバッグモードを使用する - PTS シナリオでは、全体テストの前に start-debug-pts-scene を使用して設定を検証します
6. テスト中に監視する - 負荷テスト中は実行ステータスを定期的に確認します
7. レポートを十分に確認する - レポートで応答時間、エラー率、スループットを分析します
8. テスト後にクリーンアップする - 不要なコストを避けるため、テストシナリオを削除します
9. 適切なテスト期間を設定する - テストを長くすると結果の精度が向上しますが、より多くのリソースを消費します
10. ウォームアップ期間を設ける - ピークパフォーマンスを測定する前に、システムをウォームアップする時間を確保します

参考リンク

参考資料	説明
cli-installation-guide.md	Aliyun CLI のインストールと設定
related-apis.md	API と CLI コマンドの完全なリファレンス
ram-policies.md	RAM 権限ポリシー
verification-method.md	各操作の検証手順
pts-scene-json-reference.md	PTS シーン JSON 構造の完全なリファレンス
acceptance-criteria.md	スキル検証の受け入れ基準