View a markdown version of this page

条件处理的表达式语法 - Amazon CloudWatch
处理器级和条目级条件条件处理支持运算符函数表达式示例限制

条件处理的表达式语法

支持条件处理的 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，则不会针对该日志事件执行整个管道。