Documentation on Sources

[martialblog]

Hi,

Not sure if this is an issue for this repository or Icinga Notifications Web. Feel free to move the issue if necessary.

The docs here mention in the first sentence

Icinga Notifications is a set of components that processes received events from various sources [...]

and from the blog post about Icinga Notifications it is my understanding that Icinga Notifications is meant as a generic tool for managing notifications and their recipients (maybe that assumption is wrong, feel free to correct me).

However, there is currently little to none documentation on how to do that.

The docs here mention "Sources" and that

[...] Next to Icinga DB, other notification sources can be configured.

Another reference is in the Icinga Notifications Web docs where it says

Sources are the most vital part of Icinga Notifications. Without them, no events will be processed and no notifications will be sent. So the next thing to configure is your first source. To be able to configure sources, an integration in Icinga Web is required. Consult the source-specific documentation on how to integrate such.

Is there anything I'm missing? How would one create or configure these "sources" when they are not Icinga2/IcingaDB Web or Icinga Kubernetes?

Cheers

[martialblog]

Related to this, the general question "What even is a source"? I know it is something that generates events, but it seems there is more to it than that.

See #253

[martialblog]

I saw there's a Hook that can be implemented in PHP to provide a source? Is that correct?

https://github.com/Icinga/icinga-notifications-web/blob/main/library/Notifications/Hook/V1/SourceHook.php

I small description of how these different components work together would really be helpful.

[oxzi]

In a nutshell, sources are twofold at the moment: a application and a web module.

Your main source is an application sending notification events - such as state changes - to the Icinga Notifications /process-event API. Starting with version 1.5.0, Icinga DB acts as such a source with implementing the source.Client from the IGL.

However, the /process-event API does not only accept events, but also feedbacks outdated rules. "What are rules now?!1!", you might ask yourself.

The Icinga Notifications Web configuration is based on rules, containing filters to decide which event gets dispatched to whom. This is briefly explained in the now a bit outdated getting started blog post.

To allow source-specific filters, the filter logic needs to know a bit about the source. For example, when using Icinga DB, you might wanna filter based on the service name or custom vars. However, when using K8s, there are no service names and you might wanna use some deployment attribute or pod name.

Thus, different sources require different filters. These filters are now implemented on the web part via the SourceHook you mentioned. Continuing with the Icinga DB example, Icinga DB Web supplies this hook with its latest release 1.3.0. This allows clicking a filter with a similar UI as already known by Icinga DB Web.

The filters generated by the hook-implementing web module are stored in some source-specific format. In other words, whatever fits best for the source. For Icinga DB/Icinga DB Web, SQL queries are prepared to be executed by Icinga DB to determine if an event should be forwarded.

To wrap it up: as before, you need an application acting as a source, submitting events to the Icinga Notifications /process-event API and some counterpart in Icinga Web 2 implementing the hook.

Please note: The plan is to simplify this again for the next release, hopefully enabling a simpler API to be just curled.