Maat Event Listener User Guide

EventListener

EventListener works as a listener and receives notifications about events (add/update/remove resources/services) in Maat. The application gives access to the collected events via REST API.

Configuration

Most important parameters of application.properties are as follows:

Property	Example Values	Description
mongo-host	localhost or 127.0.0.1	Hostname for EventListener database in the form of name or address
mongo-port	27022	Port number for EventListener database
mongo-timeout	3000	Timeout for EventListener database. It is waiting time for a response from Mongo database.
mongo-user	user	Username for MongoDB
mongo-password	password	Password for MongoDB
autoRegisterEventListener	on	Ability to enable or disable automatic registration EventListener application in Maat. Possible values: "on" - enable automatic registration "off" - disable automatic registration
maat-host	localhost or 127.0.0.1	Hostname for Maat application in the form of name or address
maat-port	8080	Port number for Maat application
event-listener-host	localhost or 127.0.0.1	Hostname for EventListener application in the form of name or address
server.port	8081	Port number for EventListener application

Building and running project

Required:

Maven 3.8.6
Java 17 LTS or higher
NoSQL Database (MongoDB)

Important:

In order for the application to work properly, it is necessary to run first Mongo database for EventListener. When the application loses connection to the database during operation, events will be automatically added to the cache database. NOTE After restoring the connection to the database, events will be added to the main database when the next event is received.

When the property "autoRegisterEventListener" will be set to "on" Maat application must be started first, because EventListener checks the occurrence of a listener with such name in Maat database. To disable this function change the value in application.properties to "off"

Building:

mvn clean install

Running:

java -jar target/*.jar

Building docker image

Run in eventListener folder:

docker build -t eventListener -f dockerForEventListener/Dockerfile .

Running EventListener with docker-compose

Go to dockerForEventListener/ folder and run:

docker-compose up

or if you want to run it in background

docker-compose up -d

REST API

Example links that invokes each API implemented in the EventListener application:

Link	Method	Input	Description
http://localhost:8081/events	GET	-	Get all events
http://localhost:8081/events/[ID]	GET	ID	Get event by ID
http://localhost:8081/eventlistener	POST	JSON	Add event

For GET method we can use a few params to filter events more accurately:

limit --to limit the number of displayed objects
offset --to make offset on received objects
fields --to display only selected fields (for example: fields=eventType,eventTime)

There is also the possibility to search elements by key-value option. For example parameter "eventType=ResourceCreateEvent" will search all attributes eventType with value ResourceCreateEvent.

An additional option is to filter events by date:

Key	Example value	Description
eventTimeGT	2023-05-25T10:15:00	Values greater than a specified date and time value
eventTimeGTE	2023-05-25T10:15:00	Values greater than or equal to a specified date and time value
eventTimeLT	2023-05-25T10:15:00	Values less than a specified date and time value
eventTimeLTE	2023-05-25T10:15:00	Values less than or equal to a specified date and time value
eventTime>	2023-05-25T10:15:00	Values greater than a specified date and time value
eventTime<	2023-05-25T10:15:00	Values less than a specified date and time value

Register new Listener

To register new Listener, you need to send request to Maat with specific parameters: - callback -- listener's address to which Maat must send notification - query -- specifies what type of events should be sent to this listener (e.g. ResourceCreateEvent, ResourceAttributeValueChangeEvent, ResourceDeleteEvent, ServiceCreateEvent, ServiceAttributeValueChangeEvent, ServiceDeleteEvent, null).
The null value of query sets sending notifications for all types of events**

EventListener uses automatic registration as listener in Maat application (using property "autoRegisterEventListener" in application.properties). Example of POST request sent to Maat is given below:

{
    "callback" : "http://localhost:8081/eventlistener",
    "query" : null
}

Data visualization in Grafana

Grafana

Grafana open source is open source visualization and analytics software. It allows you to query, visualize, alert on, and explore your metrics, logs, and traces no matter where they are stored. It provides you with tools to turn your time-series database (TSDB) data into insightful graphs and visualizations.

Grafana installation

Instructions for installing Grafana on the system: https://grafana.com/docs/grafana/latest/setup-grafana/installation/

Instructions for installing Grafana on the docker: https://grafana.com/docs/grafana/latest/setup-grafana/installation/docker/

Adding a data source

In order for Grafana to display any data, it needs its source. To add EventListener as a data source, follow the steps below.

Go to Grafana Web Interface

Open a web browser.
Navigate to the Grafana Web Interface URL:
http://<SERVER_IP>:3000
Sign in (by default: admin:admin).

Infinity data source installation

Go to the Connections:
- From the left menu, click Connections.
Find Infinity Datasource.
Click Install (requires admin privileges)
After the installation process is complete, create a new data source:
- Click "Add new data source"
- Change name to "eventlistener-infinity"
- Toggle as default
- Click "Save & test".

Importing the EventListener dashboard

The ready eventlistener_dashboard.json file containing the dashboard for EventListener is located in the “Grafana” folder of the project files. However, in order for it to work properly before importing it, make sure that all required ip address changes have been applied.

Edit eventlistener_dashboard.json

Open the eventlistener_dashboard.json file for editing.
Replace localhost with the correct address on which EventListener is running. (lines: 97, 98, 232)
Example:
"url": "http://localhost:8081/events,"
change to
"url": "http://<eventlistener_ip>:8081/events",
Replace localhost with the correct address on which the gui for Maat is running. (lines: 135, 136)
Example:
"title": "http://localhost:9100${__data.fields.supportive}","
change to
"title": "http://<maat_gui_ip>:9100${__data.fields.supportive}",