alerta-blackout-regex 3.1.0
Alerta Blackout enhancement plugin
License: Apache License 2.0

alerta-blackout-regex
=====================

`Alerta <https://alerta.io/>`_ plugin to enhance the blackout management, by 
matching the alerts against blackouts with PCRE (Perl Compatible Regular 
Expression) on attributes.

A blackout is considered matched when all its attributes are matched.

Once an alert is identified as matching a blackout, a special label is applied,
with the format: ``regex_blackout=<blackout id>``, where *blackout id* is the 
ID of the matched blackout, e.g., 
``regex_blackout=d8ba1d3b-dbfd-4677-ab00-e7f8469d7ad3``. This way, when the 
alert is fired again, there's no need to verify the matching again, but simply
verify whether the blackout referenced is still active.

.. important::

    Beginning with version 2.0.0, the behaviour has changed, and instead of 
    evaluating the alert into the `post_receive` hook, this plugin now 
    evaluates the alerts through the `pre_receive` hook. The reasoning was that 
    `post_receive` would set the `blackout` status *after* the alert has been 
    sent to other plugins, which has resulted in confusing behaviour.

    That said, the plugin has been changed to process the alert in 
    ``pre_receive`` and therefore before the alert has been correlated. As the 
    Blackouts are retrieved from the Alerta API as unfortunately there's no 
    other way to gather the Blackouts from a plugin via other internal 
    mechanisms, processing each and every alert throguh `pre_receive` would put 
    a lot more workload on your Alerta API. To reduce this, the 
    `blackout_regex` plugin now caches the Blackouts locally, into a file. To 
    fine tune this behaviour for your own setup you are able to set a few 
    environment variables. See more details below, under the _Configuration_ 
    section.

.. note::

    Starting with version 3.0.0 onwards, the plugin will gather the list of 
    Blackouts straight from the database (instead of using the API, as 
    previously). This should normally improve reliability, but as there's no
    caching involved, every alert notification coming in (before being 
    evaluated and correlated) will cause a DB query.

Installation
------------

This plugin is designed to be installed on the Alerta server; the package is 
available on PyPI so you can install as:

.. code-block:: bash

    pip install alerta-blackout-regex

Configuration
-------------

Add ``blackout_regex`` to the list of enabled PLUGINS in ``alertad.conf`` server
configuration file and set plugin-specific variables either in the server
configuration file or as environment variables.

.. code-block:: ini

  PLUGINS = ['blackout_regex']

.. note::

    To ensure this plugin won't affect the existing Blackouts you may have in 
    place, it is recommended to list the `blackout_regex` plugin *after* the 
    native ``blackout`` plugin in the ``PLUGINS`` configuration option or 
    environment variable.

References
----------

- `Suppressing Alerts using Blackouts 
  <https://docs.alerta.io/en/latest/gettingstarted/tutorial-5-blackouts.html>`_

License
-------

Copyright (c) 2020-2022 Mircea Ulinic. Available under the Apache License 2.0.