Performance Insights 的 AWS CLI 示例
在以下各节中，详细了解性能详情的 AWS Command Line Interface（AWS CLI）并使用 AWS CLI 示例。
主题
性能详情的 AWS CLI 的内置帮助
您可以使用 AWS CLI 查看 Performance Insights 数据。可以通过在命令行上输入以下内容来查看 Performance Insights 的 AWS CLI 命令的帮助。
aws pi help
如果尚未安装 AWS CLI，请参阅《AWS CLI 用户指南》中的安装 AWS CLI 来了解安装信息。
检索计数器指标
以下屏幕截图显示 AWS Management Console 中的两个计数器指标图表。
以下示例显示如何收集 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– 对于 Amazon RDS 来说为RDS -
--identifier– 数据库实例的资源 ID -
--start-time和--end-time– 要查询的期间的 ISO 8601DateTime值，支持多种格式
它查询一小时时间范围：
-
--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 Management Console用于生成堆栈区域线图的相同查询。此示例检索按前七个等待事件划分负载的最后一个小时的 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
此示例指定指标 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 中有八个条目。有一个有关总 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（父级）下。
此示例中的命令类似于 检索首要等待事件的数据库负载平均值 中的命令。不过，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
此示例查询 24 小时，以秒为单位的期间为一小时。
此示例指定指标 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），其中每个条目具有 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。在 AWS Management Console中，此 ID 称为支持 ID。它如此命名是因为 ID 是 AWS 支持服务可检查以帮助您解决数据库问题的数据。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 筛选的数据库负载平均值
上图显示选择了特定查询，并且首要平均活动会话堆栈区域线图限定为该查询。虽然查询仍针对前七个总体等待事件，已筛选响应的值。筛选条件使它只考虑与特定筛选条件匹配的会话。
此示例中的相应 API 查询类似于 检索首要 SQL 的数据库负载平均值 中的命令。不过，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。
检索 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-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-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 不会列出此标签。
