From 64b28603f6b410f3e967eb22b87b4ad7d0c00e7f Mon Sep 17 00:00:00 2001 From: Alex Date: Wed, 7 Feb 2024 12:42:18 +0100 Subject: [PATCH 1/4] docs: add 'inserting hosts' section in docs --- docs/host_limit.rst | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/docs/host_limit.rst b/docs/host_limit.rst index 95c14be7..a07a068e 100644 --- a/docs/host_limit.rst +++ b/docs/host_limit.rst @@ -17,3 +17,26 @@ Event data example: The value for "hosts" can be a comma delimited string of multiple host names, but typically it is a single host. This is useful to restrict a remedy playbook to run only on the problematical host that emits a monitored event. Be sure that the source plugin already sends this metadata. + + +Inserting hosts to meta +----------------------- + +The plugins may not send metadata like for example the `ansible.eda.webhook` plugin which +sends the arbitrary payload under the `payload` key. + +To accommodate this, the EDA collection provides the `insert_hosts_to_meta` filter, +allowing any plugin to customize the value of `event.meta.hosts` based on the contents +of a specific key in the event. + +Example: + +.. code-block:: yaml + + sources: + - ansible.eda.webhook: + port: 4444 + host: 0.0.0.0 + filters: + - ansible.eda.insert_hosts_to_meta: + host_path: "payload.alert.instances" From 35d23e8377667305a2780319125671e2599e291b Mon Sep 17 00:00:00 2001 From: Alex Date: Thu, 15 Feb 2024 13:39:49 +0100 Subject: [PATCH 2/4] docs: add clarification and add filter in the filters list --- docs/filters.rst | 16 +++++++++++++++- docs/host_limit.rst | 6 ++++++ 2 files changed, 21 insertions(+), 1 deletion(-) diff --git a/docs/filters.rst b/docs/filters.rst index 2ad7c8ce..17e8b68b 100644 --- a/docs/filters.rst +++ b/docs/filters.rst @@ -22,6 +22,9 @@ Event Filters - Include and exclude keys from the event object * - dashes_to_underscores - This filter changes the dashes in all keys in the payload to be underscore. + * - insert_hosts_to_meta + - This filter inserts the hosts from the event into the meta key within the event + based on a custom path in the event object. | Events filters can be chained one after the other, and the updated data is | sent from one filter to the next. @@ -30,7 +33,7 @@ Event Filters | When the rulebook starts the Source plugin it associates the correct filters | and transforms the data before putting it into the queue. -e.g. +Examples: .. code-block:: yaml @@ -45,6 +48,17 @@ e.g. exclude_keys: ['*_url', '_links', 'base', 'sender', 'owner', 'user'] - dashes_to_underscores: + +.. code-block:: yaml + + sources: + - foo.bar.my_custom_source: + url: https://my_custom_source.com + filters: + - ansible.eda.insert_hosts_to_meta: + host_path: "alert.meta.instances" + + | In the above example the data is first passed thru the json_filter and then | thru the dashes_to_underscores filter. | Keys in the event payload can only contain letters, numbers and underscores. diff --git a/docs/host_limit.rst b/docs/host_limit.rst index a07a068e..8e9040e6 100644 --- a/docs/host_limit.rst +++ b/docs/host_limit.rst @@ -29,6 +29,12 @@ To accommodate this, the EDA collection provides the `insert_hosts_to_meta` filt allowing any plugin to customize the value of `event.meta.hosts` based on the contents of a specific key in the event. +.. note:: + + The `host_path` in filter `insert_hosts_to_meta` don't expect the `event` root key unlike conditions + or action arguments and it won't take action if the `host_path` is not found in the event. + + Example: .. code-block:: yaml From 5b0a6ddc5c10f53e5d313f079f4e536249a45588 Mon Sep 17 00:00:00 2001 From: Alex Date: Fri, 16 Feb 2024 16:39:29 +0100 Subject: [PATCH 3/4] chore: fix --- docs/filters.rst | 11 ----------- 1 file changed, 11 deletions(-) diff --git a/docs/filters.rst b/docs/filters.rst index 17e8b68b..d8010c20 100644 --- a/docs/filters.rst +++ b/docs/filters.rst @@ -48,17 +48,6 @@ Examples: exclude_keys: ['*_url', '_links', 'base', 'sender', 'owner', 'user'] - dashes_to_underscores: - -.. code-block:: yaml - - sources: - - foo.bar.my_custom_source: - url: https://my_custom_source.com - filters: - - ansible.eda.insert_hosts_to_meta: - host_path: "alert.meta.instances" - - | In the above example the data is first passed thru the json_filter and then | thru the dashes_to_underscores filter. | Keys in the event payload can only contain letters, numbers and underscores. From 9af9187ae9e30bdd3fa98cc33193ee8a688be8d9 Mon Sep 17 00:00:00 2001 From: Alex Date: Mon, 19 Feb 2024 23:09:22 +0100 Subject: [PATCH 4/4] docs: add changes as per suggestions --- docs/host_limit.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/host_limit.rst b/docs/host_limit.rst index 8e9040e6..6ef5670b 100644 --- a/docs/host_limit.rst +++ b/docs/host_limit.rst @@ -31,8 +31,8 @@ of a specific key in the event. .. note:: - The `host_path` in filter `insert_hosts_to_meta` don't expect the `event` root key unlike conditions - or action arguments and it won't take action if the `host_path` is not found in the event. + The host_path argument in the filter `insert_hosts_to_meta` does not need the `event.` prefix + like conditions or action arguments. Example: @@ -42,7 +42,6 @@ Example: sources: - ansible.eda.webhook: port: 4444 - host: 0.0.0.0 filters: - ansible.eda.insert_hosts_to_meta: host_path: "payload.alert.instances"