# Performance Insights 的 Amazon CLI 示例 在以下各节中，详细了解性能详情的 Amazon Command Line Interface（Amazon CLI）并使用 Amazon CLI 示例。 **Topics** + [ ## 性能详情的 Amazon 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) ## 性能详情的 Amazon CLI 的内置帮助 您可以使用 Amazon CLI 查看 Performance Insights 数据。可以通过在命令行上输入以下内容来查看 Performance Insights 的 Amazon CLI 命令的帮助。 ``` aws pi help ``` 如果尚未安装 Amazon CLI，请参阅《Amazon CLI 用户指南》**中的[安装 Amazon CLI](https://docs.amazonaws.cn/cli/latest/userguide/installing.html) 来了解安装信息。 ## 检索计数器指标 以下屏幕截图显示 Amazon Web Services 管理控制台 中的两个计数器指标图表。 ![\[计数器指标图表。\]](http://docs.amazonaws.cn/AmazonRDS/latest/UserGuide/images/perf-insights-api-counters-charts.png) 以下示例显示如何收集 Amazon Web Services 管理控制台 用于生成两个计数器指标图表的相同数据。 对于 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` – 对于 Amazon RDS 来说为 `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` 中有两个元素。 ## 检索首要等待事件的数据库负载平均值 以下示例是 Amazon Web Services 管理控制台用于生成堆栈区域线图的相同查询。此示例检索按前七个等待事件划分负载的最后一个小时的 `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`。有关此示例的有效值的详细信息，请参阅 *Performance Insights API 参考* 中的 [DimensionGroup](https://docs.amazonaws.cn/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 小时，以秒为单位的期间为一小时。 此示例指定指标 `db.load.avg` 和前七个等待事件的 `GroupBy`。有关此示例的有效值的详细信息，请参阅 *Performance Insights API 参考* 中的 [DimensionGroup](https://docs.amazonaws.cn/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，或 Performance Insights 为您生成的合成 ID（如果本机数据库 ID 不可用）。此示例返回 `pi-2372568224` 合成 ID。 + `db.sql_tokenized.id`：Performance Insights 中的查询的 ID。 在 Amazon Web Services 管理控制台中，此 ID 称为支持 ID。它如此命名是因为 ID 是 Amazon 支持服务可检查以帮助您解决数据库问题的数据。Amazon 极其重视您的数据的安全性和隐私，几乎所有数据都使用您的 Amazon KMS 密钥进行加密存储。因此，Amazon 中的任何人都无法查看这些数据。在上一个示例中，`tokenized.statement` 和 `tokenized.db_id` 都进行了加密存储。如果您的数据库出现问题，Amazon 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.amazonaws.cn/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 文件中指定的令牌化 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 ``` 在此示例中，有维度详细信息。因此，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-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 ``` ## 向性能分析报告中添加标签 以下示例向 `report-01ad15f9b88bcbd56` 报告中添加了一个键为 `name`、值为 `test-tag` 的标签。 ``` 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 不会列出此标签。