Skip to content

DeviceQoSEvaluator

This Support System has the purpose of collecting and calculating Key Performance Indicators (KPIs) from the devices operating within a Local Cloud. Based on the calculated KPIs this system can assist in finding the best service provider system(s) to fulfill specific requirements.

Learn more:
Abstract System Description (SysD)

Services

qualityEvaluation

The purpose of this service is to filter or sort systems based on a specified KPI set with associated weighting factors over a defined time window. The service is offered for both application and Core/Support systems.

Learn more:
Abstract Service Description (SD)
generic_http (IDD) | generic_https (IDD)
generic_mqtt (IDD) | generic_mqtts (IDD)
since: v5.2.0

Service metadata: 

{
    "evaluationType": "basic-device-kpi"
}

filter

This service operation filters out any systems from a given list whose calculated QoS scores exceed a specified threshold.

Example: generic_http | generic_https
Example: generic_mqtt | generic_mqtts

sort

This service operation sorts a given list of systems according to their calculated QoS scores.

Example: generic_http | generic_https
Example: generic_mqtt | generic_mqtts

deviceQualityDataManagement

The purpose of this service is to query the measurement metric values and also to trigger the synchronization with ServiceRegistry Core System manually. This service is offered for Core/Support systems.

Learn more:
Abstract Service Description (SD)
generic_http (IDD) | generic_https (IDD)
generic_mqtt (IDD) | generic_mqtts (IDD)
since: v5.2.0

query

This service operation queries raw measurement data using the specified filters.

Example: generic_http | generic_https
Example: generic_mqtt | generic_mqtts

reload

This service operation initiates the synchronization of system and device entities

Example: generic_http | generic_https
Example: generic_mqtt | generic_mqtts

generalManagement

Its purpose is to get some information about the hosting system’s behavior, such as log entries and configuration settings. The service is offered for administrative Support systems.

Learn more:
Abstract Service Description (SD)
generic_http (IDD) | generic_https (IDD)
generic_mqtt (IDD) | generic_mqtts (IDD)
since: v5.2.0

get-log

This service operation lists the log entries of the system that match the filtering requirements.

Example: generic_http | generic_https
Example: generic_mqtt | generic_mqtts

get-config

This service operation lists the current values of the specified configuration settings.

Example: generic_http | generic_https
Example: generic_mqtt | generic_mqtts

Measurement Routines

Basic

Round-Trip Time (RTT) measurements are performed towards the Local Cloud’s devices without requiring any additional effort. For detailed information about the RTT measurement process, refer to the SysD document.

In order to calculating proper RTT based KPIs, a reasonable rtt.measurement.timeout shall be configured. This timeout defines the maximum allowed duration for a connection attempt and is treated as the upper bound of the measurement window, meaning that all RTT measurements are normalized relative to this value. Also, this timeout must be always less than the augmented.measurement.job.interval.

Augmented

Augmented measurement groups and types are uniquely identified by hierarchical, OID-like unique identifiers.

Performing augmented measurements requires two thing:

  • Installing a device agent on the hosting devices (hardwares, virtual machines or containers).
  • Specifying the supported measurements on system level by using system metadata.

Device Agent

The device-side agent is a lightweight monitoring server implemented in Python. It continuously samples the current performance in every second per OID sub-groups and caches the collected values in a 30-second time window. The DeviceQoSEvaluator system periodically retrieves these samples and computes the corresponding OID statistical values, which are then stored for a configurable retention period. Operators can enable or disable specific OID sub-groups through the agent’s configuration.

System Metadata

If a system of the Local Cloud is being hosted on a device that running the device agent, it shall advertiese its enabled OID sub-groups through the ServiceRegistry Core System by using the system metadata the following way:

{
    "qos": {
        "deviceAugmented": [ "1.4", "2.1", "3.1", "3.2" ]
    }
}

Configuration

The system configuration properties can be found in the application.properties file located at /src/main/resources folder.

Note: During the build process this file is going to be built into the executable JAR, but also going to be copied next to the JAR file. Any modification in the configuration file located next to the executable JAR file will override the built in configuration property value.

General parameters

See the general configuration properties.

Database parameters

spring.datasource.url

URL to the database.

spring.datasource.username

Username to the database.

spring.datasource.password

Password to the database.

spring.datasource.driver-class-name

The driver provides the connection to the database and implements the protocol for transferring the query and result between client and database.

spring.jpa.show-sql

Set to true in order to log out the SQL queries.

spring.jpa.properties.hibernate.format sql

Set to true to log out SQL queries in pretty format. (Effective only when 'spring.jpa.show-sql' is 'true')

spring.jpa.hibernate.ddl-auto

Auto initialization of database tables. Value must be always 'none'.

Custom parameters

authenticator.credentials

The credentials that this system will use for performing the login operation when the authentication policy is outsourced.

authenticator.credentials={\
    '<credential-name>': '<credential-value>' \
}

enable.management.filter

Enable or disable authorization for accessing the management services. Can be true of false.

management.policy

Way of authorizing the management service requester systems. Can be:

  • sysop-only, when the authenticated requester system has system-operator role that ensures overall management permission.
  • whitelist, sysop-only and when the authenticated requester system is whitelisted in the management.whitelist configuration property that ensures overall management permission.
  • authorization, sysop-only and whitelist and when the authenticated requester system has appropriate service permission according to the ConsumerAuthorization Core system.

management.whitelist

Name of the systems which can access to management services in case of whitelist policy is effective.

enable.blacklist.filter

Enable/disable automatic service requester system name verification against to cloud level blacklist. Can be true or false.

force.blacklist.filter

Whether or not the service requests should be refused when the blacklist server is not responding. Can be true or false.

blacklist.check.exclude.list

Comma-separated list that contains systems whose requests are served without checking the cloud level blacklist, even if blacklist is enabled.

max.page.size

Specifies the maximum number of records a page can contain in case of pageable service responses.

measurement.organizer.job.interval

Specifies the interval (in seconds) at which the device and system tables are synchronized by querying the ServiceRegistry Core System, and the measurements are reorganized. The interval cannot be less than 10 seconds.

rtt.measurement.job.interval

Specifies the frequency (in seconds) for measuring the round-trip time to the devices. The frequency cannot be less than 5 seconds.

rtt.measurement.timeout

Specifies how long to wait (in milliseconds) for a response during a round-trip time measurement. This value cannot be less then 3000 milliseconds, must be less than the rtt.measurement.job.interval and is also treated as 100% (worst case) when scaling during the evaluation process.

augmented.measurement.job.interval

Specifies the frequency (in seconds) of fetching the augmented measurement results from the devices. The frequency cannot be less than 5 seconds.
Note: The device agent caches measurements within a 30-second time window. Any frequency higher than 30 seconds will result measurement loss.

evaluation.time.window

Specifies the duration (in seconds) of the time window to be evaluated. The duration must be less than raw.measurement.data.max.age.

cleaning.job.interval

Specifies the interval (in seconds) at which the cleaning job is executed. The interval cannot be less than 60 seconds.

raw.measurement.data.max.age

Specifies after how many minutes the raw measurement data is removed from the database.

inactive.device.max.age

Specifies after how many minutes inactive devices are removed from the database. Removal occurs only if no raw measurement data is available for the device.

Logging configuration

The logging configuration properties can be found in the log4j2.xml file located at src/main/resources folder.

Note: During the build process this file is going to be built into the executable JAR, but it is also possible to override it by an external file. For that use the following command when starting the system:

java -jar arrowhead-device-qos-evaluator-x.x.x.jar
     -Dlog4j.configurationFile=path-to-external-file

JDBC_LEVEL

Set this to change the level of log messages in the database. Levels: ALL, TRACE, DEBUG, INFO, WARN, ERROR, FATAL, OFF.

CONSOLE FILE LEVEL

Set this to change the level of log messages in consol and the log file. Levels: ALL, TRACE, DEBUG, INFO, WARN, ERROR, FATAL, OFF.

LOG_DIR

Set this to change the directory of log files.