Overview
The monitoring API can be used to receive monitoring information about all tags and gateways of a given site, it uses the MQTT protocol with a monitoring topic per site. Notifications by emails also are sent to Tracking managers of the sites.
Each MQTT message contains a topic and a payload.
The topic of the message contains the siteID and has the following format:
1 | {environment}/{API_key}/monitoring |
where
- environment is prod
- API_key gives access to your site on NAO Cloud. API Key can be found and managed in NAO Cloud in the following page: Left menu of your site > Developers > API Keys
Ex: prod/9NqWWUa0uvYLOJWiWme7b/locs where 9NqWWUa0uvYLOJWiWme7b is the API_key generated by NAO Cloud.
Once subscribed, you will receive all monitoring messages concerning the specified site.
The payload of the message is in Message Pack format, which is like JSON but small and fast. MessagePack is supported by over 50 programming languages and environments so please pick the one that is most convenient for you. Once unpacked, the payload has the following structure:
2 | 'Timestamp': Alert timestamp (UnixTimestamp format in seconds from EPOCH), required, int |
3 | 'SiteID': ID of concerned site, required, int |
4 | 'BleListenerID': ID of concerned gateway, required, string |
5 | 'TrackableID': ID of concerned tag, optional, string |
6 | 'Type': Alert type, required, string |
7 | 'Status': Alert status, optional, string |
8 | 'Value': Value that lead to raising this alert, optional, string |
The possible values for the Type field are: “ACTIVE_GWS”, “LOW_BATTERY_TAGS”, “TAG_TELEMETRY”, “LOGGING_MSG”
The possible values for the Status field are: the level of errors or warnings in case of type “LOGGING_MSG”
BLE Beacons
The beacons telemetry (continuously advertised) is processed through the gateways (3rd party compatible). This feature is currently only available for NAO Bluespot V4 beacons.
Beacon monitoring information can be accessed on the “Infrastructure/BLE beacons/Monitoring” page, or via the REST API.
BLE Listeners
A listener is considered healthy (active) if it has communicated with the server at least once during the last 10 minutes, otherwise it is considered Critical (inactive). For Pole Star NAO BlueListener, this means they will be shown as Healthy as soon as a WebSocket connection can be established. For 3rd party listeners (Aruba, Cisco, …), this means that they will be shown as Healthy as soon as they transmit data from a tag whether it is commissioned on NAO Cloud or not.
Listeners monitoring information can be accessed on the “Infrastructure/BLE listeners/Monitoring” page, or via the REST API.
In addition, the healthy listeners are reported via MQTT every 10 minutes.
Example of message with 2 active listeners:
2 | 'Timestamp': 1519815037, |
5 | 'Value': "112233445566,AABBCCDDEEFF" |
BLE Tags
Pole Star tags can detect that their batteries are low. In that case, they include the information in their telemetry BLE frames that are reported by gateways to the server. Every 10 minutes, the low battery tags are reported via MQTT.
Example of an alert raised when 2 tags are in low battery:
2 | 'Timestamp': 1519815037, |
4 | 'Type': "LOW_BATTERY_TAGS", |
5 | 'Value': "11:22:33:44:55:66,aa:bb:cc:dd:ee:ff" |
In addition, tag monitoring information including current battery level can be accessed on the “Tag tracking/Tracked devices” page (“Telemetry” column), or via the REST API.
Email notifications
Notifications by emails also can be sent to Infrastructure managers of the sites. The email has the following format:
1 | Event: Type - Status (Value) |
2 | Timestamp: Timestamp UTC |
3 | BLE Listener / Gateway: ID of conerned gateway |
5 | Tag / Asset: ID of concerned tag |
The possible values for the Type field are: “GATEWAY_STATUS”
The possible values for the Status field are: “PROBLEM_DETECTED”, “PROBLEM_RESOLVED” and “NO_PROBLEM”
Ex:
1 | Event: GATEWAY_STATUS - PROBLEM_DETECTED (301s) |
2 | Timestamp: 2018-07-10 11:12:10 UTC |
3 | BLE Listener / Gateway: AC233FC0061A |
The notification above says that the system did not receive any information from the gateway “AC233FC0061A” for 301 seconds.
The notification is repeated every hour if the problem persists. Usually, the gateways are able to get back after a short period of time. If the value in seconds exceeds 2 hours which is rare, we might need to take an action to investigate the state of the gateway further.