Performance Insights 的 Amazon CLI 示例
在以下各节中，详细了解性能详情的 Amazon Command Line Interface（Amazon CLI）并使用 Amazon CLI 示例。
主题
性能详情的 Amazon CLI 的内置帮助
您可以使用 Amazon CLI 查看 Performance Insights 数据。可以通过在命令行上输入以下内容来查看 Performance Insights 的 Amazon CLI 命令的帮助。
aws pi help
如果尚未安装 Amazon CLI，请参阅《Amazon CLI 用户指南》中的安装 Amazon CLI 来了解安装信息。
检索计数器指标
以下屏幕截图显示 Amazon Web Services Management Console 中的两个计数器指标图表。
以下示例显示如何收集 Amazon Web Services 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 中有两个元素。
检索首要等待事件的数据库负载平均值
以下示例是 Amazon Web Services 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。在 Amazon Web Services Management Console中，此 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 筛选的数据库负载平均值
上图显示选择了特定查询，并且首要平均活动会话堆栈区域线图限定为该查询。虽然查询仍针对前七个总体等待事件，已筛选响应的值。筛选条件使它只考虑与特定筛选条件匹配的会话。
此示例中的相应 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 不会列出此标签。