alertmanager

Alertmanager module.

exception spicerack.alertmanager.AlertmanagerError(message: str, response: requests.models.Response | None = None) → None

Bases: SpicerackError

Custom exception class for errors of this module.

Initializes an AlertmanagerError instance with the API response instance.

Parameters:

• message (str) -- the actual exception message.

• response (typing.Optional[requests.models.Response], default: None) -- the requests response object, if present.

class spicerack.alertmanager.Alertmanager(*, alertmanager_urls: collections.abc.Sequence[str], http_authentication: requests.auth.AuthBase | None = None, http_proxies: dict[str, str] | None = None, dry_run: bool = True) → None

Bases: object

Operate on Alertmanager via its APIs.

Initialize the instance.

When using Alertmanager in high availability (cluster) make sure to pass all hosts in your cluster as alertmanager_urls.

Parameters:

• alertmanager_urls (collections.abc.Sequence[str]) -- list of Alertmanager instances to connect to.

• http_authentication (typing.Optional[requests.auth.AuthBase], default: None) -- Requests authentication configuration to use to connect to the Alertmanager instances.

• http_proxies (typing.Optional[dict[str, str]], default: None) -- HTTP proxies in requests format to use to connect to the Alertmanager instances.

• dry_run (bool, default: True) -- whether this is a DRY-RUN.

Raises:

spicerack.alertmanager.AlertmanagerError -- if alertmanager_urls is empty.

downtime(reason: spicerack.administrative.Reason, *, matchers: collections.abc.Sequence[dict[str, str | int | float | bool]], duration: datetime.timedelta = datetime.timedelta(seconds=14400)) → str

Issue a new downtime.

Parameters:

• reason (spicerack.administrative.Reason) -- the downtime reason.

• matchers (collections.abc.Sequence[dict[str, typing.Union[str, int, float, bool]]]) -- the list of matchers to be applied to the downtime. The downtime will match alerts that match all the matchers provided, as they are ANDed by AlertManager.

• duration (datetime.timedelta, default: datetime.timedelta(seconds=14400)) -- the length of the downtime period.

Return type:

str

Returns:

The downtime ID.

Raises:

• spicerack.alertmanager.AlertmanagerError -- if none of the alertmanager_urls API returned a success or the

• parameters are invalid. --

downtimed(reason: spicerack.administrative.Reason, *, matchers: collections.abc.Sequence[dict[str, str | int | float | bool]], duration: datetime.timedelta = datetime.timedelta(seconds=14400), remove_on_error: bool = False) → collections.abc.Iterator[None]

Context manager to perform actions while the matching alerts are downtimed on Alertmanager.

Parameters:

• reason (spicerack.administrative.Reason) -- the reason to set for the downtime on Alertmanager.

• matchers (collections.abc.Sequence[dict[str, typing.Union[str, int, float, bool]]]) -- the list of matchers to be applied to the downtime. The downtime will match alerts that match all the matchers provided, as they are ANDed by AlertManager.

• duration (datetime.timedelta, default: datetime.timedelta(seconds=14400)) -- the length of the downtime period.

• remove_on_error (bool, default: False) -- should the downtime be removed even if an exception was raised.

Yields:

None -- it just yields control to the caller once Alertmanager has received the downtime and deletes the downtime once getting back the control.

Return type:

collections.abc.Iterator[None]

hosts(target_hosts: spicerack.typing.TypeHosts, *, verbatim_hosts: bool = False) → spicerack.alertmanager.AlertmanagerHosts

Returns an AlertmanagerHosts instance for the specified hosts.

Parameters:

• target_hosts (typing.TypeVar(TypeHosts, collections.abc.Sequence[str], ClusterShell.NodeSet.NodeSet)) -- the target hosts either as a NodeSet instance or a sequence of strings.

• verbatim_hosts (bool, default: False) -- if True use the hosts passed verbatim as is, if instead False, the default, consider the given target hosts as FQDNs and extract their hostnames to be used in Alertmanager.

Raises:

spicerack.alertmanager.AlertmanagerError -- if no target hosts are provided.

Return type:

spicerack.alertmanager.AlertmanagerHosts

remove_downtime(downtime_id: str) → None

Remove a downtime.

Parameters:

downtime_id (str) -- the downtime ID to remove.

Raises:

spicerack.alertmanager.AlertmanagerError -- if none of the alertmanager_urls API returned a success.

Return type:

None

class spicerack.alertmanager.AlertmanagerHosts(target_hosts: spicerack.typing.TypeHosts, *, verbatim_hosts: bool = False, alertmanager_urls: collections.abc.Sequence[str], http_authentication: requests.auth.AuthBase | None = None, http_proxies: dict[str, str] | None = None, dry_run: bool = True) → None

Bases: Alertmanager

Operate on Alertmanager for a list of hosts via its APIs.

Initialize the instance.

Parameters:

• target_hosts (typing.TypeVar(TypeHosts, collections.abc.Sequence[str], ClusterShell.NodeSet.NodeSet)) -- the target hosts either as a NodeSet instance or a sequence of strings.

• verbatim_hosts (bool, default: False) -- if True use the hosts passed verbatim as is, if instead False, the default, consider the given target hosts as FQDNs and extract their hostnames to be used in Alertmanager.

• alertmanager_urls (collections.abc.Sequence[str]) -- list of Alertmanager instances to connect to.

• http_authentication (typing.Optional[requests.auth.AuthBase], default: None) -- Requests authentication configuration to use to connect to the Alertmanager instances.

• http_proxies (typing.Optional[dict[str, str]], default: None) -- HTTP proxies in requests format to use to connect to the Alertmanager instances.

• dry_run (bool, default: True) -- whether this is a DRY-RUN.

Raises:

spicerack.alertmanager.AlertmanagerError -- if no target hosts are provided.

downtime(reason: spicerack.administrative.Reason, *, matchers: collections.abc.Sequence[dict[str, str | int | float | bool]] = (), duration: datetime.timedelta = datetime.timedelta(seconds=14400)) → str

Issue a new downtime for the given hosts.

Parameters:

• reason (spicerack.administrative.Reason) -- the downtime reason.

• matchers (collections.abc.Sequence[dict[str, typing.Union[str, int, float, bool]]], default: ()) -- an optional list of matchers to be applied to the downtime. They will be added to the matcher automatically generated to match the current instance target_hosts hosts. For this reason the provided matchers cannot be for the instance property. The downtime will match alerts that match all the matchers provided, as they are ANDed by AlertManager.

• duration (datetime.timedelta, default: datetime.timedelta(seconds=14400)) -- the length of the downtime period.

Returns:

the downtime ID.

Return type:

str

Raises:

• spicerack.alertmanager.AlertmanagerError -- if none of the alertmanager_urls API returned a success or the

• parameters are invalid. --

downtimed(reason: spicerack.administrative.Reason, *, matchers: collections.abc.Sequence[dict[str, str | int | float | bool]] = (), duration: datetime.timedelta = datetime.timedelta(seconds=14400), remove_on_error: bool = False) → collections.abc.Iterator[None]

Context manager to perform actions while the hosts are downtimed on Alertmanager.

Parameters:

• reason (spicerack.administrative.Reason) -- the reason to set for the downtime on Alertmanager.

• matchers (collections.abc.Sequence[dict[str, typing.Union[str, int, float, bool]]], default: ()) -- an optional list of matchers to be applied to the downtime. They will be added to the matcher automatically generated to match the current instance target_hosts hosts. For this reason the provided matchers cannot be for the instance property. The downtime will match alerts that match all the matchers provided, as they are ANDed by AlertManager.

• duration (datetime.timedelta, default: datetime.timedelta(seconds=14400)) -- the length of the downtime period.

• remove_on_error (bool, default: False) -- should the downtime be removed even if an exception was raised.

Yields:

None -- it just yields control to the caller once Alertmanager has received the downtime and deletes the downtime once getting back the control.

Return type:

collections.abc.Iterator[None]

spicerack.alertmanager.PORT_REGEX: str = '(\\..+)?(:[0-9]+)?'

The regular expression used to match FQDNs and port numbers in the instance labels.