Overview

The Neuron Monitor plugin is an open source north bound plugin, which, as its name implies, is used for monitoring the Neuron instance. The Monitor plugin is special in that users are not allow to create or delete nodes using the plugin directly, but a singleton monitor node is created for you at startup of the Neuron process. You could see the monitor node in the North Apps tab through the dashboard.

Neuron monitor node
Fig.1 - Neuron monitor node

Parameters

These are the available parameters when configuring the monitor node.

Parameter Description
Client ID MQTT client id for communication, required.
Event Topic Prefix Prefix of the MQTT topics for event reporting, required.
Heartbeat Topic MQTT topic to which heartbeat messages will be published, required.
Heartbeat Interval Interval in seconds between each heartbeat messages. Set to 0 to disable heartbeat messages.
Broker Host MQTT broker host, required.
Broker Port MQTT broker port number, required.
Username MQTT user name, optional.
Password MQTT user password, optional.
SSL Whether to enable MQTT SSL, default false.
CA CA certificate which signs the server certificate, required when SSL enabled.
Client Cert Client certificate, required when using SSL two way authentication.
Client Private Key Client private key, required when using SSL two way authentication.
Client Private Key Password Client private key password, required only when Client Private Key, if provided, is encrypted.

tip These parameters are used only for heartbeats and events reporting, you don’t need to configure the monitor node if you do not use these features.

The Broker Host, Broker Port, Username, Password, SSL, CA, Client Cert, Client Private Key and Client Private Key Password parameters are used to make MQTT connections, which are similar to that of the MQTT plugin. We refer to these 9 parameters as the MQTT connection parameters in the following text.

Metrics

The Neuron Monitor plugin exposes a Prometheus compatible metrics HTTP API. The Neuron dashboard About page and Data statistics tab depends on this API to display certain information.

You may click System Information -> About to show the About page.

Neuron dashboard About page
Fig.2 - Neuron dashboard About page

Click the Data statistics icon on your node to show the Data statistics tab.

Neuron dashboard Data Statistics icon
Fig.3 - Neuron dashboard Data statistics icon

Below is the Data statistics tab, showing the metrics of an example file node.

Neuron dashboard Data Statistics tab example
Fig.4 - Neuron dashboard Data statistics tab

warning NOTE The metrics API is enabled through the life time of the Neuron process. Starting or stopping the monitor node will only start or stop the heartbeats and events functionality.

Heartbeats

The Monitor plugin allows users to publish heartbeat messages to MQTT brokers, which can be used to check the liveness of the Neuron process or node states. Together with the MQTT connection parameters, this feature is controlled by two additional parameters, Heartbeat Topic and Heartbeat Interval. The Heartbeat Topic parameter designates the MQTT topic that the plugin will publish heartbeat messages to. The Heartbeat Interval parameter specifies the interval in seconds between each heartbeat message.

tip Setting the Heartbeat Interval to 0 will disable heartbeat messages.

Heartbeat messages have the following fields:

  • timestamp : the Unix timestamp when the message is generated.
  • version : the Neuron version number.
  • states : array of node states which are similar to that in node state HTTP API.

Bellow is an example heartbeat message.

  1. {
  2.   "timestamp": 1658134132237,
  3.   "version": "2.4.0",
  4.   "states": [
  5.     {
  6.       "node": "mqtt-client",
  7.       "link": 2,
  8.       "running": 3
  9.     },
  10.     {
  11.       "node": "fx5u-client",
  12.       "link": 2,
  13.       "running": 3
  14.     }
  15.   ]
  16. }

Events

Events represent internal state changes of the Neuron process that system administrators or operational engineers may be interested in, such as the creation, removal, or setting of nodes.

The Monitor plugin can publish event messages to MQTT topics determined by the Event Topic Prefix parameter. We use {event-topic-prefix} to denote the actual value provided for the Event Topic Prefix parameter.

Node events

Node creation events

Topic: {event-topic-prefix}/node/add

Example:

  1. {
  2.   "name": "file",
  3.   "plugin": "File"
  4. }

Node removal events

Topic: {event-topic-prefix}/node/delete

Example:

  1. {
  2.   "name": "file"
  3. }

Node setting events

Topic: {event-topic-prefix}/node/setting

Example:

  1. {
  2.   "node": "file",
  3.   "params": {
  4.     "file_length": 512
  5.   }
  6. }

Node control events

Topic: {event-topic-prefix}/node/ctl

Example:

  1. {
  2.   "node": "file",
  3.   "cmd": 1
  4. }

Group events

Group creation events

Topic: {event-topic-prefix}/group/add

Example:

  1. {
  2.   "node": "file",
  3.   "group": "grp",
  4.   "interval": 1000
  5. }

Group update events

Topic: {event-topic-prefix}/group/update

Example:

  1. {
  2.   "node": "file",
  3.   "group": "grp",
  4.   "interval": 2000
  5. }

Group removal events

Topic: {event-topic-prefix}/group/delete

Example:

  1. {
  2.   "node": "file",
  3.   "group": "grp"
  4. }

Tag events

Tag creation events

Topic: {event-topic-prefix}/tag/add

Example:

  1. {
  2.   "node": "file",
  3.   "group": "grp",
  4.   "tags": [
  5.     {
  6.       "name": "tag0",
  7.       "type": 13,
  8.       "attribute": 1,
  9.       "address": "hello.txt",
  10.       "precision": 0,
  11.       "decimal": 0.0,
  12.       "description": ""
  13.     }
  14.   ]
  15. }

Tag update events

Topic: {event-topic-prefix}/tag/update

Example:

  1. {
  2.   "node": "file",
  3.   "group": "grp",
  4.   "tags": [
  5.     {
  6.       "name": "tag0",
  7.       "type": 13,
  8.       "attribute": 3,
  9.       "address": "hello.txt",
  10.       "precision": 0,
  11.       "decimal": 0.0,
  12.       "description": ""
  13.     }
  14.   ]
  15. }

Tag removal events

Topic: {event-topic-prefix}/tag/delete

Example:

  1. {
  2.   "node": "file",
  3.   "group": "grp",
  4.   "tags": [
  5.     "tag0"
  6.   ]
  7. }