事件过滤器

事件过滤器提供了一种灵活的方式，在事件数据被规则引擎评估之前
对其进行预处理。您可以使用它们来删除不必要的信息，以及
修改、丰富或转换事件的内容和结构。这确保了
数据处于最适合您的规则条件的格式。

事件被定义为 Python 代码并以集合（collections）的形式分发。

为了帮助用户快速上手，我们已经提供了包含一组常用过滤器的 `ansible.eda` 集合。

您可以在此处浏览该集合： https://galaxy.ansible.com/ui/repo/published/ansible/eda/content/

事件过滤器可以一个接一个地链接在一起，更新后的数据将

从一个过滤器发送到下一个过滤器。

事件过滤器在 rulebook 中定义在源（source）定义之后。
当 rulebook 启动源插件时，它会关联正确的过滤器
并在将数据放入队列之前对其进行转换。

示例

sources:
  - name: azure_service_bus
    ansible.eda.azure_service_bus:
      conn_str: "{{connection_str}}"
      queue_name: "{{queue_name}}"
    filters:
      - json_filter:
          include_keys: ['clone_url']
          exclude_keys: ['*_url', '_links', 'base', 'sender', 'owner', 'user']
      - dashes_to_underscores:

在上述示例中，数据首先通过 json_filter，然后
通过 dashes_to_underscores 过滤器。
事件负载中的键（Keys）只能包含字母、数字和下划线。
点号 (.) 用于访问嵌套键。

在开发新过滤器时，您可以使用 -F 来指定
过滤器所在的目录。当您使用决策环境（decision environment）时，此方法将不起作用，
您必须通过集合来分发过滤器。

内置事件过滤器

ansible-rulebook 提供了以下内置事件过滤器

eda.builtin.insert_meta_info
eda.builtin.event_splitter
eda.builtin.dashes_to_underscores
eda.builtin.json_filter
eda.builtin.normalize_keys
eda.builtin.insert_hosts_to_meta

eda.builtin.insert_meta_info

由于每个事件都应记录事件的来源，因此我们提供了一个过滤器
eda.builtin.insert_meta_info，它将由 ansible-rulebook 自动添加，
以添加源名称、类型和接收时间（received_at）。
received_at 存储 UTC ISO8601 格式的日期时间，并包括
微秒。
uuid 存储事件的唯一 ID。
事件负载将被修改以包含以下数据

event = { ..., 'meta': {'source': {'name': 'azure_service_bus',
                                   'type': 'ansible.eda.azure_service_bus'},
                        'received_at': '2023-03-23T19:11:15.802274Z',
                        'uuid': 'eb7de03f-6f8f-4943-b69e-3c90db346edf'}
        }

meta 键用于存储关于事件的元数据，这对于

在 aap-server 中正确报告事件是必需的。

eda.builtin.event_splitter

如果传入的事件负载中封装了多个事件，我们可以
使用 eda.builtin.event_splitter 过滤器将这些事件拆分为单个事件。
这在 Big Panda 和 Prometheus 警报中非常常见。
该过滤器接受 4 个参数

Name	描述	必填
splitter_key	存储事件数组的嵌套键。您可以使用点分隔符来指定路径，例如 incident.alerts	是
attribute_key_map	如果您需要将父节点的额外属性添加到事件中，请将其指定为字典	否
extras	如果您需要向事件中添加静态属性，请将其指定为字典	否
raise_error	true 或 false。如果 splitter_key 缺失，我们可以通过将 raise_error 设置为 true 来停止源。默认为 false，如果 splitter_key 缺失，我们将原样返回事件。	否

示例

sources:
  - name: my_prometheus
    ansible.eda.alertmanager:
       ...
    filters:
      - eda.builtin.event_splitter:
          splitter_key: alerts
          attributes_key_map:
            header: header
            hosts: labels.instance
          extras:
            region: us-east

sources:
  - name: my_bigpanda
    ...big_panda...:
       ...
    filters:
      - eda.builtin.event_splitter:
          splitter_key: incident.alerts
          attributes_key_map:
             id: incident.id
             active: incident.active
             severity: incident.severity
             status: incident.status
             environments: incident.environments

eda.builtin.dashes_to_underscores

将事件键中的连字符（-）更改为下划线（_）。例如，键 server-name 变为 server_name。该过滤器递归处理所有字典键，包括嵌套在列表中的键。它接受一个参数

Name	描述	必填
overwrite	如果在将连字符转换为下划线时发生键冲突，则覆盖值。默认值：true	否

示例

sources:
  - name: my_webhook
    eda.builtin.webhook:
      host: 0.0.0.0
      port: 5000
    filters:
      - eda.builtin.dashes_to_underscores:
          overwrite: false

# Input event
{
  "server-name": "web01",
  "app-version": "1.0"
}

# Output event
{
  "server_name": "web01",
  "app_version": "1.0"
}

eda.builtin.json_filter

根据包含/排除模式过滤事件中的键。include_keys 参数可防止键被排除（它不充当白名单）。包含模式会覆盖排除模式。

Name	描述	必填
exclude_keys	要删除的键模式列表（支持 `*` 和 `?` 等通配符）	否
include_keys	即使匹配排除模式也要保留的键模式列表	否

示例

sources:
  - name: my_source
    eda.builtin.webhook:
      host: 0.0.0.0
      port: 5000
    filters:
      - eda.builtin.json_filter:
          exclude_keys:
            - 'metadata'
            - 'internal_*'
          include_keys:
            - 'internal_id'

# Input event
{
  "data": "important",
  "metadata": "remove",
  "internal_debug": "remove",
  "internal_id": "keep"
}

# Output event (internal_id kept despite matching internal_*)
{
  "data": "important",
  "internal_id": "keep"
}

eda.builtin.normalize_keys

通过将非字母数字字符替换为下划线来规范化键。连续的特殊字符将合并为一个下划线。例如，server.name 变为 server_name，而 server--name 变为 server_name。

Name	描述	必填
overwrite	如果在规范化后发生键冲突，则覆盖值。默认值：true	否

示例

sources:
  - name: my_source
    eda.builtin.webhook:
      host: 0.0.0.0
      port: 5000
    filters:
      - eda.builtin.normalize_keys:

# Input event
{
  "server.name": "web01",
  "app@version": "1.0",
  "data--key": "value"
}

# Output event
{
  "server_name": "web01",
  "app_version": "1.0",
  "data_key": "value"
}

eda.builtin.insert_hosts_to_meta

从事件数据中提取主机并将其插入到 meta 字典中。在 ansible-rulebook 中，这将限制操作仅在 meta 字典中指定的主机上运行。

Name	描述	必填
host_path	事件数据中用于查找主机的 JSON 路径（使用点号表示法）	是
path_separator	用于解析 host_path 的分隔符。默认值：“.”	否
host_separator	如果主机字符串包含多个主机，则用于拆分主机的分隔符	否
raise_error	如果 host_path 不存在则抛出错误。建议在开发时使用。默认值：false	否
log_error	如果 host_path 不存在则记录错误。默认值：true	否

示例

sources:
  - name: my_alertmanager
    ansible.eda.alertmanager:
      host: 0.0.0.0
      port: 5050
    filters:
      - eda.builtin.insert_hosts_to_meta:
          host_path: "alert.target"
          path_separator: "."
          raise_error: true

# Input event
{
  "alert": {
    "target": "server1.example.com",
    "severity": "critical"
  }
}

# Output event
{
  "alert": {
    "target": "server1.example.com",
    "severity": "critical"
  },
  "meta": {
    "hosts": ["server1.example.com"]
  }
}