12. Unify Applications monitoring

This chapter describes how to monitor the various unify applications deployed within the same MQTT broker.

12.1. Overview

Application monitoring intend to provide application-level monitoring information. Any application/MQTT client participating in the system should be able to be monitored using this functionality.

An ApplicationMonitoring Unify cluster has been designed for this reporting purpose. It operates as all other clusters, with Attributes, SupportedCommands and Commands.

The difference about this cluster, is that it does not use any UNID, but instead MQTT Client ID. An overview of the publications under this cluster is shown below:

ucl/by-mqtt-client/<client-id>/ApplicationMonitoring/<AttributeName>/Reported { "value": 23 }
ucl/by-mqtt-client/<client-id>/ApplicationMonitoring/SupportedCommands { "value": ["WriteAttributes"}] }
ucl/by-mqtt-client/<client-id>/ApplicationMonitoring/SupportedGeneratedCommands { "value": ["LogMessage"] }
ucl/by-mqtt-client/<client-id>/ApplicationMonitoring/Commands/<CommandName> { "field1": 42 }
ucl/by-mqtt-client/<client-id>/ApplicationMonitoring/GeneratedCommands/<CommandName> { "field1": 42 }

No endpoints are used for this cluster.

Note that all communications and commands executions are expected to be instantaneous in the ucl/by-mqtt-client/ topic space. Therefore, the Desired value of attributes MUST NOT be published under this topic space.

12.2. MQTT Client ID

Each MQTT Client connecting to the system is responsible for creating a unique Client ID.

To allow for multiple instances of the same application avoiding to use the same MQTT client ID, it is RECOMMENDED to use the following format: application_name-docker_container_id-process_id. With the following elements:

• application_name is the name of the application running.

• docker_container_id is the docker container ID, if running in a docker container.

• process_id is the unique process identifier on the system.

For example, the unify_aoxpc running in a docker container ID d8453812a556 and process ID 1 would be: aoxpc-d8453812a556-1.

If no docker container is used, the container ID should be skipped, for example aoxpc-37296

12.3. MQTT Will Message

Applications connecting to the MQTT broker that support ApplicationMonitoring MUST publish all mandatory attributes from the ApplicationMonitoring cluster.

A special attribute called ApplicationConnected MUST alwasy be set to true. It is used to detect non-graceful disconnects from MQTT Clients.

When establishing an MQTT connection to the broker, applications MUST set their will message to be a publication at the following topic:

ucl/by-mqtt-client/<client-id>/ApplicationMonitoring/ApplicationConnected/Reported { "value": false }

This way, other clients will be able to see detect if an application shut down non-gracefully.

Applications disconnecting gracecully MUST unretaining all messages that they published under their ucl/by-mqtt-client/<client-id>/ topic.

The diagram below shows an example of a non-graceful disconnect of an application:

12.4. Logging

Applications supporting the logging functionality will advertise the following attributes as supported:

• MQTTLoggingEnabled

• LoggingLevel

They will support the following WriteAttributes command to modify these attributes and they will generate a LogEntry for each log message when logging via MQTT is enabled.

12.5. Detecting stale MQTT topics

Each application SHOULD publish a list of expected topic spaces that they will be using to publish.

Using this information, an IoT Service can detect and decide to remove stale topics when an application left the system non-gracefully.

12.6. MQTT Statistics for each application

Each application MAY report basic statistics about its MQTT communications with the broker.

As for SystemMetrics, applications that support reporting MQTT Statistics MUST support the MQTTStatisticsReportingIntervalSeconds attribute, that will allow clients to configure how often these statistics are to be published.

12.7. System Statistics for each application

Each application MAY report System Metrics like statistics for itself.

As for SystemMetrics, applications that support reporting Application System Statistics MUST support the ApplicationStatisticsReportingIntervalSeconds attribute, that will allow MQTT clients to configure how often these statistics are to be published.