Get started

The Health Monitor is an IoTCatalyst add-on that can monitor the status of the Hypervisors on which the Catalyst agent is installed.

The Health Monitor is constantly listening to the MQTT broker and therefore knows the statuses of all the Hypervisors at all times. It is designed to monitor thousands of Hypervisors in a high-performance way. It exposes a RESTful API with which it is possible to retrieve information on the statuses of all Hypervisors, of a specific one (by name or id), or a subset marked by specific tags.

But the information made available by the Health Monitor is not limited to the simple status: the agent collects other helpful information about the devices on which it is installed, such as the device's disk space or RAM, as well as device label information and when the agent last changed its state. The Health Monitor receives this information and makes it available via its API.

It is also possible to ask the microservice for counts of the installed Hypervisors, where a typical question could be: "How many Hypervisors in the field are currently in the 'disconnected' state?".

Another very useful function in practice, found built-in in the Health Monitor, is obtaining information on the change of statuses of the Hypervisors.

In fact, "info" or "alarm" type events are automatically generated if the status of a Hypervisor changes. These events are kept in the microservice's memory for a certain number of days (settable by API) according to the following table:

All the information stored by the Health Monitor are easily accessible using the RESTFul API here described.

Invoking the APIs

Once you've set up the frontend, you can use remote HTTP requests to call the API. To do that you need to send HTTP POST requests to the API endpoint file located in the frontend directory. For example, if your IoT Catalyst Studio frontend is installed under HTTPS://{IoTCatalystStudioEndpoint}, the HTTP request to call will look like this:

curl -X GET -H "Authorization:<valid IoT Catalyst Studio session token> "http://<IoTCatalystStudioEndpoint>/health-monitor/status;"
                    

The API makes use of query parameters in order to filter the results or simply in order to choose between id or name as keys in the results. Some endpoints have mandatory request parameters. The parameter "force_refresh", which if "true" would force the refresh of the cache, is always optional and defaults to "false".

Security

Before you can access any data inside of IoT Catalyst Health Monitor you'll need to log in and obtain an authentication token. This can be done using the APISecurity.requestToken method.

Once you have obtained a valid IoTCatalyst Session Token, you should use it as a bearer token in your RESTFul API invocations

CURL Invocation Example

curl -X GET -H "Authorization:<valid IoT Catalyst Studio session token> "http://<IoTCatalystStudioEndpoint>/health-monitor/status";                           
                    

JAVASCRIPT

$.ajax({
    url: http://<IoTCatalystStudioEndpoint>//hypervisor/hypervisors/count?status=connected,
    async: true,
    crossDomain: true,
    method: "GET",
    dataType: "json",
    contentType: "application/json;",
    cache: false,            
    beforeSend: function (xhr) {
        /* Authorization header */
        xhr.setRequestHeader("Authorization", "Bearer ************************");                 
    },
    "statusCode": {
        401: function (xhr, error, thrown) {
            console.error("Impossible to load Hypervisors counter from HM. "+JSON.parse(xhr.responseText).message,'',true);
            return;
        },
        403: function (xhr, error, thrown) {
            console.error("Impossible to load Hypervisors counter from HM. "+JSON.parse(xhr.responseText).message,'',true);
            return;
        }
    },
    success: function (data) {
        console.log(data);
    },
    error: function (jqXHR, textStatus, errorThrown) {
        //error handling routine goes here...
    }			
});





                        
                    

Response Format

if everything goes well, IoT Catalyst Health Monitor API response will contain a valid JSON data.

Here follows an example of JSON data generated by the API GetAllHypervisorsStatuses

                    {
    "data": {
        "FullTesterWindows1": {
            "location": "FWD Lab",
            "vendor": "Generic Windows 64 Bit",
            "model": "Win AMD 64bit",
            "architecture": "p36-win-amd64"
        },
        "FWDLab498_1": {
            "process_CPU_load": "0",
            "process_RAM_load": "0",
            "total_disk_usage": "0",
            "status": "disconnected",
            "free_disk_space": "0",
            "free_RAM": "0",
            "log_level": 10,
            "total_disk_space": "0",
            "system_CPU_load": "0",
            "total_RAM": "0",
            "pid": 0,
            "sdk_version": "1.5.3",
            "status_from": 1666872433033,
            "id": "563",
            "name": "FWDLab498_1",
            "location": "FWDLab498",
            "vendor": "Fair Winds Digital",
            "model": "Edge XT",
            "architecture": "p35-linux-armv7"
        },
        "FWDLab498_2": {
            "status": "disconnected",
            "pid": 0,
            "sdk_version": "1.6.0",
            "system_CPU_load": "0",
            "process_CPU_load": "0",
            "process_RAM_load": "0",
            "free_RAM": "0",
            "total_RAM": "0",
            "total_disk_usage": "0",
            "free_disk_space": "0",
            "total_disk_space": "0",
            "log_level": 10,
            "status_from": 1666872433081,
            "id": "908",
            "name": "FWDLab498_2",
            "location": "FWD Lab",
            "vendor": "Fair Winds Digital",
            "model": "Edge XT",
            "architecture": "p37-linux-armv7"
        },
        "FWD_Edge_XT_Relax_Room": {
            "status": "connected",
            "pid": "665",
            "sdk_version": "1.5.3",
            "system_CPU_load": "32.1",
            "process_CPU_load": "3.0",
            "process_RAM_load": "2.46",
            "free_RAM": "82.72",
            "total_RAM": "948.30",
            "total_disk_usage": "27.0",
            "free_disk_space": "73.0",
            "total_disk_space": "1075.92",
            "log_level": 10,
            "status_from": 1680878476059,
            "id": "672",
            "name": "FWD_Edge_XT_Relax_Room",
            "location": "FWD Lab",
            "vendor": "Fair Winds Digital",
            "model": "Edge XT",
            "architecture": "p37-linux-armv7"
        },
        "HypervisorOTC": {
            "status": "connected",
            "pid": 15823,
            "sdk_version": "1.5.6",
            "system_CPU_load": "0",
            "process_CPU_load": "0",
            "process_RAM_load": "0",
            "free_RAM": "0",
            "total_RAM": "0",
            "total_disk_usage": "0",
            "free_disk_space": "0",
            "total_disk_space": "0",
            "log_level": 10,
            "status_from": 1680530464312,
            "id": "881",
            "name": "HypervisorOTC",
            "location": "IoT Catalyst Default Location",
            "vendor": "Generic",
            "model": "Linux",
            "architecture": "p37-linux-x86_64",
            "idComponentType": "5",
            "idComponent": "881",
            "InstalledOn": 1670259816,
            "LastKnownException": "",
            "Uptime": 1191286,
            "Details": {
                "sdk_version": "1.6.1.007",
                "system_CPU_load": "19.3",
                "process_CPU_load": "4.0",
                "process_RAM_load": "0.10",
                "free_RAM": "47.75",
                "total_RAM": "24660.71",
                "total_disk_usage": "46.2",
                "free_disk_space": "53.8",
                "total_disk_space": "574668.94"
            }
        },
        "HypeWizardTest": {
            "location": "IoT Catalyst Default Location",
            "vendor": "Generic Windows 64 Bit",
            "model": "Win AMD 64bit",
            "architecture": "p36-win-amd64"
        }
    },
    "message": "",
    "info": {
        "page": "1",
        "results_in_page": 6,
        "total_pages": 1,
        "total_elements": 6
    }
}

                    

Error Handling

Here is the list of possible error codes returned by the Health Monitor, with possible explanations:

### 400
Bad request body (on initialization).

### 401
Request with no Authorization header.

### 403
Request forbidden, for example the client has requested an endpoint related to Containers when the Health Monitor is in mode 'hypervisor'.

### 404
Apart from the obvious bad endpoint, even a correct endpoint can return this code if the Health Monitor is not initialized.
When asking for the status / stats of a Hypervisor or Container by id or name, the Health Monitor returns this code if the requested entity was not found.

### 409
Health Monitor already initialized.

### 422
A problem was encountered when initializing the Health Monitor (e.g. bad IoTCatalyst Studio credentials).
This code can also be returned when the Health Monitor is not functioning properly and thus cannot process the request.
                    

This endpoint initializes the Health Monitor. Until the Health Monitor is not initialized, it doesn"t listen for entities" statuses

METHOD

URL

AUTH TYPE

AUTH FIELDS

REQUEST PARAMETERS

This endpoint initializes the Health Monitor using a valid IoT Catalyst Passport. Until the Health Monitor is not initialized, it doesn"t listen for entities" statuses

METHOD

URL

AUTH TYPE

AUTH FIELDS

REQUEST PARAMETERS

This endpoint gets the status of the Health Monitor

METHOD

URL

REQUEST PARAMETERS

This endpoint gets a token from a IoT Catalyst Studio instance, the retrieved token is necessary in order to make authorized requests to the Health Monitor as indicated in the relevant parts of this document.

METHOD

URL

REQUEST PARAMETERS

This endpoint gets the stats of all Hypervisors, although with a compulsory pagination.

METHOD

URL

AUTH TYPE

AUTH FIELDS

REQUEST PARAMETERS

This endpoint gets the stats of a single Hypervisor.

METHOD

URL

AUTH TYPE

AUTH FIELDS

REQUEST PARAMETERS

This endpoint gets the statuses of all Hypervisors, although with a compulsory pagination.

METHOD

URL

AUTH TYPE

AUTH FIELDS

REQUEST PARAMETERS

This endpoint gets the status of a single Hypervisor.

METHOD

URL

AUTH TYPE

AUTH FIELDS

REQUEST PARAMETERS

This endpoint gets the count of the Hypervisors actually present in IoT Catalyst Domain

METHOD

URL

AUTH TYPE

AUTH FIELDS

REQUEST PARAMETERS

This endpoint gets the alarms relative to all Hypervisors, although with a compulsory pagination.

METHOD

URL

AUTH TYPE

AUTH FIELDS

REQUEST PARAMETERS

This endpoint gets the alarms relative to a single Hypervisor, although with a compulsory pagination.

METHOD

URL

AUTH TYPE

AUTH FIELDS

REQUEST PARAMETERS

This endpoint gets the info relative to all Hypervisors, although with a compulsory pagination.

METHOD

URL

AUTH TYPE

AUTH FIELDS

REQUEST PARAMETERS

This endpoint gets the info relative to a single Hypervisor, although with a compulsory pagination.

METHOD

URL

AUTH TYPE

AUTH FIELDS

REQUEST PARAMETERS

This endpoint gets the storage expiration (in days) relative to alarms or info of the Hypervisors

METHOD

URL

AUTH TYPE

AUTH FIELDS

REQUEST PARAMETERS

This endpoint sets the storage expiration (in days) relative to alarms or info of the Hypervisors.

METHOD

URL

AUTH TYPE

AUTH FIELDS

REQUEST PARAMETERS

This endpoint gets the logs of the Health Monitor service

METHOD

URL

AUTH TYPE

AUTH FIELDS

REQUEST PARAMETERS

This endpoint gets the storage expiration (in days) relative to the logs of the Health Monitor service.

METHOD

URL

AUTH TYPE

AUTH FIELDS

REQUEST PARAMETERS

This endpoint sets the storage expiration (in days) relative to the logs of the Health Monitor service

METHOD

URL

AUTH TYPE

AUTH FIELDS

REQUEST PARAMETERS

This endpoint gets a json with a collection of exemplary endpoints.

METHOD

URL

AUTH TYPE

AUTH FIELDS

REQUEST PARAMETERS

This endpoint returns a guide to the Health Monitor service

METHOD

URL

AUTH TYPE

AUTH FIELDS

REQUEST PARAMETERS