View a markdown version of this page

條件式處理的表達式語法 - Amazon CloudWatch
處理器層級和入門層級條件條件式處理支援運算子函數表達式範例限制

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

條件式處理的表達式語法

支援條件式處理的 CloudWatch 管道處理器接受包含表達式的when參數。當表達式評估為 true 時，處理器或項目會執行。表達式使用點符號 (.) 進行巢狀欄位存取。例如， 會user.role存取 user 物件內的 role 欄位。如需支援條件式處理的處理器及其特定參數的詳細資訊，請參閱 CloudWatch 管道處理器。如需組態範例，請參閱 常見的處理器使用案例。

注意

條件式處理僅適用於日誌管道。指標管道不支援 when 參數。

處理器層級和入門層級條件

您可以套用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的條件不相符時 （即日誌層級是 ERROR 以外的任何項目），才會使用 when_else和 執行。

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

條件式處理支援

下表顯示哪些處理器支援條件式處理和哪個層級。

處理器條件式支援
處理器 條件式支援 Level
add_entries是處理器和項目
copy_values是處理器和項目
delete_entries是處理器
move_keys是處理器和項目
flatten是處理器
lowercase_string是處理器
uppercase_string是處理器
trim_string是處理器
substitute_string是處理器和項目
截斷是處理器
extract_value是處理器和項目
convert_entry_type是處理器
date是處理器
剖析是處理器
list_to_map是處理器
rename_keys是處理器和項目
select_entries是處理器
translate是處理器
grok是處理器
drop_events是處理器 （必要）
OCSF、CSV、JSON、KeyValue、WAF、Postgres、CloudFront、VPC、Route53否—

運算子

支援的運算子
Category 運算子 範例
關聯式 <, <=, >, >= 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"}
Regex 比對 =~, !~ 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 個字元。

  • Parser 處理器 (Grok 除外） 不支援條件式處理。這包括 JSON、CSV、KeyValue、WAF、Postgres、CloudFront、VPC、Route53 和 OCSF 剖析器。

  • 如果在管道中使用 Grok 處理器做為剖析器 （第一個處理器），且其when條件評估為 false，則整個管道不會針對該日誌事件執行。