# Performance Insights API for Aurora によるメトリクスの取得
Performance Insights がオンになっている場合、API はインスタンスのパフォーマンスを可視化します。Amazon CloudWatch Logs は、AWS のサービスをモニタリングしたメトリクスの信頼性のある提供元です。
Performance Insightsは、平均アクティブ・セッション(AAS)として測定されるデータベースロードのドメイン固有のビューを提供します。このメトリクスはAPI利用者には2次元時系列データセットのように見えます。データの時間ディメンションは、クエリされた時間範囲内の各時点のDBロード・データを提供します。各時点で、その時点で計測された `SQL`、`Wait-event`、`User`、`Host` などのリクエストされたディメンションに関する負荷全体が分解されます。
Amazon RDS Performance Insights では、 Amazon Aurora DB クラスターをモニタリングし、データベースパフォーマンスの分析とトラブルシューティングを行うことができます。Performance Insights は、AWS マネジメントコンソール で表示することができます。また、Performance Insights では独自のデータをクエリできるように、パブリック API も提供されています。API を使用して、次を実行できます。
+ データベースにデータをオフロードする
+ Performance Insights データを既存のモニタリングダッシュボードに追加する
+ モニタリングツールを構築する
Performance Insights API を使用するには、いずれかの Amazon RDS DB インスタンスで Performance Insights を有効にします。Performance Insights の有効化については、「[Aurora の Performance Insights の有効化と無効化](USER_PerfInsights.Enabling.md)」を参照してください。Performance Insights API の詳細については、「[Amazon RDS Performance Insights API リファレンス](https://docs.aws.amazon.com/performance-insights/latest/APIReference/Welcome.html)」を参照してください。
Performance Insights API は、以下のオペレーションを提供します。
****
| Performance Insights でのアクション | AWS CLI コマンド | 説明 |
| --- | --- | --- |
| [https://docs.aws.amazon.com/performance-insights/latest/APIReference/API_CreatePerformanceAnalysisReport.html](https://docs.aws.amazon.com/performance-insights/latest/APIReference/API_CreatePerformanceAnalysisReport.html) | [https://docs.aws.amazon.com/cli/latest/reference/pi/CreatePerformanceAnalysisReport.html](https://docs.aws.amazon.com/cli/latest/reference/pi/CreatePerformanceAnalysisReport.html) | DB インスタンスの特定の期間のパフォーマンス分析レポートを作成します。結果は、レポートの固有識別子である `AnalysisReportId` です。 |
| [https://docs.aws.amazon.com/performance-insights/latest/APIReference/API_DeletePerformanceAnalysisReport.html](https://docs.aws.amazon.com/performance-insights/latest/APIReference/API_DeletePerformanceAnalysisReport.html) | [https://docs.aws.amazon.com/cli/latest/reference/pi/DeletePerformanceAnalysisReport.html](https://docs.aws.amazon.com/cli/latest/reference/pi/DeletePerformanceAnalysisReport.html) | パフォーマンス分析レポートを削除します。 |
| [https://docs.aws.amazon.com/performance-insights/latest/APIReference/API_DescribeDimensionKeys.html](https://docs.aws.amazon.com/performance-insights/latest/APIReference/API_DescribeDimensionKeys.html) | [https://docs.aws.amazon.com/cli/latest/reference/pi/describe-dimension-keys.html](https://docs.aws.amazon.com/cli/latest/reference/pi/describe-dimension-keys.html) | 特定の期間に、メトリクスの上位 N 個のディメンションキーを取得します。 |
| [https://docs.aws.amazon.com/performance-insights/latest/APIReference/API_GetDimensionKeyDetails.html](https://docs.aws.amazon.com/performance-insights/latest/APIReference/API_GetDimensionKeyDetails.html) | [https://docs.aws.amazon.com/cli/latest/reference/pi/get-dimension-key-details.html](https://docs.aws.amazon.com/cli/latest/reference/pi/get-dimension-key-details.html) | DB インスタンスまたはデータソースの指定されたディメンショングループの属性を取得します。例えば、SQL ID を指定し、ディメンションの詳細が使用可能な場合、`GetDimensionKeyDetails` は、この ID に関連付けられているディメンション `db.sql.statement` の全文を取得します。このオペレーションは、`GetResourceMetrics` および `DescribeDimensionKeys` が大きな SQL ステートメントテキストの取得をサポートしないため、便利です。 |
| [https://docs.aws.amazon.com/performance-insights/latest/APIReference/API_GetPerformanceAnalysisReport.html](https://docs.aws.amazon.com/performance-insights/latest/APIReference/API_GetPerformanceAnalysisReport.html) | [https://docs.aws.amazon.com/cli/latest/reference/pi/GetPerformanceAnalysisReport.html](https://docs.aws.amazon.com/cli/latest/reference/pi/GetPerformanceAnalysisReport.html) | レポートのインサイトを含むレポートを取得します。結果には、レポートのステータス、レポート ID、レポート時間の詳細、インサイト、および推奨事項が含まれます。 |
| [GetResourceMetadata](https://docs.aws.amazon.com/performance-insights/latest/APIReference/API_GetResourceMetadata.html) | [https://docs.aws.amazon.com/cli/latest/reference/pi/get-resource-metadata.html](https://docs.aws.amazon.com/cli/latest/reference/pi/get-resource-metadata.html) | さまざまな機能に関するメタデータを取得します。例えば、メタデータにより、特定の DB インスタンスで何等かの機能が有効化されているか無効化されているかを、示すことができます。 |
| [https://docs.aws.amazon.com/performance-insights/latest/APIReference/API_GetResourceMetrics.html](https://docs.aws.amazon.com/performance-insights/latest/APIReference/API_GetResourceMetrics.html) | [https://docs.aws.amazon.com/cli/latest/reference/pi/get-resource-metrics.html](https://docs.aws.amazon.com/cli/latest/reference/pi/get-resource-metrics.html) | 期間中、データソースのセットに Performance Insights のメトリクスを取得します。特定のディメンショングループおよびディメンションを提供し、各グループの集約とフィルタリング条件を提供することができます。 |
| [ListAvailableResourceDimensions](https://docs.aws.amazon.com/performance-insights/latest/APIReference/API_ListAvailableResourceDimensions.html) | [https://docs.aws.amazon.com/cli/latest/reference/pi/list-available-resource-dimensions.html](https://docs.aws.amazon.com/cli/latest/reference/pi/list-available-resource-dimensions.html) | 指定したインスタンスで、指定したメトリクスタイプごとにクエリできるディメンションを取得します。 |
| [ListAvailableResourceMetrics](https://docs.aws.amazon.com/performance-insights/latest/APIReference/API_ListAvailableResourceMetrics.html) | [https://docs.aws.amazon.com/cli/latest/reference/pi/list-available-resource-metrics.html](https://docs.aws.amazon.com/cli/latest/reference/pi/list-available-resource-metrics.html) | DB インスタンスを指定しながら、指定されたメトリクスタイプでクエリが可能なメトリクスをすべて取得します。 |
| `[ListPerformanceAnalysisReports](https://docs.aws.amazon.com/performance-insights/latest/APIReference/API_ListPerformanceAnalysisReports.html)` | [https://docs.aws.amazon.com/cli/latest/reference/pi/list-performance-analysis-reports.html](https://docs.aws.amazon.com/cli/latest/reference/pi/list-performance-analysis-reports.html) | DB インスタンスについて入手可能なすべての分析レポートを取得します。レポートは、各レポートの開始時間に基づいて一覧表示されます。 |
| `[ListTagsForResource](https://docs.aws.amazon.com/performance-insights/latest/APIReference/API_ListTagsForResource.html)` | [https://docs.aws.amazon.com/cli/latest/reference/pi/list-tags-for-resource.html](https://docs.aws.amazon.com/cli/latest/reference/pi/list-tags-for-resource.html) | リソースに追加されたすべてのメタデータタグを一覧表示します。リストには、タグの名前と値が含まれます。 |
| `[TagResource](https://docs.aws.amazon.com/performance-insights/latest/APIReference/API_TagResource.html)` | [https://docs.aws.amazon.com/cli/latest/reference/pi/tag-resource.html](https://docs.aws.amazon.com/cli/latest/reference/pi/tag-resource.html) | Amazon RDS リソースにメタデータタグを追加します。タグには名前と値が含まれます。 |
| `[UntagResource](https://docs.aws.amazon.com/performance-insights/latest/APIReference/API_UntagResource.html)` | [https://docs.aws.amazon.com/cli/latest/reference/pi/untag-resource.html](https://docs.aws.amazon.com/cli/latest/reference/pi/untag-resource.html) | メタデータタグをリソースから削除します。 |
Performance Insights の時系列メトリクスの取得と AWS CLI の例の詳細については、以下のトピックを参照してください。
**Topics**
+ [Performance Insights の時系列メトリクスの取得](USER_PerfInsights.API.TimeSeries.md)
+ [AWS CLIPerformance Insights での の例](USER_PerfInsights.API.Examples.md)
# Performance Insights の時系列メトリクスの取得
`GetResourceMetrics` オペレーションでは、1 つ以上の時系列メトリクスを Performance Insights データから取得します。`GetResourceMetrics` には、メトリクスおよび期間が必要であり、データポイントのリストを含むレスポンスが返ります。
例えば、AWS マネジメントコンソール は、次のイメージのように、[**カウンターメトリクス**] チャートと [**データベースロード**] チャートの入力に `GetResourceMetrics` を使用します。
![\[カウンターメトリクスグラフおよびデータベースロードグラフ\]](http://docs.aws.amazon.com/ja_jp/AmazonRDS/latest/AuroraUserGuide/images/perf-insights-api-charts.png)
`GetResourceMetrics` によって返るメトリクスはすべて、`db.load` の例外を除き、スタンダードの時系列メトリクスです。このメトリクスは、[**データベースロード**] グラフに表示されます。この `db.load` メトリクスは、*ディメンション*と呼ばれるサブコンポーネントに分割できるため、他の時系列メトリクスとは異なります。前のイメージでは、`db.load` は分割され、`db.load` を構成する待機状態によってグループ化されています。
**注記**
`GetResourceMetrics` は、`db.sampleload` メトリクスを返すこともできますが、通常 `db.load` メトリクスが適切です。
`GetResourceMetrics` により返されるカウンターメトリクスに関する情報は、「[Performance Insights カウンターメトリクス](USER_PerfInsights_Counters.md)」を参照してください。
以下の計算は、メトリクスにサポートされています。
+ 平均 - 期間中のメトリクスの平均値。`.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 コマンドの使用の詳細については、「[https://docs.aws.amazon.com/cli/latest/reference/pi/get-resource-metrics.html](https://docs.aws.amazon.com/cli/latest/reference/pi/get-resource-metrics.html)」を参照してください。
`--metric-queries` オプションでは、結果を取得する 1 つ以上のクエリを指定します。各クエリは、必須の `Metric` と、オプションの `GroupBy` および `Filter` パラメータから構成されます。`--metric-queries` オプションの指定の例を次に示します。
```
{
"Metric": "string",
"GroupBy": {
"Group": "string",
"Dimensions": ["string", ...],
"Limit": integer
},
"Filter": {"string": "string"
...}
```
# AWS CLIPerformance Insights での の例
以下のセクションでは、Performance Insights の AWS Command Line Interface (AWS CLI) の詳細と AWS CLI の使用例について説明します。
**Topics**
+ [Performance Insights の AWS CLI の組み込みヘルプ](#USER_PerfInsights.API.CLI)
+ [カウンターメトリクスの取得](#USER_PerfInsights.API.Examples.CounterMetrics)
+ [上位の待機イベントに関する DB 平均負荷の取得](#USER_PerfInsights.API.Examples.DBLoadAverage)
+ [上位の SQL に関する DB 平均負荷の取得](#USER_PerfInsights.API.Examples.DBLoadAverageTop10SQL)
+ [SQL によってフィルタリングされた平均 DB ロードの取得](#USER_PerfInsights.API.Examples.DBLoadAverageFilterBySQL)
+ [SQL ステートメントの全文の取得](#USER_PerfInsights.API.Examples.GetDimensionKeyDetails)
+ [一定期間のパフォーマンス分析レポートの作成](#USER_PerfInsights.API.Examples.CreatePerfAnalysisReport)
+ [パフォーマンス分析レポートの取得](#USER_PerfInsights.API.Examples.GetPerfAnalysisReport)
+ [DB インスタンスのすべてのパフォーマンス分析レポートを一覧表示する](#USER_PerfInsights.API.Examples.ListPerfAnalysisReports)
+ [パフォーマンス分析レポートの削除](#USER_PerfInsights.API.Examples.DeletePerfAnalysisReport)
+ [パフォーマンス分析レポートにタグを追加する](#USER_PerfInsights.API.Examples.TagPerfAnalysisReport)
+ [パフォーマンス分析レポートのすべてのタグを一覧表示する](#USER_PerfInsights.API.Examples.ListTagsPerfAnalysisReport)
+ [パフォーマンス分析レポートからタグを削除する](#USER_PerfInsights.API.Examples.UntagPerfAnalysisReport)
## Performance Insights の AWS CLI の組み込みヘルプ
Performance Insights は、AWS CLI を使用して表示することができます。Performance Insights の AWS CLI コマンドのヘルプを表示するには、コマンドラインで次のように入力します。
```
aws pi help
```
AWS CLI がインストールされていない場合は、「*AWS CLI ユーザーガイド*」の「[AWS CLI のインストール](https://docs.aws.amazon.com/cli/latest/userguide/installing.html)」でインストールの方法を確認してください。
## カウンターメトリクスの取得
以下のスクリーンショットは、AWS マネジメントコンソール における 2 つのカウンターメトリクスグラフを示します。
![\[カウンターメトリクスグラフ\]](http://docs.aws.amazon.com/ja_jp/AmazonRDS/latest/AuroraUserGuide/images/perf-insights-api-counters-charts.png)
以下の例では、2 つのカウンターメトリクスグラフを生成するために AWS マネジメントコンソール で使用するデータと同じデータを生成する方法を示します。
Linux、macOS、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、macOS、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-type` - `RDS` for Amazon RDS
+ `--identifier` - DB インスタンスのリソース ID
+ `--start-time` および `--end-time` - クエリを実行する期間の ISO 8601 `DateTime` 値 (サポートされている複数の形式)
クエリは 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 マネジメントコンソール で使用されるのと同じクエリです。この例では、上位 7 つの待機イベントに応じて負荷を分割し、最後の 1 時間で `db.load.avg` を取得します。コマンドは [カウンターメトリクスの取得](#USER_PerfInsights.API.Examples.CounterMetrics) と同じコマンドです。ただし、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-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.avg` と `GroupBy` のメトリクスを指定しています。この例の有効な値の詳細については、*Performance Insights の API リファレンス*の「[DimensionGroup](https://docs.aws.amazon.com/performance-insights/latest/APIReference/API_DimensionGroup.html)」を参照してください。
レスポンスは次の例のようになります。
```
{
"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 平均負荷の取得](#USER_PerfInsights.API.Examples.DBLoadAverage) のコマンドに似ています。ただし、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-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.avg` と `GroupBy` のメトリクスを指定しています。この例の有効な値の詳細については、*Performance Insights の API リファレンス*の「[DimensionGroup](https://docs.aws.amazon.com/performance-insights/latest/APIReference/API_DimensionGroup.html)」を参照してください。
レスポンスは次の例のようになります。
```
{
"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 マネジメントコンソール で、この 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 ロードの取得
![\[SQL グラフでフィルタリングします。\]](http://docs.aws.amazon.com/ja_jp/AmazonRDS/latest/AuroraUserGuide/images/perf-insights-api-filter-chart.png)
上のイメージは、特定のクエリが選択されていることを示しています。上位の平均アクティブセッションのスタックされたエリアグラフはそのクエリを対象としています。クエリは、依然として上位 7 つの全体的な待機イベントを対象としていますが、レスポンスの値はフィルタリングされます。フィルタでは、特定のフィルタに一致するセッションのみが考慮されます。
この例に対応する API クエリは、[上位の SQL に関する DB 平均負荷の取得](#USER_PerfInsights.API.Examples.DBLoadAverageTop10SQL) のコマンドに似ています。ただし、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-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 つの待機イベントであるためです。
## 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-identifier my-sql-id \
--requested-dimensions statement
```
Windows の場合:
```
aws pi get-dimension-key-details ^
--service-type RDS ^
--identifier db-10BCD2EFGHIJ3KL4M5NO6PQRS5 ^
--group db.sql ^
--group-identifier my-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 を呼び出しても、このタグは一覧に表示されません。