Amazon Relational Database Service
ユーザーガイド

パフォーマンスインサイト API

Amazon RDSパフォーマンスインサイト API は、サポートされているエンジンタイプでパフォーマンスインサイトが有効な場合に、RDS インスタンスのパフォーマンスを可視化します。Amazon CloudWatch Logs​ は、AWS のサービスの発行されたモニタリングメトリクスに対して権威あるソースを提供します。パフォーマンスインサイトが提供するドメイン固有のデータベース負荷のビューは、平均のアクティブセッション数として計測され、2 ディメンションの時系列データセットとして API コンシューマーに提供されます。データの時間ディメンションは、クエリを実行した時間範囲の時点ごとにデータベース負荷に関するデータを提供します。各時点で、その時点で計測された SQLWait-eventUserHost などのリクエストされたディメンションに関する負荷全体が分解されます。

Amazon RDSパフォーマンスインサイトでは、Amazon RDS DB インスタンスをモニタリングし、データベースパフォーマンスの分析とトラブルシューティングを行うことができます。パフォーマンスインサイトは、AWS マネジメントコンソール で表示することができます。また、独自のデータをクエリできるように、パブリック API も提供されています。この API は、データベースへのデータのオフロード、既存のモニタリングダッシュボードへのパフォーマンスインサイトの追加、モニタリングツールの構築などに使用できます。パフォーマンスインサイト API を使用するには、いずれかの Amazon RDS DB インスタンスでパフォーマンスインサイトを有効にします。パフォーマンスインサイトの有効化については、「パフォーマンスインサイトの有効化」を参照してください。

Performance Insights API は、以下のオペレーションを提供します。

Performance Insights オペレーション

AWS CLI コマンド

説明

DescribeDimensionKeys

aws pi describe-dimension-keys

特定の期間に、メトリクスの上位 N 個のディメンションキーを取得します。

GetResourceMetrics

aws pi get-resource-metrics

期間中、データソースのセットに Performance Insights のメトリクスを取得します。特定のディメンショングループおよびディメンションを提供し、各グループの集約とフィルタリング条件を提供することができます。

Performance Insights API の詳細については、「Amazon RDS Performance Insights API リファレンス」を参照してください。

パフォーマンスインサイトで AWS CLI を使用する

パフォーマンスインサイトは、AWS CLI を使用して表示することができます。パフォーマンスインサイトの AWS CLI コマンドのヘルプを表示するには、コマンドラインで次のように入力します。

aws pi help

AWS CLI がインストールされていない場合は、『AWS CLI ユーザーガイド』の「AWS コマンドラインインターフェイスのインストール」でインストールの方法を確認してください。

時系列メトリクスの取得

GetResourceMetrics オペレーションでは、1 つ以上の時系列メトリクスをパフォーマンスインサイトデータから取得します。GetResourceMetrics には、メトリクスおよび期間が必要であり、データポイントのリストを含むレスポンスが返ります。

たとえば、AWS マネジメントコンソール のパフォーマンスインサイトのダッシュボードの 2 つの場所で GetResourceMetrics を使用しているとします。GetResourceMetrics は、次の図に示すように、[カウンターメトリクス] グラフおよび [データベースロード] グラフに入力するために使用されます。


					カウンターメトリクスグラフおよびデータベースロードグラフ

GetResourceMetrics によって返るメトリクスはすべて、1 つの例外を除き、標準の時系列メトリクスです。例外として、パフォーマンスインサイトのコアメトリクスである db.load があります。このメトリクスは、[データベースロード] グラフに表示されます。この db.load メトリクスは、ディメンションと呼ばれるサブコンポーネントに分割できるため、他の時系列メトリクスとは異なります。前の図では、db.load は分割され、db.load を構成する待機状態によってグループ化されています。

注記

GetResourceMetrics は、db.sampleload メトリクスを返すこともできますが、通常 db.load メトリクスが適切です。

GetResourceMetrics により返されるカウンタ〜メトリクスに関する情報は、「パフォーマンスインサイトのカウンター」を参照してください。

以下の計算は、メトリクスにサポートされています。

  • 平均 – 期間中のメトリクスの平均値。.avg をメトリクス名に追加します。

  • 最小 – 期間中のメトリクスの最小値。.min をメトリクス名に追加します。

  • 最大 – 期間中のメトリクスの最大値。.max をメトリクス名に追加します。

  • 合計 – 期間中のメトリクス値の合計。.sum をメトリクス名に追加します。

  • サンプル数 – 期間中にメトリクスが収集された回数。.sample_count をメトリクス名に追加します。

たとえば、メトリクスが 300 秒 (5 分) 収集され、メトリクスが 1 分に 1 回収集されたものとみなします。毎分の値は、1、2、3、4、5 です。この場合、以下の計算が返されます。

  • 平均 – 3

  • 最小 – 1

  • 最大 – 5

  • 合計 – 15

  • サンプル数 – 5

get-resource-metrics AWS CLI コマンドの使用の詳細については、「get-resource-metrics」を参照してください。

--metric-queries オプションでは、結果を取得する 1 つ以上のクエリを指定します。各クエリは、必須の Metric と、オプションの GroupBy および Filter パラメータから構成されます。--metric-queries オプションの指定の例を次に示します。

{ "Metric": "string", "GroupBy": { "Group": "string", "Dimensions": ["string", ...], "Limit": integer }, "Filter": {"string": "string" ...} }

AWS CLI のパフォーマンスインサイトの例

パフォーマンスインサイトで AWS CLI を使用する複数の例を以下に示します。

カウンターメトリクスの取得

以下のイメージは、AWS マネジメントコンソール における 2 つのカウンターメトリクスグラフを示します。


					カウンターメトリクスグラフ

以下の例では、2 つのカウンターメトリクスグラフを生成するために AWS マネジメントコンソール で使用するデータと同じデータを生成する方法を示します。

Linux、OS X、Unix の場合:

aws pi get-resource-metrics \ --service-type RDS \ --identifier db-ID \ --start-time 2018-10-30T00:00:00Z \ --end-time 2018-10-30T01:00:00Z \ --period-in-seconds 60 \ --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-time 2018-10-30T00:00:00Z ^ --end-time 2018-10-30T01:00:00Z ^ --period-in-seconds 60 ^ --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、OS X、Unix の場合:

aws pi get-resource-metrics \ --service-type RDS \ --identifier db-ID \ --start-time 2018-10-30T00:00:00Z \ --end-time 2018-10-30T01:00:00Z \ --period-in-seconds 60 \ --metric-queries file://query.json

Windows の場合:

aws pi get-resource-metrics ^ --service-type RDS ^ --identifier db-ID ^ --start-time 2018-10-30T00:00:00Z ^ --end-time 2018-10-30T01:00:00Z ^ --period-in-seconds 60 ^ --metric-queries file://query.json

前述の例では、各オプションに次の値を指定します。

  • --service-typeRDS for Amazon RDS

  • --identifier – DB インスタンスのリソース ID

  • --start-time および --end-time – クエリを実行する期間の ISO 8601 DateTime 値 (サポートされている複数の形式)

クエリは 1 時間の範囲で実行されます。

  • --period-in-seconds60 (1 分ごとのクエリ)

  • --metric-queries – 2 つのクエリの配列。それぞれ 1 つのメトリクスに対して使用されます。

    メトリクス名ではドットを使用してメトリクスを有用なカテゴリに分類します。最終の要素は関数になります。この例では、関数は、クエリの avg です。Amazon CloudWatch と同様に、サポートされている関数は、minmaxtotal、および 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

レスポンスには、IdentifierAlignedStartTime、および AlignedEndTime があります。--period-in-seconds 値が 60 の場合、開始時間および終了時間は、時間 (分) に調整されます。--period-in-seconds3600 の場合、開始時間および終了時間は、時間 (時) に調整されます。

レスポンスの MetricList には、多数のエントリを含み、それぞれに Key および DataPoints エントリがあります。DataPoint にはそれぞれ、Timestamp および Value を含みます。クエリは 1 分ごとのデータが 1 時間以上実行されるため、Datapoints の各リストには、60 個のデータポイントがあります。これには、Timestamp1/Minute1Timestamp2/Minute2 から、Timestamp60/Minute60 まで含まれます。

クエリは 2 つの異なるカウンタメトリクスを対象としているため、レスポンス MetricList には 2 つの要素があります。

上位の待機イベントの DB 平均負荷の取得

以下の例は、スタックされたエリアチャートを生成するために AWS マネジメントコンソール で使用されるのと同じクエリです。この例では、上位 7 つの待機イベントに応じて負荷を分割し、最後の 1 時間で db.load.avg を取得します。コマンドは カウンターメトリクスの取得 と同じコマンドです。ただし、query.json ファイルには、次の内容が含まれます。

[ { "Metric": "db.load.avg", "GroupBy": { "Group": "db.wait_event", "Limit": 7 } } ]

次のコマンドを実行します。

Linux、OS X、Unix の場合:

aws pi get-resource-metrics \ --service-type RDS \ --identifier db-ID \ --start-time 2018-10-30T00:00:00Z \ --end-time 2018-10-30T01:00:00Z \ --period-in-seconds 60 \ --metric-queries file://query.json

Windows の場合:

aws pi get-resource-metrics ^ --service-type RDS ^ --identifier db-ID ^ --start-time 2018-10-30T00:00:00Z ^ --end-time 2018-10-30T01:00:00Z ^ --period-in-seconds 60 ^ --metric-queries file://query.json

この例では、上位 7 つの待機イベントのうち db.load.avgGroupBy のメトリクスを指定しています。この例の有効な値の詳細については、『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、OS X、Unix の場合:

aws pi get-resource-metrics \ --service-type RDS \ --identifier db-ID \ --start-time 2018-10-29T00:00:00Z \ --end-time 2018-10-30T00:00:00Z \ --period-in-seconds 3600 \ --metric-queries file://query.json

Windows の場合:

aws pi get-resource-metrics ^ --service-type RDS ^ --identifier db-ID ^ --start-time 2018-10-29T00:00:00Z ^ --end-time 2018-10-30T00:00:00Z ^ --period-in-seconds 3600 ^ --metric-queries file://query.json

この例では、1 時間の間隔 (秒) で 24 時間以上のクエリを実行します。

この例では、上位 7 つの待機イベントのうち db.load.avgGroupBy のメトリクスを指定しています。この例の有効な値の詳細については、『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、またはパフォーマンスインサイトによって生成される合成 ID (ネイティブデータベース ID が利用できない場合)。この例では、pi-2372568224 合成 ID が返ります。

  • db.sql_tokenized.statement – パフォーマンスインサイト内のクエリの ID。

    AWS マネジメントコンソール で、この ID はサポート ID と呼ばれます。この ID は、データベースの問題をトラブルシューティングしやすいように、AWS サポートが調べることができるデータであるため、このように呼ばれます。AWS はお客様データのセキュリティやプライバシーを重視しており、ほとんどすべてのデータはお客様の AWS KMS キーで暗号化され、保存されています。そのため、このデータを AWS 内で見ることはできません。前述の例では、tokenized_statementtokenized.db_id のいずれも暗号化して保存されています。データベースに問題がある場合は、AWS サポートがサポート ID を参照して問題を解決できるようお手伝いします。

クエリを実行する際、GroupByGroup を指定した方が便利な場合があります。ただし、返るデータを詳細に制御できるように、ディメンションのリストを指定します。たとえば、必要なデータが 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 平均負荷の取得


						SQL グラフでフィルタリングします。

上の図は、特定のクエリが選択されていることを示しています。上位の平均アクティブセッションのスタックされたエリアグラフはそのクエリを対象としています。クエリは、依然として上位 7 つの全体的な待機イベントを対象としていますが、レスポンスの値はフィルタリングされます。フィルタでは、特定のフィルタに一致するセッションのみが考慮されます。

この例に対応する API クエリは、上位の SQL の DB 平均負荷の取得 のコマンドに似ています。ただし、query.json ファイルには、次の内容が含まれます。

[ { "Metric": "db.load.avg", "GroupBy": { "Group": "db.wait_event", "Limit": 5 }, "Filter": { "db.sql_tokenized.id": "AKIAIOSFODNN7EXAMPLE" } } ]

Linux、OS X、Unix の場合:

aws pi get-resource-metrics \ --service-type RDS \ --identifier db-ID \ --start-time 2018-10-30T00:00:00Z \ --end-time 2018-10-30T01:00:00Z \ --period-in-seconds 60 \ --metric-queries file://query.json

Windows の場合:

aws pi get-resource-metrics ^ --service-type RDS ^ --identifier db-ID ^ --start-time 2018-10-30T00:00:00Z ^ --end-time 2018-10-30T01:00:00Z ^ --period-in-seconds 60 ^ --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 つの待機イベントであるためです。