View a markdown version of this page

条件付き処理の式構文 - Amazon CloudWatch
プロセッサレベルとエントリレベルの条件条件付き処理のサポートオペレータ関数式の例制限事項

条件付き処理の式構文

条件付き処理をサポートしている CloudWatch パイプラインプロセッサは、式を含む when パラメータを受け入れます。式が true と評価されると、プロセッサまたはエントリが実行されます。式は、ネストされたフィールドアクセスにドット表記 (.) を使用します。例えば、user.role は user オブジェクト内の roleフィールドにアクセスします。条件付き処理をサポートしているプロセッサとその特定のパラメータの詳細については、「CloudWatch パイプラインプロセッサ」を参照してください。設定の例については、「プロセッサの一般的なユースケース」を参照してください。

プロセッサレベルとエントリレベルの条件

プロセッサに応じて、when 条件を適用できるレベルは 2 つあります。

プロセッサレベル when (外部レベル)

プロセッサ設定の最上位にある when。式が false と評価された場合、プロセッサ全体がスキップされ、プロセッサ内のオペレーションは実行されません。条件付き処理をサポートしているすべてのプロセッサは、このレベルをサポートします。

例プロセッサレベルの条件 — プロセッサ全体をスキップする

次の delete_entries プロセッサは、環境が本番環境またはステージングの場合にのみ実行されます。条件が false の場合、どのキーも削除されません。

processor:
  - delete_entries:
      with_keys: ["password", "api_key", "ssn"]
      when: "environment in {'prod', 'staging'}"
エントリレベル when (各エントリ内)

entries 配列内の個々のエントリ内にある when。各エントリは個別に評価されます — 式が false の場合、その特定のエントリのみがスキップされ、同じプロセッサ内の他のエントリは引き続き実行されます。entries 配列を持つプロセッサのみが、このレベル (add_entries、copy_values、rename_keys、move_keys、extract_value、substitute_string など) をサポートします。

例エントリレベルの条件 — 個々のエントリをスキップする

次の add_entries プロセッサは、各エントリの条件に応じて異なるキーを追加します。最初のエントリは、ログレベルが ERROR の場合にのみ severity を追加します。2 番目のエントリは条件がないため、それは常に 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 の場合に実行されます。2 番目のエントリは、when_else を使用して、最初のエントリの when 条件が一致しない場合 (つまり、ログレベルが 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はいプロセッサとエントリ
切り詰めはいプロセッサ
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 文字です。

  • パーサープロセッサ (Grok を除く) は条件付き処理をサポートしていません。これには、JSON、CSV、KeyValue、WAF、Postgres、CloudFront、VPC、Route53、および OCSF パーサーが含まれます。

  • Grok プロセッサをパイプラインのパーサー (最初のプロセッサ) として使用し、その when 条件が false と評価された場合、パイプライン全体がそのログイベントに対して実行されません。