add_entries 處理器 copy_values 處理器 delete_entries 處理器 move_keys 處理器平面處理器查詢處理器

轉換處理器

轉換處理器透過新增、複製、移動或移除欄位來修改日誌事件的結構。

add_entries 處理器

將靜態金鑰/值對新增至日誌事件。最多可將 1 個add_entries處理器新增至管道。

組態

使用下列參數設定 add_entries 處理器：


processor:
  - add_entries:
      entries:
        - key: "environment"
          value: "production"
          overwrite_if_key_exists: false

Parameters

entries (必要): 要新增至每個日誌事件的鍵/值對陣列。
entries[].key (必要): 要新增至日誌事件的欄位名稱。支援使用點表示法的巢狀欄位。
entries[].value (必要): 要指派給金鑰的靜態值。
entries[].overwrite_if_key_exists (選用): 決定金鑰已存在時行為的布林值旗標。預設為 false。
when (選用): 處理器層級條件式表達式。指定時，如果表達式評估為 false，則會略過整個處理器。長度上限為 256 個字元。請參閱條件式處理的表達式語法。
entries[].when (選用): 入門級條件式表達式。指定時，如果表達式評估為 false，則只會略過此項目。長度上限為 256 個字元。請參閱條件式處理的表達式語法。
entries[].when_else (選用): 只有在相同處理器中沒有其他when條件相符時，才會執行的備用項目。表達式值可識別要考慮when的條件。長度上限為 256 個字元。請參閱條件式處理的表達式語法。

copy_values 處理器

將值從一個欄位複製到另一個欄位。最多可將 1 個copy_values處理器新增至管道。

組態

使用下列參數設定 copy_values 處理器：


processor:
  - copy_values:
      entries:
        - from_key: "user_id"
          to_key: "backup_user"
          overwrite_if_to_key_exists: false

Parameters

entries (必要): 在每個日誌事件上執行的複製操作陣列。
entries[].from_key (必要): 要從中複製值的欄位名稱。將點表示法用於巢狀欄位。
entries[].to_key (必要): 要複製值的欄位名稱。如果使用點表示法，則會建立巢狀結構。
entries[].overwrite_if_to_key_exists (選用): 當目標欄位已存在時，控制行為的布林值旗標。預設為 false。
when (選用): 處理器層級條件式表達式。指定時，如果表達式評估為 false，則會略過整個處理器。長度上限為 256 個字元。請參閱條件式處理的表達式語法。
entries[].when (選用): 入門級條件式表達式。指定時，如果表達式評估為 false，則只會略過此項目。長度上限為 256 個字元。請參閱條件式處理的表達式語法。
entries[].when_else (選用): 只有在相同處理器中沒有其他when條件相符時，才會執行的備用項目。表達式值可識別要考慮when的條件。長度上限為 256 個字元。請參閱條件式處理的表達式語法。

delete_entries 處理器

從日誌事件中移除指定的欄位。

組態

使用下列參數設定 delete_entries 處理器：


processor:
  - delete_entries:
      with_keys: ["temp_field", "debug_info"]

Parameters

with_keys (必要): 要從每個日誌事件中移除的欄位名稱陣列。支援使用點符號刪除巢狀欄位。
when (選用): 決定此處理器是否執行的條件式表達式。長度上限為 256 個字元。請參閱條件式處理的表達式語法。

move_keys 處理器

將欄位從一個位置移至另一個位置。

組態

使用下列參數設定 move_keys 處理器：


processor:
  - move_keys:
      entries:
        - from_key: "old_field"
          to_key: "new_field"
          overwrite_if_to_key_exists: true

Parameters

entries (必要): 移動操作陣列。最多 5 個項目。
entries[].from_key (必要): 來源欄位名稱。最多 128 個字元。
entries[].to_key (必要): 目標欄位名稱。最多 128 個字元。
entries[].overwrite_if_to_key_exists (選用): 是否覆寫現有的目標欄位。
when (選用): 處理器層級條件式表達式。指定時，如果表達式評估為 false，則會略過整個處理器。長度上限為 256 個字元。請參閱條件式處理的表達式語法。
entries[].when (選用): 入門級條件式表達式。指定時，如果表達式評估為 false，則只會略過此項目。長度上限為 256 個字元。請參閱條件式處理的表達式語法。
entries[].when_else (選用): 只有在相同處理器中沒有其他when條件相符時，才會執行的備用項目。表達式值可識別要考慮when的條件。長度上限為 256 個字元。請參閱條件式處理的表達式語法。

平面處理器

扁平化巢狀物件結構。

組態

使用下列參數設定平面處理器：


processor:
  - flatten:
      source: "metadata"
      target: "flattened"
      remove_processed_fields: true
      exclude_keys: ["sensitive_data"]

Parameters

source (必要): 包含要扁平化之巢狀物件的欄位。
target (必要): 扁平化金鑰的目標欄位字首。
remove_processed_fields (選用): 是否在平面化後移除原始巢狀欄位。
exclude_keys (選用): 要從平面化中排除的索引鍵陣列。最多 20 個金鑰，每個最多 128 個字元。
when (選用): 決定此處理器是否執行的條件式表達式。長度上限為 256 個字元。請參閱條件式處理的表達式語法。

查詢處理器

使用來自 CloudWatch Logs 查詢資料表的資料來豐富日誌事件。處理器會將日誌事件中的欄位與查詢資料表中的欄位進行比對，並將指定的欄位附加至日誌事件。將此處理器用於資料擴充案例，例如將使用者 IDs映射至使用者詳細資訊、將產品代碼映射至產品資訊，或將錯誤代碼映射至錯誤描述。最多可將 1 個lookup處理器新增至管道。

注意

如果在管道中使用查詢資料表，您必須為執行角色提供資料表的logs:GetLookupTable許可。如需詳細資訊，請參閱CloudWatch 管道 IAM 政策和許可。

組態

使用下列參數設定查詢處理器：


processor:
  - lookup:
      lookup_table: "arn:aws:logs:us-east-1:123456789012:lookup-table:my_lookup_table"
      match_keys:
        - log_key: "src_ip"
          lookup_key: "ip_address"
      entries:
        - source: "hostname"
          target: "src_hostname"
          overwrite_if_exists: true

Parameters

lookup_table (必要): 用於擴充的 CloudWatch Logs 查詢資料表 ARN。長度上限為 2048 個字元。
match_keys (必要): 金鑰對陣列，定義如何比對日誌事件欄位以查詢資料表欄位。最少 1 個，最多 5 個相符金鑰。指定多個相符索引鍵時，查詢資料表資料列必須符合所有索引鍵才能產生結果 (AND 邏輯）。
match_keys[].log_key (必要): 日誌事件中要比對的欄位名稱。最多 128 個字元。
match_keys[].lookup_key (必要): 要比對之查詢資料表中的資料欄名稱。最多 128 個字元。
entries (必要): 要從相符查詢資料表資料列新增至日誌事件的欄位陣列。最少 1 個，最多 10 個項目。
entries[].source (必要): 查詢資料表中要從中擷取值的資料欄名稱。最多 128 個字元。
entries[].target (選用): 要新增至日誌事件的欄位名稱。如果未指定，資料source欄名稱會用作欄位名稱。最多 128 個字元。
entries[].overwrite_if_exists (選用): 布林值旗標，決定目標欄位在日誌事件中已存在時的行為。預設為 false。
when (選用): 決定此處理器是否執行的條件式表達式。長度上限為 256 個字元。請參閱條件式處理的表達式語法。

範例

考慮network_assets使用下列資料列命名為的查詢資料表：

network_assets 查詢資料表
ip_address	hostname	owner	location
10.0.1.12	Web-server-01	team-alpha	us-east-1
10.0.2.45	db-server-03	team-beta	us-west-2
10.0.3.78	cache-node-07	team-alpha	eu-west-1

根據下列日誌事件：


{
  "timestamp": "2026-05-04T12:00:00Z",
  "src_ip": "10.0.2.45",
  "action": "connection_opened",
  "bytes": 2048
}

以及下列處理器組態：


processor:
  - lookup:
      lookup_table: "arn:aws:logs:us-east-1:123456789012:lookup-table:network_assets"
      match_keys:
        - log_key: "src_ip"
          lookup_key: "ip_address"
      entries:
        - source: "hostname"
          target: "src_hostname"
        - source: "owner"
        - source: "location"
          target: "src_region"
          overwrite_if_exists: false

處理器會產生下列豐富的日誌事件：


{
  "timestamp": "2026-05-04T12:00:00Z",
  "src_ip": "10.0.2.45",
  "action": "connection_opened",
  "bytes": 2048,
  "src_hostname": "db-server-03",
  "owner": "team-beta",
  "src_region": "us-west-2"
}

IAM 許可

當管道使用查詢處理器時，管道的執行角色必須包含參考資料表的logs:GetLookupTable許可。下列範例政策陳述式會授予此許可：


{
  "Effect": "Allow",
  "Action": "logs:GetLookupTable",
  "Resource": "arn:aws:logs:<region>:<account-id>:lookup-table:<table-name>"
}

文件慣用形式

剖析器處理器

字串操作處理器