diff --git a/.config/dictionary.txt b/.config/dictionary.txt index 92c1acaf..511135eb 100644 --- a/.config/dictionary.txt +++ b/.config/dictionary.txt @@ -5,6 +5,7 @@ AUTHS Abhijeet Alina Buzachis +Doston EDAHTTP FQCN GSSAPI @@ -13,6 +14,7 @@ Nikhil OAUTHBEARER PYTHONUNBUFFERED Passw +Toirov akasurde alertmanager alinabuzachis @@ -34,6 +36,7 @@ darglint deadsnakes digestmod docsite +dtoirov dynatrace envlist extfile diff --git a/extensions/eda/plugins/event_filter/dashes_to_underscores.py b/extensions/eda/plugins/event_filter/dashes_to_underscores.py index fa70d7c7..e170b68a 100644 --- a/extensions/eda/plugins/event_filter/dashes_to_underscores.py +++ b/extensions/eda/plugins/event_filter/dashes_to_underscores.py @@ -1,12 +1,16 @@ -"""dashes_to_underscores.py. - - An event filter that changes dashes in keys to underscores. - For instance, the key X-Y becomes the new key X_Y. - -Arguments: ---------- - * overwrite: Overwrite the values if there is a collision with a new key. - +DOCUMENTATION = r""" +--- +author: + - Doston Toirov (@dtoirov) +short_description: Change dashes to underscores. +description: + - An event filter that changes dashes in keys to underscores. For instance, the key X-Y becomes the new key X_Y. +options: + overwrite: + description: + - Overwrite the values if there is a collision with a new key. + type: bool + default: true """ import multiprocessing as mp diff --git a/extensions/eda/plugins/event_filter/insert_hosts_to_meta.py b/extensions/eda/plugins/event_filter/insert_hosts_to_meta.py index d6ce65ff..3d05eb0e 100644 --- a/extensions/eda/plugins/event_filter/insert_hosts_to_meta.py +++ b/extensions/eda/plugins/event_filter/insert_hosts_to_meta.py @@ -1,38 +1,59 @@ -"""insert_hosts_to_meta.py. - -An ansible-rulebook event filter that extract hosts from the event data and -insert them to the meta dict. Ansible-rulebook will limit an ansible action -running on hosts in the meta dict. - -Arguments: ---------- - host_path: The json path inside the event data to find hosts. - Do nothing if the key is not present or does exist in event - path_separator: The separator to interpret host_path. Default to "." - host_separator: The separator to interpret host string. - host_path can point to a string or a list. If it is a single - string but contains multiple hosts, use this parameter to - delimits the hosts. Treat the vale as a single host if the - parameter is not present. - raise_error: Whether raise PathNotExistError if host_path does not - exist in the event. Default to false. - It is recommended to turn it on during the rulebook - development time. You can then turn it off for production. - log_error: Whether log an error message if host_path does not - exist in the event. Default to true. - You can turn if off if it is expected to have events not - having the host_path to avoid noises in the log. - -Example: -------- - filters: - - ansible.eda.insert_hosts_to_meta: - host_path: "app.target" - path_separator: "." - host_separator: ";" - raise_error: true - log_error: true +DOCUMENTATION = r""" +--- +author: + - Doston Toirov (@dtoirov) +short_description: Extract hosts from the event data and insert them to the meta dict. +description: + - An ansible-rulebook event filter that extracts hosts from the event data and + inserts them to the meta dict. Ansible-rulebook will limit an ansible action + running on hosts in the meta dict. +options: + host_path: + description: + - The json path inside the event data to find hosts. + - Do nothing if the key is not present or does exist in event. + type: str + default: null + path_separator: + description: + - The separator to interpret host_path. + type: str + default: "." + host_separator: + description: + - The separator to interpret host string. + - host_path can point to a string or a list. If it is a single + string but contains multiple hosts, use this parameter to + delimits the hosts. Treat the value as a single host if the + parameter is not present. + type: str + default: null + raise_error: + description: + - Whether raise PathNotExistError if host_path does not + exist in the event. + - It is recommended to turn it on during the rulebook + development time. You can then turn it off for production. + type: bool + default: false + log_error: + description: + - Whether log an error message if host_path does not + exist in the event. + - You can turn if off if it is expected to have events not + having the host_path to avoid noises in the log. + type: bool + default: true +""" +EXAMPLES = r""" +filters: + - ansible.eda.insert_hosts_to_meta: + host_path: "app.target" + path_separator: "." + host_separator: ";" + raise_error: true + log_error: true """ from __future__ import annotations diff --git a/extensions/eda/plugins/event_filter/json_filter.py b/extensions/eda/plugins/event_filter/json_filter.py index 551f7160..37830d37 100644 --- a/extensions/eda/plugins/event_filter/json_filter.py +++ b/extensions/eda/plugins/event_filter/json_filter.py @@ -1,16 +1,25 @@ -"""json_filter.py: An event filter that filters keys out of events. - -Includes override excludes. - -This is useful to exclude information from events that is unneeded by the rule -engine. - -Arguments: ---------- - * exclude_keys = a list of strings or patterns to remove - * include_keys = a list of strings or patterns to keep even if it matches - exclude_keys patterns. - +DOCUMENTATION = r""" +--- +author: + - Doston Toirov (@dtoirov) +short_description: Filter keys out of events. +description: + - An event filter that filters keys out of events. + Includes override excludes. + This is useful to exclude information from events that is unneeded by the rule engine. +options: + exclude_keys: + description: + - A list of strings or patterns to remove. + type: list + elements: str + default: null + include_keys: + description: + - A list of strings or patterns to keep even if it matches exclude_keys patterns. + type: list + elements: str + default: null """ from __future__ import annotations diff --git a/extensions/eda/plugins/event_filter/noop.py b/extensions/eda/plugins/event_filter/noop.py index 8f0756fb..245efe21 100644 --- a/extensions/eda/plugins/event_filter/noop.py +++ b/extensions/eda/plugins/event_filter/noop.py @@ -1,4 +1,11 @@ -"""noop.py: An event filter that does nothing to the input.""" +DOCUMENTATION = r""" +--- +author: + - Doston Toirov (@dtoirov) +short_description: Do nothing. +description: + - An event filter that does nothing to the input. +""" from typing import Any diff --git a/extensions/eda/plugins/event_filter/normalize_keys.py b/extensions/eda/plugins/event_filter/normalize_keys.py index 58256c39..618c8435 100644 --- a/extensions/eda/plugins/event_filter/normalize_keys.py +++ b/extensions/eda/plugins/event_filter/normalize_keys.py @@ -1,40 +1,40 @@ -"""normalize_keys.py. - - An event filter that changes keys that contain non alpha numeric or +DOCUMENTATION = r""" +--- +author: + - Doston Toirov (@dtoirov) +short_description: Change keys that contain non-alpha numeric or underscore to underscores. +description: | + - An event filter that changes keys that contain non alpha numeric or underscore to underscores. - For instance, the key server-name becomes the new key server_name - If there are consecutive non alpa numeric or under score, they would - be coalesced into a single underscore + - For instance, the key server-name becomes the new key server_name. + If there are consecutive non alpha numeric or under score, they would + be coalesced into a single underscore. For instance the key server.com/&abc becomes server_com_abc instead of server_com__abc. + - If there is a existing key with the normalized name, it will get overwritten + by default. If you don't want to over write it you can pass in "overwrite: false" + The default value of overwrite is true. +options: + overwrite: + description: + - Overwrite the values if there is a collision with a new key. + type: bool + default: true +""" - If there is a existing key with the normalized name, it will get overwritten - by default. If you don't want to over write it you can pass in overwrite: False - The default value of overwrite is True. - -Arguments: ---------- - * overwrite: Overwrite the values if there is a collision with a new key. - -Usage in a rulebook, a filter is usually attached to a source in the rulebook: - example1: - .... - sources: - - my_source: - .... - filters: - ansible.eda.normalize_keys: - - - example2: To prevent over writing of keys - .... - sources: - - my_source: - .... - filters: - ansible.eda.normalize_keys: - overwrite: False - +EXAMPLES = r""" +- sources: + - my_source: + .... + filters: + ansible.eda.normalize_keys: +- name: prevent overwriting of keys + sources: + - my_source: + .... + filters: + ansible.eda.normalize_keys: + overwrite: false """ import logging