Performance Insights での AWS CLI の例
以下のセクションでは、Performance Insights の AWS Command Line Interface (AWS CLI) の詳細と AWS CLI の使用例について説明します。
トピック
- Performance Insights の AWS CLI の組み込みヘルプ
- カウンターメトリクスの取得
- 上位の待機イベントに関する DB 平均負荷の取得
- 上位の SQL に関する DB 平均負荷の取得
- SQL によってフィルタリングされた平均 DB ロードの取得
- SQL ステートメントの全文の取得
- 一定期間のパフォーマンス分析レポートの作成
- パフォーマンス分析レポートの取得
- DB インスタンスのすべてのパフォーマンス分析レポートを一覧表示する
- パフォーマンス分析レポートの削除
- パフォーマンス分析レポートにタグを追加する
- パフォーマンス分析レポートのすべてのタグを一覧表示する
- パフォーマンス分析レポートからタグを削除する
Performance Insights の AWS CLI の組み込みヘルプ
Performance Insights は、AWS CLI を使用して表示することができます。Performance Insights の AWS CLI コマンドのヘルプを表示するには、コマンドラインで次のように入力します。
aws pi help
AWS CLI がインストールされていない場合は、「AWS CLI ユーザーガイド」の「AWS CLI のインストール」でインストールの方法を確認してください。
カウンターメトリクスの取得
以下のスクリーンショットは、AWS Management Console における 2 つのカウンターメトリクスグラフを示します。
以下の例では、2 つのカウンターメトリクスグラフを生成するために AWS Management Console で使用するデータと同じデータを生成する方法を示します。
Linux、macOS、Unix の場合:
aws pi get-resource-metrics \ --service-type RDS \ --identifier db-ID\ --start-time2018-10-30T00:00:00Z\ --end-time2018-10-30T01:00:00Z\ --period-in-seconds60\ --metric-queries '[{"Metric": "os.cpuUtilization.user.avg" }, {"Metric": "os.cpuUtilization.idle.avg"}]'
Windows の場合:
aws pi get-resource-metrics ^ --service-type RDS ^ --identifier db-ID^ --start-time2018-10-30T00:00:00Z^ --end-time2018-10-30T01:00:00Z^ --period-in-seconds60^ --metric-queries '[{"Metric": "os.cpuUtilization.user.avg" }, {"Metric": "os.cpuUtilization.idle.avg"}]'
また、コマンドを作成しやすくするために、--metrics-query オプションにファイルを指定します。以下の例では、このオプション用に query.json と呼ばれるファイルを使用します。ファイルの内容は次のとおりです。
[ { "Metric": "os.cpuUtilization.user.avg" }, { "Metric": "os.cpuUtilization.idle.avg" } ]
ファイルを使用するには、次のコマンドを実行します。
Linux、macOS、Unix の場合:
aws pi get-resource-metrics \ --service-type RDS \ --identifier db-ID\ --start-time2018-10-30T00:00:00Z\ --end-time2018-10-30T01:00:00Z\ --period-in-seconds60\ --metric-queries file://query.json
Windows の場合:
aws pi get-resource-metrics ^ --service-type RDS ^ --identifier db-ID^ --start-time2018-10-30T00:00:00Z^ --end-time2018-10-30T01:00:00Z^ --period-in-seconds60^ --metric-queries file://query.json
前述の例では、各オプションに次の値を指定します。
-
--service-type-RDSfor Amazon RDS -
--identifier- DB インスタンスのリソース ID -
--start-timeおよび--end-time- クエリを実行する期間の ISO 8601DateTime値 (サポートされている複数の形式)
クエリは 1 時間の範囲で実行されます。
-
--period-in-seconds-60(1 分ごとのクエリ) -
--metric-queries- 2 つのクエリの配列。それぞれ 1 つのメトリクスに対して使用されます。メトリクス名ではドットを使用してメトリクスを有用なカテゴリに分類します。最終の要素は関数になります。この例では、関数は、クエリの
avgです。Amazon CloudWatch と同様に、サポートされている関数は、min、max、total、およびavgです。
レスポンスは次の例のようになります。
{ "Identifier": "db-XXX", "AlignedStartTime": 1540857600.0, "AlignedEndTime": 1540861200.0, "MetricList": [ { //A list of key/datapoints "Key": { "Metric": "os.cpuUtilization.user.avg" //Metric1 }, "DataPoints": [ //Each list of datapoints has the same timestamps and same number of items { "Timestamp": 1540857660.0, //Minute1 "Value": 4.0 }, { "Timestamp": 1540857720.0, //Minute2 "Value": 4.0 }, { "Timestamp": 1540857780.0, //Minute 3 "Value": 10.0 } //... 60 datapoints for the os.cpuUtilization.user.avg metric ] }, { "Key": { "Metric": "os.cpuUtilization.idle.avg" //Metric2 }, "DataPoints": [ { "Timestamp": 1540857660.0, //Minute1 "Value": 12.0 }, { "Timestamp": 1540857720.0, //Minute2 "Value": 13.5 }, //... 60 datapoints for the os.cpuUtilization.idle.avg metric ] } ] //end of MetricList } //end of response
レスポンスには、Identifier、AlignedStartTime、AlignedEndTime があります。--period-in-seconds 値が 60 の場合、スタート時間および終了時間は、時間 (分) に調整されます。--period-in-seconds が 3600 の場合、スタート時間および終了時間は、時間 (時) に調整されます。
レスポンスの MetricList には、多数のエントリを含み、それぞれに Key および DataPoints エントリがあります。DataPoint にはそれぞれ、Timestamp および Value を含みます。クエリは 1 分ごとのデータが 1 時間以上実行されるため、Datapoints の各リストには、60 個のデータポイントがあります。これには、Timestamp1/Minute1 や Timestamp2/Minute2 から、Timestamp60/Minute60 まで含まれます。
クエリは 2 つの異なるカウンターメトリクスを対象としているため、レスポンス MetricList には 2 つの要素があります。
上位の待機イベントに関する DB 平均負荷の取得
以下の例は、スタックされたエリアチャートを生成するために AWS Management Console で使用されるのと同じクエリです。この例では、上位 7 つの待機イベントに応じて負荷を分割し、最後の 1 時間で db.load.avg を取得します。コマンドは カウンターメトリクスの取得 と同じコマンドです。ただし、query.json ファイルには、次の内容が含まれます。
[ { "Metric": "db.load.avg", "GroupBy": { "Group": "db.wait_event", "Limit": 7 } } ]
以下のコマンドを実行します。
Linux、macOS、Unix の場合:
aws pi get-resource-metrics \ --service-type RDS \ --identifier db-ID\ --start-time2018-10-30T00:00:00Z\ --end-time2018-10-30T01:00:00Z\ --period-in-seconds60\ --metric-queries file://query.json
Windows の場合:
aws pi get-resource-metrics ^ --service-type RDS ^ --identifier db-ID^ --start-time2018-10-30T00:00:00Z^ --end-time2018-10-30T01:00:00Z^ --period-in-seconds60^ --metric-queries file://query.json
この例では、上位 7 つの待機イベントのうち db.load.avg と GroupBy のメトリクスを指定しています。この例の有効な値の詳細については、Performance Insights の API リファレンスの「DimensionGroup」を参照してください。
レスポンスは次の例のようになります。
{ "Identifier": "db-XXX", "AlignedStartTime": 1540857600.0, "AlignedEndTime": 1540861200.0, "MetricList": [ { //A list of key/datapoints "Key": { //A Metric with no dimensions. This is the total db.load.avg "Metric": "db.load.avg" }, "DataPoints": [ //Each list of datapoints has the same timestamps and same number of items { "Timestamp": 1540857660.0, //Minute1 "Value": 0.5166666666666667 }, { "Timestamp": 1540857720.0, //Minute2 "Value": 0.38333333333333336 }, { "Timestamp": 1540857780.0, //Minute 3 "Value": 0.26666666666666666 } //... 60 datapoints for the total db.load.avg key ] }, { "Key": { //Another key. This is db.load.avg broken down by CPU "Metric": "db.load.avg", "Dimensions": { "db.wait_event.name": "CPU", "db.wait_event.type": "CPU" } }, "DataPoints": [ { "Timestamp": 1540857660.0, //Minute1 "Value": 0.35 }, { "Timestamp": 1540857720.0, //Minute2 "Value": 0.15 }, //... 60 datapoints for the CPU key ] }, //... In total we have 8 key/datapoints entries, 1) total, 2-8) Top Wait Events ] //end of MetricList } //end of response
このレスポンスでは、MetricList の 8 つのエントリがあります。合計の db.load.avg のエントリが 1 つあり、上位 7 つの待機イベントのいずれかに従って分割された db.load.avg のエントリが 7 つあります。初期の例とは異なり、グループ化ディメンションがあったため、メトリクスのグループ化ごとに 1 つのキーが必要です。基本的なカウンターメトリクスのユースケースのように、メトリクスごとに 1 つのキーのみ使用することはできません。
上位の SQL に関する DB 平均負荷の取得
以下の例では、上位 10 個の SQL ステートメント別に db.wait_events をグループ化します。SQL ステートメントには 2 つの異なるグループがあります。
-
db.sql- SQL のフルステートメント (例:select * from customers where customer_id = 123) -
db.sql_tokenized- トークン分割された SQL ステートメントselect * from customers where customer_id = ?()
データベースのパフォーマンスを分析するときは、パラメータが異なるだけの SQL ステートメントを 1 つの論理的な項目として検討すると便利です。そのため、クエリを実行する際、db.sql_tokenized を使用することができます。ただし、特に Explain Plan を確認したい場合は、パラメータ付きの完全な SQL ステートメントと、db.sql によるクエリのグループ化を調べる方が便利な場合があります。トークン分割化された SQL と完全 SQL の間には親子関係があり、複数の完全 SQL (子) が同じトークン分割化された SQL (親) の下にグループ化されています。
この例のコマンドは、上位の待機イベントに関する DB 平均負荷の取得 のコマンドに似ています。ただし、query.json ファイルには、次の内容が含まれます。
[ { "Metric": "db.load.avg", "GroupBy": { "Group": "db.sql_tokenized", "Limit": 10 } } ]
次の例では db.sql_tokenized を使用しています。
Linux、macOS、Unix の場合:
aws pi get-resource-metrics \ --service-type RDS \ --identifier db-ID\ --start-time2018-10-29T00:00:00Z\ --end-time2018-10-30T00:00:00Z\ --period-in-seconds3600\ --metric-queries file://query.json
Windows の場合:
aws pi get-resource-metrics ^ --service-type RDS ^ --identifier db-ID^ --start-time2018-10-29T00:00:00Z^ --end-time2018-10-30T00:00:00Z^ --period-in-seconds3600^ --metric-queries file://query.json
この例では、1 時間の間隔 (秒) で 24 時間以上のクエリを実行します。
この例では、上位 7 つの待機イベントのうち db.load.avg と GroupBy のメトリクスを指定しています。この例の有効な値の詳細については、Performance Insights の API リファレンスの「DimensionGroup」を参照してください。
レスポンスは次の例のようになります。
{ "AlignedStartTime": 1540771200.0, "AlignedEndTime": 1540857600.0, "Identifier": "db-XXX", "MetricList": [ //11 entries in the MetricList { "Key": { //First key is total "Metric": "db.load.avg" } "DataPoints": [ //Each DataPoints list has 24 per-hour Timestamps and a value { "Value": 1.6964980544747081, "Timestamp": 1540774800.0 }, //... 24 datapoints ] }, { "Key": { //Next key is the top tokenized SQL "Dimensions": { "db.sql_tokenized.statement": "INSERT INTO authors (id,name,email) VALUES\n( nextval(?) ,?,?)", "db.sql_tokenized.db_id": "pi-2372568224", "db.sql_tokenized.id": "AKIAIOSFODNN7EXAMPLE" }, "Metric": "db.load.avg" }, "DataPoints": [ //... 24 datapoints ] }, // In total 11 entries, 10 Keys of top tokenized SQL, 1 total key ] //End of MetricList } //End of response
このレスポンスの MetricList には 11 のエントリがあり (合計が 1 つと、トークン分割された上位 10 項目の SQL)、各エントリには、1 時間あたり 24 の DataPoints があります。
トークン分割された SQL の場合は、各ディメンションリストに 3 つのエントリがあります。
-
db.sql_tokenized.statement- トークン分割された SQL ステートメント。 -
db.sql_tokenized.db_id- SQL の参照に使用されていたネイティブデータベース ID、または Performance Insights によって生成される合成 ID (ネイティブデータベース ID が利用できない場合)。この例では、pi-2372568224合成 ID が返ります。 -
db.sql_tokenized.id- Performance Insights 内のクエリの ID。AWS Management Console で、この ID はサポート ID と呼ばれます。ID は、データベースに関する問題のトラブルシューティングに役立つ、AWS サポートが調査できるデータであるため、この名前が付けられています。AWS は、データのセキュリティとプライバシーを非常に重視しており、ほとんどすべてのデータが AWS KMS キーで暗号化されて保存されます。そのため、このデータを AWS 内で見ることはできません。前の例では、
tokenized.statementとtokenized.db_idの両方が暗号化されて保存されます。データベースに問題がある場合は、AWS サポートがサポート ID を参照して問題を解決できるようお手伝いします。
クエリを実行する際、Group で GroupBy を指定した方が便利な場合があります。ただし、返るデータを詳細に制御できるように、ディメンションのリストを指定します。例えば、必要なデータが db.sql_tokenized.statement のみの場合は、Dimensions 属性を query.json ファイルに追加することができます。
[ { "Metric": "db.load.avg", "GroupBy": { "Group": "db.sql_tokenized", "Dimensions":["db.sql_tokenized.statement"], "Limit": 10 } } ]
SQL によってフィルタリングされた平均 DB ロードの取得
上のイメージは、特定のクエリが選択されていることを示しています。上位の平均アクティブセッションのスタックされたエリアグラフはそのクエリを対象としています。クエリは、依然として上位 7 つの全体的な待機イベントを対象としていますが、レスポンスの値はフィルタリングされます。フィルタでは、特定のフィルタに一致するセッションのみが考慮されます。
この例に対応する API クエリは、上位の SQL に関する DB 平均負荷の取得 のコマンドに似ています。ただし、query.json ファイルには、次の内容が含まれます。
[ { "Metric": "db.load.avg", "GroupBy": { "Group": "db.wait_event", "Limit": 5 }, "Filter": { "db.sql_tokenized.id": "AKIAIOSFODNN7EXAMPLE" } } ]
Linux、macOS、Unix の場合:
aws pi get-resource-metrics \ --service-type RDS \ --identifier db-ID\ --start-time2018-10-30T00:00:00Z\ --end-time2018-10-30T01:00:00Z\ --period-in-seconds60\ --metric-queries file://query.json
Windows の場合:
aws pi get-resource-metrics ^ --service-type RDS ^ --identifier db-ID^ --start-time2018-10-30T00:00:00Z^ --end-time2018-10-30T01:00:00Z^ --period-in-seconds60^ --metric-queries file://query.json
レスポンスは次の例のようになります。
{ "Identifier": "db-XXX", "AlignedStartTime": 1556215200.0, "MetricList": [ { "Key": { "Metric": "db.load.avg" }, "DataPoints": [ { "Timestamp": 1556218800.0, "Value": 1.4878117913832196 }, { "Timestamp": 1556222400.0, "Value": 1.192823803967328 } ] }, { "Key": { "Metric": "db.load.avg", "Dimensions": { "db.wait_event.type": "io", "db.wait_event.name": "wait/io/aurora_redo_log_flush" } }, "DataPoints": [ { "Timestamp": 1556218800.0, "Value": 1.1360544217687074 }, { "Timestamp": 1556222400.0, "Value": 1.058051341890315 } ] }, { "Key": { "Metric": "db.load.avg", "Dimensions": { "db.wait_event.type": "io", "db.wait_event.name": "wait/io/table/sql/handler" } }, "DataPoints": [ { "Timestamp": 1556218800.0, "Value": 0.16241496598639457 }, { "Timestamp": 1556222400.0, "Value": 0.05163360560093349 } ] }, { "Key": { "Metric": "db.load.avg", "Dimensions": { "db.wait_event.type": "synch", "db.wait_event.name": "wait/synch/mutex/innodb/aurora_lock_thread_slot_futex" } }, "DataPoints": [ { "Timestamp": 1556218800.0, "Value": 0.11479591836734694 }, { "Timestamp": 1556222400.0, "Value": 0.013127187864644107 } ] }, { "Key": { "Metric": "db.load.avg", "Dimensions": { "db.wait_event.type": "CPU", "db.wait_event.name": "CPU" } }, "DataPoints": [ { "Timestamp": 1556218800.0, "Value": 0.05215419501133787 }, { "Timestamp": 1556222400.0, "Value": 0.05805134189031505 } ] }, { "Key": { "Metric": "db.load.avg", "Dimensions": { "db.wait_event.type": "synch", "db.wait_event.name": "wait/synch/mutex/innodb/lock_wait_mutex" } }, "DataPoints": [ { "Timestamp": 1556218800.0, "Value": 0.017573696145124718 }, { "Timestamp": 1556222400.0, "Value": 0.002333722287047841 } ] } ], "AlignedEndTime": 1556222400.0 } //end of response
このレスポンスでは、query.json ファイルで指定されているトークン分割化された SQL AKIAIOSFODNN7EXAMPLE の割合に従って、値はすべてフィルタリングされます。キーは、フィルタなしのクエリとは異なる順序で表示されることもあります。これは、フィルタ処理された SQL に影響を与えるのは上位 5 つの待機イベントであるためです。
SQL ステートメントの全文の取得
次の例では、DB インスタンス db-10BCD2EFGHIJ3KL4M5NO6PQRS5 の SQL ステートメントの全文を取得します。--group は db.sql であり、--group-identifier は db.sql.id です。この例では、my-sql-id は、pi
get-resource-metrics または pi describe-dimension-keys を呼び出して取得した SQL ID を表します。
以下のコマンドを実行します。
Linux、macOS、Unix の場合:
aws pi get-dimension-key-details \ --service-type RDS \ --identifier db-10BCD2EFGHIJ3KL4M5NO6PQRS5 \ --group db.sql \ --group-identifiermy-sql-id\ --requested-dimensions statement
Windows の場合:
aws pi get-dimension-key-details ^ --service-type RDS ^ --identifier db-10BCD2EFGHIJ3KL4M5NO6PQRS5 ^ --group db.sql ^ --group-identifiermy-sql-id^ --requested-dimensions statement
この例では、ディメンションの詳細を使用できます。したがって、Performance Insights は、SQL ステートメントを切り捨てることなく、その全文を取得します。
{ "Dimensions":[ { "Value": "SELECT e.last_name, d.department_name FROM employees e, departments d WHERE e.department_id=d.department_id", "Dimension": "db.sql.statement", "Status": "AVAILABLE" }, ... ] }
一定期間のパフォーマンス分析レポートの作成
次の例では、db-loadtest-0 データベースの 1682969503 開始時間と 1682979503 終了時間を使用してパフォーマンス分析レポートを作成します。
aws pi create-performance-analysis-report \ --service-type RDS \ --identifier db-loadtest-0 \ --start-time 1682969503 \ --end-time 1682979503 \ --region us-west-2
レスポンスは、レポートの一意識別子 report-0234d3ed98e28fb17 です。
{ "AnalysisReportId": "report-0234d3ed98e28fb17" }
パフォーマンス分析レポートの取得
次の例では、report-0d99cc91c4422ee61 レポートについて分析レポートの詳細を取得します。
aws pi get-performance-analysis-report \ --service-type RDS \ --identifier db-loadtest-0 \ --analysis-report-id report-0d99cc91c4422ee61 \ --region us-west-2
レスポンスには、レポートのステータス、ID、時間の詳細、およびインサイトが表示されます。
{ "AnalysisReport": { "Status": "Succeeded", "ServiceType": "RDS", "Identifier": "db-loadtest-0", "StartTime": 1680583486.584, "AnalysisReportId": "report-0d99cc91c4422ee61", "EndTime": 1680587086.584, "CreateTime": 1680587087.139, "Insights": [ ... (Condensed for space) ] } }
DB インスタンスのすべてのパフォーマンス分析レポートを一覧表示する
次の例は、db-loadtest-0 データベースについて入手可能なすべてのパフォーマンス分析レポートを一覧表示します。
aws pi list-performance-analysis-reports \ --service-type RDS \ --identifier db-loadtest-0 \ --region us-west-2
レスポンスには、すべてのレポートがレポートの ID、ステータス、および時間の詳細とともに一覧表示されます。
{ "AnalysisReports": [ { "Status": "Succeeded", "EndTime": 1680587086.584, "CreationTime": 1680587087.139, "StartTime": 1680583486.584, "AnalysisReportId": "report-0d99cc91c4422ee61" }, { "Status": "Succeeded", "EndTime": 1681491137.914, "CreationTime": 1681491145.973, "StartTime": 1681487537.914, "AnalysisReportId": "report-002633115cc002233" }, { "Status": "Succeeded", "EndTime": 1681493499.849, "CreationTime": 1681493507.762, "StartTime": 1681489899.849, "AnalysisReportId": "report-043b1e006b47246f9" }, { "Status": "InProgress", "EndTime": 1682979503.0, "CreationTime": 1682979618.994, "StartTime": 1682969503.0, "AnalysisReportId": "report-01ad15f9b88bcbd56" } ] }
パフォーマンス分析レポートの削除
次の例では、db-loadtest-0 データベースの分析レポートを削除します。
aws pi delete-performance-analysis-report \ --service-type RDS \ --identifier db-loadtest-0 \ --analysis-report-id report-0d99cc91c4422ee61 \ --region us-west-2
パフォーマンス分析レポートにタグを追加する
次の例では、キー name と値 test-tag のタグを report-01ad15f9b88bcbd56 レポートに追加します。
aws pi tag-resource \ --service-type RDS \ --resource-arn arn:aws:pi:us-west-2:356798100956:perf-reports/RDS/db-loadtest-0/report-01ad15f9b88bcbd56 \ --tags Key=name,Value=test-tag \ --region us-west-2
パフォーマンス分析レポートのすべてのタグを一覧表示する
次の例では、report-01ad15f9b88bcbd56 レポートのすべてのタグを一覧表示します。
aws pi list-tags-for-resource \ --service-type RDS \ --resource-arn arn:aws:pi:us-west-2:356798100956:perf-reports/RDS/db-loadtest-0/report-01ad15f9b88bcbd56 \ --region us-west-2
レスポンスには、レポートに追加されたすべてのタグの値とキーが一覧表示されます。
{ "Tags": [ { "Value": "test-tag", "Key": "name" } ] }
パフォーマンス分析レポートからタグを削除する
次の例では、report-01ad15f9b88bcbd56 レポートから name タグを削除します。
aws pi untag-resource \ --service-type RDS \ --resource-arn arn:aws:pi:us-west-2:356798100956:perf-reports/RDS/db-loadtest-0/report-01ad15f9b88bcbd56 \ --tag-keys name \ --region us-west-2
タグを削除した後、list-tags-for-resource API を呼び出しても、このタグは一覧に表示されません。
