CloudWatch Metrics Insights 中的查询组件和语法 - Amazon CloudWatch
什么内容需要引号或转义字符？逐步构建丰富的查询跨账户查询示例

CloudWatch Metrics Insights 中的查询组件和语法

CloudWatch Metrics Insights 语法如下。

SELECT FUNCTION(metricName)
FROM namespace | SCHEMA(...)
[ WHERE labelKey OPERATOR labelValue [AND ... ] ]
[ GROUP BY labelKey [ , ... ] ]
[ ORDER BY FUNCTION() [ DESC | ASC ] ]
[ LIMIT number ]

Metrics Insights 查询中可能的子句如下。关键字不区分大小写，但是指标名称、命名空间和维度等标识符需区分大小写。

SELECT

必需。指定用于聚合每个时间段的观测值的函数（由提供的时段确定）。还可以指定要查询的指标的名称。

FUNCTION 的有效值为 AVG、COUNT、MAX、MIN 和 SUM。

  • AVG 计算查询匹配的观测值的平均值。

  • COUNT 返回查询匹配的观测值的计数。

  • MAX 返回查询匹配的观测值的最大值。

  • MIN 返回查询匹配的观测值的最小值。

  • SUM 计算查询匹配的观测值的总和。

FROM

必需。指定指标源。您可以指定包含要查询的指标的指标命名空间，也可以指定 SCHEMA 表函数。指标命名空间的示例包括："AWS/EC2"、"AWS/Lambda" 以及您为自定义指标创建的指标命名空间。

包括 / 或任何其他不是字母、数字或下划线的字符在内的指标命名空间必须放在双引号中。有关更多信息，请参阅 什么内容需要引号或转义字符？。

SCHEMA

一个可以在 FROM 子句中使用的可选表函数。使用 SCHEMA 将查询结果范围缩小到仅与维度列表完全匹配的指标或没有维度的指标。

如果您使用 SCHEMA 子句，它必须包含至少一个参数，并且第一个参数必须是被查询的指标命名空间。如果您仅用此命名空间参数指定 SCHEMA，则结果范围只限于没有任何维度的指标。

如果您使用其他参数指定 SCHEMA，命名空间参数之后的其他参数必须为标注键。标签键必须是维度名称。如果您指定了一个或多个标签键，则结果范围仅限于具有该确切维度集的指标。这些标签键的顺序无关紧要。

例如：

  • SELECT AVG(CPUUtilization) FROM "AWS/EC2" 匹配 AWS/EC2 命名空间中的所有 CPUUtilization 指标（无论它们的维度如何），并且会返回单个聚合时间序列。

  • SELECT AVG(CPUUtilization) FROM SCHEMA("AWS/EC2") 只匹配 AWS/EC2 命名空间中没有定义任何维度的 CPUUtilization 指标。

  • SELECT AVG(CPUUtilization) FROM SCHEMA("AWS/EC2", InstanceId) 只匹配向 CloudWatch 报告且只有一个维度（即 CPUUtilization）的 InstanceId 指标。

  • SELECT SUM(RequestCount) FROM SCHEMA("AWS/ApplicationELB", LoadBalancer, AvailabilityZone) 只匹配从 AWS/ApplicationELB 向 CloudWatch 报告且只带有 LoadBalancer 和 AvailabilityZone 两个维度的 RequestCount 指标。

WHERE

可选。使用一个或多个标签键的特定标签值，将结果筛选为仅与指定表达式匹配的指标。例如，WHERE InstanceType = 'c3.4xlarge' 将结果筛选为仅 c3.4xlarge 实例类型，WHERE InstanceType != 'c3.4xlarge' 将结果筛选为除 c3.4xlarge 外的所有实例类型。

在监控账户中运行查询时，可以利用 WHERE AWS.AccountId 将查询结果限制到指定账户。例如，WHERE AWS.AccountId=444455556666 仅查询账户 444455556666 的指标。要将查询限制为仅限监控账户本身中的指标，请使用 WHERE AWS.AccountId=CURRENT_ACCOUNT_ID()。

标签值必须始终放在单引号中。

支持的运算符

WHERE 子句支持以下运算符：

  • = 标签值必须与指定的字符串匹配。

  • != 标签值不得与指定的字符串匹配。

  • AND 指定的两个条件都必须为真才能匹配。您可以使用多个 AND 关键字来指定两个或更多条件。

GROUP BY

可选。将查询结果分组为多个时间序列，每个时间序列对应指定的一个或多个标签键的不同值。例如，使用 GROUP BY InstanceId 为每个 InstanceId 值返回不同的时间序列。使用 GROUP BY ServiceName, Operation 为 ServiceName 和 Operation 值的每个可能组合创建不同的时间序列。

通过 GROUP BY 子句，默认情况下，将使用 GROUP BY 子句中指定的标签序列将结果按字母升序排列。要更改结果的顺序，请在查询中添加 ORDER BY 子句。

在监控账户中运行查询时，您可以使用 GROUP BY AWS.AccountId 来按照结果的来源账户对结果进行分组。

注意

如果某些匹配的指标不包含 GROUP BY 子句中指定的标签键，则会返回名为 Other 的空组。例如，如果指定 GROUP BY ServiceName, Operation 而且某些返回的指标不包括作为维度的 ServiceName，则这些指标将显示为将 Other 作为 ServiceName 的值。

ORDER BY

可选。如果查询返回多个时间序列，则指定返回的时间序列的使用顺序。该顺序基于您在 ORDER BY 子句中指定的 FUNCTION 找到的值。FUNCTION 用于计算每个返回的时间序列中的单个标量值，该值用于确定顺序。

还可以指定使用升序 ASC 或降序 DESC。如果您省略这一步，则默认为升序 ASC。

例如，添加 ORDER BY MAX() DESC 子句将按时间范围内观察到的最大数据点以降序对结果进行排序：这意味着具有最高最大数据点的时间序列会首先返回。

要在 ORDER BY 子句中使用的有效函数为 AVG()、COUNT()、MAX()、MIN() 和 SUM()。

如果您将 ORDER BY 子句与 LIMIT 子句配合使用，则生成的查询为“前 N 个”查询。ORDER BY 对于可能返回大量指标的查询也很有用，因为每个查询返回的时间序列不超过 500 个。如果查询匹配超过 500 个时间序列，并且您使用 ORDER BY 子句并对时间序列进行排序，则排序中前 500 个时间序列是返回的时间序列。

LIMIT

可选。将查询返回的时间序列数量限制为指定的值。您可以指定的最大值为 500，而不指定 LIMIT 的查询也可以返回不超过 500 个时间序列。

将 LIMITED 子句与 ORDER BY 子句配合使用，将获得“前 N 个”查询。

什么内容需要引号或转义字符？

在查询中，标签值必须始终放在单引号中。例如，SELECT MAX(CPUUtilization) FROM "AWS/EC2" WHERE AutoScalingGroupName = 'my-production-fleet'。

包含字母、数字和下划线 (_) 以外的字符的指标命名空间、指标名称和标签键必须放在双引号中。例如，SELECT MAX("My.Metric")。

如果其中一个已包含双引号或单引号（如 Bytes"Input"），您必须用反斜杠转义每个引号，如 SELECT AVG("Bytes\"Input\"")。

如果指标命名空间、指标名称或标签键包含的词为 Metrics Insights 中的保留关键字，则这些词也必须放在双引号中。例如，如果您有名为 LIMIT 的指标，您可以使用 SELECT AVG("LIMIT")。将任何命名空间、指标名称或标签（即使不包含保留关键字）放在双引号中也有效。

有关保留关键字的完整列表，请参阅 保留关键字。

逐步构建丰富的查询

本节说明了如何逐步构建一个使用所有可能子句的完整示例。

我们从以下查询开始，该查询聚合了使用 LoadBalancer 和 AvailabilityZone 两个维度收集的所有 Application Load Balancer RequestCount 指标。

SELECT SUM(RequestCount) 
FROM SCHEMA("AWS/ApplicationELB", LoadBalancer, AvailabilityZone)

现在，如果我们只想查看来自特定负载均衡器的指标，我们可以添加 WHERE 子句，将返回的指标限制为 LoadBalancer 维度的值为 app/load-balancer-1 的指标。

SELECT SUM(RequestCount) 
FROM SCHEMA("AWS/ApplicationELB", LoadBalancer, AvailabilityZone)
WHERE LoadBalancer = 'app/load-balancer-1'

前面的查询将此负载均衡器的所有可用区中的 RequestCount 指标聚合为一个时间序列。如果我们想看到每个可用区的不同时间序列，可以添加 GROUP BY 子句。

SELECT SUM(RequestCount) 
FROM SCHEMA("AWS/ApplicationELB", LoadBalancer, AvailabilityZone)
WHERE LoadBalancer = 'app/load-balancer-1'
GROUP BY AvailabilityZone

接下来，我们可能希望对这些结果进行排序以首先查看最高值。以下 ORDER BY 子句按查询时间范围内每个时间序列报告的最大值以降序对时间序列进行排序：

SELECT SUM(RequestCount) 
FROM SCHEMA("AWS/ApplicationELB", LoadBalancer, AvailabilityZone)
WHERE LoadBalancer = 'app/load-balancer-1'
GROUP BY AvailabilityZone
ORDER BY MAX() DESC

最后，如果我们主要对“前 N 个”类型的查询感兴趣，我们可以使用 LIMIT 子句。这最后一个例子将结果限制为仅带有五个最高 MAX 值的时间序列。

SELECT SUM(RequestCount) 
FROM SCHEMA("AWS/ApplicationELB", LoadBalancer, AvailabilityZone)
WHERE LoadBalancer = 'app/load-balancer-1'
GROUP BY AvailabilityZone
ORDER BY MAX() DESC
LIMIT 5

跨账户查询示例

这些示例在 CloudWatch 跨账户可观测性中设置为监控账户的账户中运行时有效。

以下示例搜索源账户 123456789012 中的所有 Amazon EC2 实例并返回平均值。

SELECT AVG(CpuUtilization) 
FROM "AWS/EC2" 
WHERE AWS.AccountId ='123456789012'

以下示例查询所有关联源账户中 AWS/EC2 的 CPUUtilization 指标，并按账户 ID 和实例类型对结果进行分组。

SELECT AVG(CpuUtilization) 
FROM "AWS/EC2" 
GROUP BY AWS.AccountId, InstanceType

以下示例查询监控账户本身中的 CPUUtilization。

SELECT AVG(CpuUtilization) 
FROM "AWS/EC2" 
WHERE AWS.AccountId = CURRENT_ACCOUNT_ID()