View a markdown version of this page

条件处理的表达式语法 - Amazon CloudWatch
处理器级和条目级条件条件处理支持运算符函数表达式示例限制
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

条件处理的表达式语法

支持条件处理的 CloudWatch 管道处理器接受包含表达式的 when 参数。如果表达式的计算结果为 true，则执行处理器或条目。表达式使用点符号 (.) 来访问嵌套字段。例如，user.role 访问 user 对象内部的 role 字段。有关支持条件处理的处理器及其特定参数的更多详细信息，请参阅CloudWatch 管道处理器。有关配置示例，请参阅常见处理器使用案例。

处理器级和条目级条件

根据处理器的不同，可以在两个级别应用 when 条件。

处理器级 when（外部级别）

when 位于处理器配置的顶层。如果该表达式的计算结果为 false，则跳过整个处理器并且不会执行其中的任何操作。所有支持条件处理的处理器都支持此级别。

例处理器级条件：跳过整个处理器

以下 delete_entries 处理器仅在生产环境或暂存环境中运行。如果条件为 false，则不删除任何密钥。

processor:
  - delete_entries:
      with_keys: ["password", "api_key", "ssn"]
      when: "environment in {'prod', 'staging'}"
条目级 when（在每个条目中）

when 位于 entries 数组中单个条目内。每个条目均经过独立评估：如果表达式为 false，则仅跳过该特定条目，而同一处理器中的其他条目仍会执行。只有具有 entries 数组的处理器支持此级别（例如 add_entries、copy_values、rename_keys、move_keys、extract_value 和 substitute_string）。

例条目级条件：跳过单个条目

以下 add_entries 处理器根据每个条目的条件添加不同的密钥。仅当日志级别为 ERROR 时，第一个条目才会添加 severity。第二个条目总是添加 processed，因为它没有条件。

processor:
  - add_entries:
      entries:
        - key: "severity"
          value: "high"
          when: "log.level == 'ERROR'"
        - key: "processed"
          value: "true"

支持这两个级别的处理器可将它们一起使用。如果同时指定了两者，则首先评估处理器级条件。如果为 false，则跳过整个处理器，并且不评估条目级条件。

例两个级别相结合

处理器级 when 可确保整个处理器仅针对生产流量运行。其中，每个条目都有自己的条件来控制添加哪个密钥。

processor:
  - add_entries:
      when: "environment == 'prod'"
      entries:
        - key: "alert_level"
          value: "critical"
          when: "log.level == 'ERROR'"
        - key: "alert_level"
          value: "warning"
          when: "log.level == 'WARN'"

有关显示哪些处理器支持哪个级别的表格，请参阅以下条件处理支持一节。

通过 when_else 回退

支持条目级条件的处理器也支持 when_else。带有 when_else 的条目充当回退选项：仅当同一处理器中的其他 when 条件都不匹配时，它才会执行。提供给 when_else 的表达式值用于标识要考虑哪组 when 条件，但条目本身仅根据这些条件的计算结果是否都为 false 来运行。没有显式否定检查：该条目只是在没有其他 when 匹配项时运行。

例带有 when_else 的回退条目

第一个条目在日志级别为 ERROR 时运行。第二个条目仅在第一个条目的 when 条件不匹配时才使用 when_else 和运行（即，日志级别是除 ERROR 以外的项目）。

processor:
  - add_entries:
      entries:
        - key: "alert_level"
          value: "critical"
          when: "log.level == 'ERROR'"
        - key: "alert_level"
          value: "info"
          when_else: "log.level == 'ERROR'"

条件处理支持

下表显示了哪些处理器支持条件处理以及支持哪个级别。

处理器条件支持
处理器 条件支持 级别
add_entries是处理器和条目
copy_values是处理器和条目
delete_entries是处理器
move_keys是处理器和条目
flatten是处理器
lowercase_string是处理器
uppercase_string是处理器
trim_string是处理器
substitute_string是处理器和条目
truncate是处理器
extract_value是处理器和条目
convert_entry_type是处理器
date是处理器
dissect是处理器
list_to_map是处理器
rename_keys是处理器和条目
select_entries是处理器
翻译是处理器
grok是处理器
drop_events是处理器（必填）
OCSF、CSV、JSON、KeyValue、WAF、Postgres、CloudFront、VPC、Route53否—

运算符

支持的运算符
类别 运算符 示例
关系 <, <=, >, >= status_code >= 200 and status_code < 300
等于 ==, != log.level == "ERROR"
有条件 and, or, not log.level == "ERROR" or log.level == "FATAL"
算术 +, -, *, / response_time * 1000 > 5000
设置成员资格 in, not in environment in {"prod", "staging", "preprod"}
正则表达式匹配 =~, !~ message =~ "^ERROR.*timeout"

函数

length(value)

返回字符串或数组的长度。示例：length(message) > 100

contains(value, search)

检查字符串是否包含子字符串或数组是否包含元素。示例：contains(message, "error")

startsWith(field, prefix)

检查字符串是否以指定的前缀开头。示例：startsWith(message, "ERROR")

表达式示例

log.level == "ERROR"
status_code >= 200 and status_code < 300
environment in {"prod", "staging", "preprod"}
message =~ "^ERROR.*timeout"
user.role == "admin" and user.permissions.write == true
length(message) > 100 and contains(message, "error")
(log.level == "ERROR" or log.level == "FATAL") and environment == "prod"

限制

  • 表达式最大长度为 256 个字符。

  • 解析器处理器（Grok 除外）不支持条件处理。这包括 JSON、CSV、KeyValue、WAF、Postgres、CloudFront、VPC、Route53 和 OCSF 解析器。

  • 如果将 Grok 处理器用作管道中的解析器（第一个处理器），并且其 when 条件的计算结果为 false，则不会针对该日志事件执行整个管道。