本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # AWS CLI 績效詳情的範例 在下列各節中，進一步了解績效詳情的 AWS Command Line Interface (AWS CLI)，並使用 AWS CLI 範例。 **Topics** + [for Performance Insights AWS CLI 的內建說明](#USER_PerfInsights.API.CLI) + [擷取計數器指標](#USER_PerfInsights.API.Examples.CounterMetrics) + [擷取最久等待事件的資料庫負載平均值](#USER_PerfInsights.API.Examples.DBLoadAverage) + [擷取最高 SQL 的資料庫負載平均值](#USER_PerfInsights.API.Examples.DBLoadAverageTop10SQL) + [擷取依據 SQL 篩選的資料庫負載平均值](#USER_PerfInsights.API.Examples.DBLoadAverageFilterBySQL) + [擷取 SQL 陳述式的完整文字](#USER_PerfInsights.API.Examples.GetDimensionKeyDetails) + [建立一段時間區間的績效分析報告](#USER_PerfInsights.API.Examples.CreatePerfAnalysisReport) + [擷取績效分析報告](#USER_PerfInsights.API.Examples.GetPerfAnalysisReport) + [列出資料庫執行個體的所有績效分析報告](#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) ## for Performance Insights AWS CLI 的內建說明 您可以使用 AWS CLI檢視績效詳情資料。您可以在 AWS CLI 命令列中輸入以下內容，以檢視 Performance Insights 命令的說明。 ``` aws pi help ``` 如果您尚未 AWS CLI 安裝 ，請參閱*AWS CLI 《 使用者指南*》中的[安裝 AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/installing.html) ，以取得安裝相關資訊。 ## 擷取計數器指標 下列螢幕擷取畫面顯示 AWS 管理主控台中的兩個計數器指標圖表。 ![\[計數器指標圖表。\]](http://docs.aws.amazon.com/zh_tw/AmazonRDS/latest/UserGuide/images/perf-insights-api-counters-charts.png) 下列範例示範如何收集 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`– 資料執行個體的資源 ID + `--start-time` 和 `--end-time` – 要查詢期間的 ISO 8601 `DateTime` 值，支援多種格式 它會查詢一小時的時間範圍： + `--period-in-seconds`–`60` 適用於每分鐘的查詢 + `--metric-queries`– 兩個查詢的陣列，一個指標剛好一個查詢。 此指標名稱會使用點將指標分類在實用的類別，其中最後一個元素則做為函數。在此範例中，此函數是每個查詢的 `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`。每個 `Datapoints` 清單有 60 個資料點，因為查詢是適用於一小時中的每分鐘資料，內含 `Timestamp1/Minute1`、`Timestamp2/Minute2` 等，最多可達 `Timestamp60/Minute60`。 因為此查詢是適用於兩個不同的計數器指標，回應 `MetricList` 中會有兩個元素。 ## 擷取最久等待事件的資料庫負載平均值 下列範例與 AWS 管理主控台 用來產生堆疊區域折線圖的查詢相同。此範例會使用根據前七個最久的等待事件而區分的負載來擷取前一小時的 `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 ``` 此範例會指定 `db.load.avg` 指標與前七個最久等待事件的 `GroupBy`。如需此範例有效值的詳細資訊，請參閱*績效詳情 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` 中有八個項目。有一個項目適用於總計 `db.load.avg`，有七個項目，分別適用於根據前七個最久等待事件區份的 `db.load.avg`。與第一個範例不同，因為其中有分組維度，每個指標分組都必須有一個索引鍵。每個指標不能只有一個索引鍵，如同基本計數器指標使用案例。 ## 擷取最高 SQL 的資料庫負載平均值 以下範例會根據前 10 個 SQL 陳述式來分組 `db.wait_events`。SQL 陳述式有兩個不同的分組： + `db.sql`– 完整的 SQL 陳述式，例如 `select * from customers where customer_id = 123` + `db.sql_tokenized`– 字符化的 SQL 陳述式，例如 `select * from customers where customer_id = ?` 分析資料庫效能時，將僅參數不同的 SQL 陳述式視為單一邏輯項目可能會很有幫助。因此，您可以在查詢時使用 `db.sql_tokenized`。然而，特別是在您對說明計畫感興趣時，使用參數來檢查完整 SQL 陳述式並依據 `db.sql` 來查詢分組有時候會更有幫助。這是字符化與完整 SQL 之間的父子關係，內含使用相同字符化 SQL (父項) 分組的多個完整 SQL (子項)。 此範例中的命令與 [擷取最久等待事件的資料庫負載平均值](#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 ``` 此範例的查詢會持續 24 小時，其中 period-in-seconds 為一小時。 此範例會指定 `db.load.avg` 指標與前七個最久等待事件的 `GroupBy`。如需此範例有效值的詳細資訊，請參閱*績效詳情 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)，每個項目擁有 24 個每小時 `DataPoints`。 對於字符化的 SQL，每個維度清單中有三個項目： + `db.sql_tokenized.statement`– 字符化的 SQL 陳述式。 + `db.sql_tokenized.db_id `– 參考 SQL 所用的原生資料庫 ID，或是無法使用原生資料庫 ID 時，績效詳情為您產生的合成 ID。此範例會傳回 `pi-2372568224` 合成 ID。 + `db.sql_tokenized.id`– 績效詳情中查詢的 ID。 在 中 AWS 管理主控台，此 ID 稱為支援 ID。它的名稱為這個，因為 ID 是 AWS Support 可以檢查的資料，以協助您對資料庫的問題進行故障診斷。 非常重視資料 AWS 的安全性和隱私權，而且幾乎所有資料都會以您的 AWS KMS 金鑰加密存放。因此，內部沒有人 AWS 可以查看此資料。在先前的範例中，`tokenized.statement` 和 `tokenized.db_id` 都同時會以加密的形式存放。如果您的資料庫發生問題， AWS Support 可以透過參考支援 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 篩選的資料庫負載平均值 ![\[依據 SQL 篩選的圖表。\]](http://docs.aws.amazon.com/zh_tw/AmazonRDS/latest/UserGuide/images/perf-insights-api-filter-chart.png) 先前的影像顯示已選取特定的查詢，最高平均作用中工作階段堆疊區域折線圖的範圍仍涵蓋至該查詢。雖然此查詢仍適用於前七個整體等待事件，系統仍會將回應值篩選出來。此篩選條件會在工作階段符合特定篩選條件時，才進行篩選。 此範例中的對應 API 查詢與 [擷取最高 SQL 的資料庫負載平均值](#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 file.檔案中指定的字符化 SQL AKIAIOSFODNN7EXAMPLE 的影響程度來篩選所有值。此索引鍵遵循的順序可能會與不含篩選條件的查詢不同，因為這是影響篩選 SQL 的前五個等待事件。 ## 擷取 SQL 陳述式的完整文字 下列範例會擷取資料庫執行個體 `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 ``` 在此範例中，維度詳細資訊可供使用。因此，績效詳情會擷取 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-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 不會列出此標籤。