add_entries 处理器 copy_values 处理器 delete_entries 处理器 move_keys 处理器 flatten 处理器查找处理器 geoip 处理器

转换处理器

转换处理器通过添加、复制、移动或移除字段来修改日志事件的结构。

add_entries 处理器

向日志事件添加静态键值对。一个管道最多可以添加 1 个 add_entries 处理器。

配置

使用以下参数配置 add_entries 处理器：


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

参数

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

参数

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_entris 处理器：


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

参数

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

参数

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 个字符。请参阅条件处理的表达式语法。

flatten 处理器

展平嵌套对象结构。

配置

使用以下参数配置 flatten 处理器：


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

参数

source（必需）: 包含要展平的嵌套对象的字段。
target（必需）: 展平密钥的目标字段前缀。
remove_processed_fields（可选）: 展平后是否移除原始嵌套字段。
exclude_keys（可选）: 要从展平中排除的键数组。最多 20 个键，每个键最多可包含 128 个字符。
when（可选）: 用于确定此处理器是否执行的条件表达式。最大长度为 256 个字符。请参阅条件处理的表达式语法。

查找处理器

使用 CloudWatch Logs 查找表中的数据充实日志事件。处理器将您的日志事件中的字段与查找表中的字段进行匹配，并将指定的字段附加到您的日志事件中。此处理器用于数据充实场景，例如将用户 ID 映射到用户详细信息，将产品代码映射到产品信息，或者将错误代码映射到错误描述。一个管道最多可以添加 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

参数

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	地点
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>"
}

geoip 处理器

geoip 处理器基于 IP 地址通过地理位置数据丰富日志事件。处理器使用 MaxMind 数据库将 IP 地址解析为地理信息，例如城市、国家、大洲、坐标和自治系统编号（ASN）详细信息。针对网络流量分析、用户位置丰富和安全调查场景使用此处理器。

配置

使用以下参数配置 geoip 处理器：


processor:
  - geoip:
      entries:
        - source: "client_ip"
          target: "client_geo"
          include_fields:
            - "city_name"
            - "country_name"
            - "country_iso_code"
            - "continent_name"
            - "latitude"
            - "longitude"
          when: '.client_ip != "127.0.0.1"'

参数

entries（必需）

定义要使用地理数据丰富哪些 IP 字段的条目对象数组。最少 1 个，最多 10 个条目。

entries[].source（必需）

日志事件中包含要查找的 IP 地址的字段名称。必须引用有效的 IPv4 或 IPv6 地址。最多 128 个字符。

entries[].target（必需）

处理器在日志事件中写入地理丰富数据的字段名称。最多 128 个字符。

entries[].include_fields（必需）

要包括在丰富结果中的地理字段数组。最少 1 个，最多 12 个字段。以下字段可用：

continent_code：两个字母的大洲代码（例如“NA”）。
continent_name：大洲的名称（例如“北美”）。
country_name：国家或地区的名称（例如“美国”）。
country_iso_code：ISO 3166-1 alpha-2 国家或地区（例如“US”）。
city_name：城市名称（例如“西雅图”）。
postal_code：与 IP 地址位置关联的邮政编码。
time_zone：IANA 时区名称（例如“America/Los_Angeles”）。
latitude：IP 地址位置的纬度坐标。
longitude：IP 地址位置的经度坐标。
network：与 IP 地址关联的网络的 CIDR 表示法。
asn：与 IP 地址关联的自治系统编号。
asn_organization：与自治系统编号关联的组织名称。

entries[].when（可选）

决定此条目是否执行的条件表达式。最大长度为 256 个字符。请参阅条件处理的表达式语法。

when（可选）

决定此处理器是否执行的顶级条件表达式。最大长度为 256 个字符。请参阅条件处理的表达式语法。

示例

以下示例展示了一个包含 IP 地址字段的示例日志事件：


{
  "timestamp": "2026-05-04T12:00:00Z",
  "src_ip": "203.0.113.50",
  "dst_ip": "198.51.100.25",
  "action": "ALLOW",
  "bytes": 4096
}

以下处理器配置将源 IP 字段和目标 IP 字段映射到地理丰富目标：


processor:
  - geoip:
      entries:
        - source: "src_ip"
          target: "src_geo"
          include_fields:
            - "city_name"
            - "country_name"
            - "country_iso_code"
            - "latitude"
            - "longitude"
            - "asn"
            - "asn_organization"
        - source: "dst_ip"
          target: "dst_geo"
          include_fields:
            - "country_name"
            - "country_iso_code"

处理器生成以下充实日志事件：


{
  "timestamp": "2026-05-04T12:00:00Z",
  "src_ip": "203.0.113.50",
  "dst_ip": "198.51.100.25",
  "action": "ALLOW",
  "bytes": 4096,
  "src_geo": {
    "city_name": "Seattle",
    "country_name": "United States",
    "country_iso_code": "US",
    "latitude": 47.6062,
    "longitude": -122.3321,
    "asn": 16509,
    "asn_organization": "Amazon.com, Inc."
  },
  "dst_geo": {
    "country_name": "Germany",
    "country_iso_code": "DE"
  }
}

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

解析器处理器

字符串操作处理器