CloudWatch 搜索表达式语法 - Amazon CloudWatch
令牌化部分匹配项精确匹配项排除指标架构在搜索中指定属性名称非字母数字字符布尔运算符使用数学表达式
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

CloudWatch 搜索表达式语法

有效的搜索表达式具有以下格式。

SEARCH(' {Namespace, DimensionName1, DimensionName2, ...} SearchTerm', 'Statistic')

例如：

SEARCH('{AWS/EC2,InstanceId} MetricName="CPUUtilization"', 'Average')

  • 查询中单词 SEARCH 之后的第一部分（用大括号括起来）是要搜索的指标架构。指标架构包含指标命名空间以及一个或多个维度名称。在搜索查询中包含指标架构是可选的。如果指定，则指标架构必须包含命名空间，并且可以（可选）包含在该命名空间中有效的一个或多个维度名称。

    除非命名空间或维度名称包含空格或非字母数字字符，否则不需要在指标架构中使用引号。在这种情况下，您必须用双引号将包含这些字符的名称引起来。

  • SearchTerm 也是可选的，但有效的搜索必须包含指标架构和/或 SearchTerm。SearchTerm 通常包含一个或多个账户 ID、指标名称或维度值。SearchTerm 可以通过部分匹配和精确匹配来包含要搜索的多个词语。它还可以包含布尔运算符。

    在 SearchTerm 中使用账户 ID 仅适用于设置为 CloudWatch 跨账户可观测性监控账户的账户。SearchTerm 中账户 ID 的语法是 :aws.AccountId = "444455556666"。您也可以使用 'LOCAL' 来指定监控账户本身：:aws.AccountId = 'LOCAL'

    有关更多信息，请参阅 CloudWatch 跨账户可观测性。

    SearchTerm 可以包含一个或多个指示符，例如 MetricName=（如本例中所示），但不需要使用指示符。

    指标架构和 SearchTerm 必须一起包含在一对单引号中。

  • Statistic 是任何有效 CloudWatch 统计数据的名称。它必须用单引号引起来。有关更多信息，请参阅 统计数据。

上述示例在 AWS/EC2 命名空间中搜索任何具有 InstanceId 作为维度名称的指标。它会返回找到的所有 CPUUtilization 指标，图表显示 Average 统计数据。

搜索表达式只能找到在过去两周内报告了数据的指标。

搜索表达式限制

最大搜索表达式查询大小为 1024 个字符。一个图表上最多可以包含 100 个搜索表达式。一个图表可以显示多达 500 个时间序列。

CloudWatch 搜索表达式：令牌化

当您指定 SearchTerm 时，搜索函数会搜索令牌，即 CloudWatch 自动根据完整的指标名称、维度名称、维度值和命名空间生成的子字符串。CloudWatch 生成的令牌在原始字符串中以驼峰式大小写区分。数字字符也可用作新令牌的开头，非字母数字字符用作分隔符，从而在非字母数字字符之前和之后创建令牌。

相同类型的令牌分隔符字符的连续字符串会生成一个令牌。

所有生成的令牌都是小写的。下表显示了一些生成的令牌示例。

原始字符串 生成的令牌

CustomCount1

customcount1, custom, count, 1

SDBFailure

sdbfailure, sdb, failure

Project2-trial333

project2trial333, project, 2, trial, 333

CloudWatch 搜索表达式：部分匹配项

当您指定 SearchTerm 时，搜索词也会被令牌化。CloudWatch 根据部分匹配项查找指标，部分匹配项是根据搜索词生成的单个令牌与根据指标名称、命名空间、维度名称或维度值生成的单个令牌的匹配项。

与单个令牌匹配的部分匹配搜索是不区分大小写的。例如，使用以下任一搜索词可能会返回 CustomCount1 指标：

  • count

  • Count

  • COUNT

但是，使用 couNT 作为搜索词不会找到 couNT，因为搜索词 CustomCount1 中的大写会被令牌化为 cou 和 NT。

搜索还可以匹配复合令牌，复合令牌是在原始名称中连续出现的多个令牌。为与复合令牌匹配，搜索是区分大小写的。例如，如果原始词是 CustomCount1，则 CustomCount 或 Count1 的搜索成功，但 customcount 或 count1 的搜索不成功。

CloudWatch 搜索表达式：精确匹配项

您可以定义搜索，以便通过使用双引号将搜索词中需要精确匹配的部分引起来，仅查找搜索词的精确匹配项。这些双引号被括在将整个搜索词引起来的单引号中。例如，SEARCH(' {MyNamespace}, "CustomCount1" ', 'Maximum') 找到确切的字符串 CustomCount1（如果它在名为 MyNamespace 的命名空间中作为指标名称、维度名称或维度值存在）。但是，搜索 SEARCH(' {MyNamespace}, "customcount1" ', 'Maximum') 或 SEARCH(' {MyNamespace}, "Custom" ', 'Maximum') 找不到该字符串。

您可以在单个搜索表达式中组合部分匹配词和精确匹配词。例如，SEARCH(' {AWS/NetworkELB, LoadBalancer} "ConsumedLCUs" OR flow ', 'Maximum') 会返回名为 ConsumedLCUs 的 Elastic Load Balancing 指标和包含令牌 flow 的所有 Elastic Load Balancing 指标或维度。

使用精确匹配也是查找具有特殊字符（例如非字母数字字符或空格）的名称的好方法，如下例所示。

SEARCH(' {"My Namespace", "Dimension@Name"}, "Custom:Name[Special_Characters" ', 'Maximum')

CloudWatch 搜索表达式：排除指标架构

到目前为止显示的所有示例都包括指标架构（在大括号中）。省略指标架构的搜索也是有效的。

例如，SEARCH(' "CPUUtilization" ', 'Average') 返回所有与字符串 CPUUtilization 精确匹配的指标名称、维度名称、维度值和命名空间。在 Amazon 指标命名空间中，这可以包括多个服务（包括 Amazon EC2、Amazon ECS、SageMaker 等）中的指标。

要将此搜索范围缩小到只有一个 Amazon 服务，最佳做法是在指标架构中指定命名空间以及任何必要的维度，如以下示例所示。虽然这会缩小对 AWS/EC2 命名空间的搜索范围，但如果您已将 CPUUtilization 定义为其他指标的维度值，它仍会返回这些指标的结果。

SEARCH(' {AWS/EC2, InstanceType} "CPUUtilization" ', 'Average')

或者，您可以在 SearchTerm 中添加命名空间，如以下示例所示。但是在本示例中，搜索将与任何 AWS/EC2 字符串匹配，即使它是自定义维度名称或值。

SEARCH(' "AWS/EC2" MetricName="CPUUtilization" ', 'Average')

CloudWatch 搜索表达式：在搜索中指定属性名称

以下搜索 "CustomCount1" 的精确匹配将返回具有该名称的所有指标。

SEARCH(' "CustomCount1" ', 'Maximum')

但它也返回维度名称、维度值或命名空间为 CustomCount1 的指标。要进一步构建搜索，您可以指定要在搜索中查找的对象类型的属性名称。以下示例搜索所有命名空间并返回名为 CustomCount1 的指标。

SEARCH(' MetricName="CustomCount1" ', 'Maximum')

您还可以使用命名空间和维度名称/值对作为属性名称，如以下示例所示。这些示例中的第一个还演示了您也可以将属性名称与部分匹配搜索一起使用。

SEARCH(' InstanceType=micro ', 'Average')
SEARCH(' InstanceType="t2.micro" Namespace="AWS/EC2" ', 'Average')

CloudWatch 搜索表达式：非字母数字字符

非字母数字字符用作分隔符，并标记要将指标名称、维度名称、命名空间名称和搜索词分隔成令牌的位置。当词语被令牌化时，非字母数字字符会被剥离掉，不会出现在令牌中。例如，Network-Errors_2 生成令牌 network、errors 和 2。

您的搜索词可以包含任何非字母数字字符。如果这些字符出现在搜索词中，则可以在部分匹配中指定复合令牌。例如，以下所有搜索都将查找名为 Network-Errors-2 或 NetworkErrors2 的指标。

network/errors
network+errors
network-errors
Network_Errors

当您进行精确值搜索时，精确搜索中使用的任何非字母数字字符都必须是出现在要搜索的字符串中的正确字符。例如，如果您要查找 Network-Errors-2，则 "Network-Errors-2" 的搜索成功，但 "Network_Errors_2" 搜索不成功。

执行精确匹配搜索时，必须使用反斜杠转义以下字符。

" \ ( )

例如，要按精确匹配查找指标名称 Europe\France Traffic(Network)，请使用搜索词 "Europe\\France Traffic\(Network\)"

CloudWatch 搜索表达式：布尔运算符

搜索支持在 SearchTerm 中使用布尔运算符 AND、OR 和 NOT。布尔运算符被括在用于将整个搜索词引起来的单引号中。布尔运算符区分大小写，因此 and、or 和 not 作为布尔运算符无效。

您可以在搜索中显式使用 AND，例如 SEARCH('{AWS/EC2,InstanceId} network AND packets', 'Average')。在搜索词之间不使用任何布尔运算符会隐式地搜索它们，就好像存在 AND 运算符，因此 SEARCH(' {AWS/EC2,InstanceId} network packets ', 'Average') 产生相同的搜索结果。

使用 NOT 从结果中排除数据子集。例如，SEARCH(' {AWS/EC2,InstanceId} MetricName="CPUUtilization" NOT i-1234567890123456 ', 'Average') 返回您的所有实例（i-1234567890123456 实例除外）的 CPUUtilization。您还可以使用 NOT 子句作为唯一的搜索词。例如，SEARCH( 'NOT Namespace=AWS ', 'Maximum') 产生所有自定义指标（具有不包括 AWS 的命名空间的指标）。

您可以在一个查询中使用多个 NOT 短语。例如，SEARCH(' {AWS/EC2,InstanceId} MetricName="CPUUtilization" NOT "ProjectA" NOT "ProjectB" ', 'Average') 返回区域中的所有实例（但维度值为 ProjectA 或 ProjectB 的实例除外）的 CPUUtilization。

您可以组合布尔运算符以进行更强大、更详细的搜索，如以下示例所示。使用括号对运算符进行分组。

接下来的两个示例都返回包含 EC2 和 EBS 命名空间中的 ReadOps 的所有指标名称。

SEARCH(' (EC2 OR EBS) AND MetricName=ReadOps ', 'Maximum')
SEARCH(' (EC2 OR EBS) MetricName=ReadOps ', 'Maximum')

以下示例将以前的搜索范围缩小为仅包含 ProjectA 的结果，这可能是维度的值。

SEARCH(' (EC2 OR EBS) AND ReadOps AND ProjectA ', 'Maximum')

以下示例使用嵌套分组。它返回所有函数的 Errors 的 Lambda 指标，以及名称中包含字符串 ProjectA 或 ProjectB 的函数的 Invocations。

SEARCH(' {AWS/Lambda,FunctionName} MetricName="Errors" OR (MetricName="Invocations" AND (ProjectA OR ProjectB)) ', 'Average')

CloudWatch 搜索表达式：使用数学表达式

您可以在图表中的数学表达式内使用搜索表达式。

例如，SUM(SEARCH(' {AWS/Lambda, FunctionName} MetricName="Errors" ', 'Sum')) 返回您的所有 Lambda 函数的 Errors 指标的总和。

对搜索表达式和数学表达式使用单独的行可能会产生更有用的结果。例如，假设您在图表中使用以下两个表达式。第一行显示您的各个 Lambda 函数的单独 Errors 行。该表达式的 ID 为 e1。第二行添加另一行，以显示所有函数的错误总和。

SEARCH(' {AWS/Lambda, FunctionName}, MetricName="Errors" ', 'Sum')
SUM(e1)