Skip to main content
Version: Management Center 2.5

Monitoring REST API ⭐

2.5
Premium


This page describes the first version of the Monitoring REST API of the Mosquitto Management Center (MMC). This API will provide endpoints for retrieving monitoring information about the Mosquitto broker instances that are connected to the Management Center.

info

Monitoring API can be accessed by users with a viewer role and higher. monitroingViewer user has exclusive rights which allow them to access theis REST API only.

API description

Data format

The data format used by the Monitoring REST API is JSON.

Endpoints

Connections

This endpoint will retrieve the status of all brokers.

URL and HTTP methods

  • URL: /api/monitoring/brokers
  • Method: GET

Response payload

The response body contains the overview information of all brokers. Each broker provides additional metrics information like the number of clients connected, the number of subscriptions and the number of messages received and sent.

The response payload has the following structure:

{
"total": 2,
"brokers": [
{
"id": "mosquitto1",
"name": "Mosquitto 1 Test Instance",
"status": {
"timestamp": 1234567,
"connected": false,
"error": {
"errno": -61,
"code": "ECONNREFUSED",
"syscall": "connect",
"address": "127.0.0.1",
"port": 1891
}
}
},
{
"id": "mosquitto2",
"name": "Mosquitto 2 Test Instance",
"status": {
"timestamp": 1234567,
"connected": true
},
"metrics": {
"version": "mosquitto version 2.1.0",
"clients": {
"total": "3",
"active": "1",
"connected": "1"
},
"load": {
"publish": {
"sent": {
"1min": "89.24",
"5min": "37.59",
"15min": "26.32"
}
},
"sockets": {
"15min": "0.87",
"1min": "1.96",
"5min": "0.74"
},
"connections": {
"15min": "0.87",
"1min": "1.96",
"5min": "0.74"
},
"messages": {
"received": {
"1min": "13.69",
"5min": "5.34",
"15min": "3.45"
},
"sent": {
"1min": "106.56",
"5min": "45.82",
"15min": "33.12"
}
},
"bytes": {
"received": {
"1min": "406.86",
"5min": "154.90",
"15min": "124.23"
},
"sent": {
"1min": "3418.76",
"5min": "1371.17",
"15min": "885.65"
}
}
},
"messages": {
"stored": "37",
"received": "195425",
"sent": "1207818"
},
"store": {
"messages": {
"count": "37",
"bytes": "200"
}
},
"subscriptions": {
"count": "7"
},
"retained messages": {
"count": "37"
},
"publish": {
"messages": {
"sent": "1012830"
},
"bytes": {
"sent": "5919457"
}
},
"bytes": {
"received": "17444986",
"sent": "43697617"
},
"uptime": "5367950 seconds"
}
}
]
}

Single Connection

This endpoint will retrieve the status of a single connection.

URL and HTTP methods

  • URL: /api/monitoring/brokers/<broker-id>
  • Method: GET

Response payload

The response body contains the detailed information of one single broker:

{
"id": "mosquitto2",
"name": "Mosquitto 2 Test Instance",
"status": {
"timestamp": 1234567,
"connected": true
},
"metrics": {
"version": "mosquitto version 2.1.0",
"clients": {
"total": "3",
"active": "1",
"connected": "1"
},
"load": {
"publish": {
"sent": {
"1min": "89.24",
"5min": "37.59",
"15min": "26.32"
}
},
"sockets": {
"15min": "0.87",
"1min": "1.96",
"5min": "0.74"
},
"connections": {
"15min": "0.87",
"1min": "1.96",
"5min": "0.74"
},
"messages": {
"received": {
"1min": "13.69",
"5min": "5.34",
"15min": "3.45"
},
"sent": {
"1min": "106.56",
"5min": "45.82",
"15min": "33.12"
}
},
"bytes": {
"received": {
"1min": "406.86",
"5min": "154.90",
"15min": "124.23"
},
"sent": {
"1min": "3418.76",
"5min": "1371.17",
"15min": "885.65"
}
}
},
"messages": {
"stored": "37",
"received": "195425",
"sent": "1207818"
},
"store": {
"messages": {
"count": "37",
"bytes": "200"
}
},
"subscriptions": {
"count": "7"
},
"retained messages": {
"count": "37"
},
"publish": {
"messages": {
"sent": "1012830"
},
"bytes": {
"sent": "5919457"
}
},
"bytes": {
"received": "17444986",
"sent": "43697617"
},
"uptime": "5367950 seconds"
}
}

Clusters

This endpoint will retrieve statuses of all the clusters.

URL and HTTP methods

  • URL: /api/monitoring/clusters
  • Method: GET

Response payload

The response contains a list of all available clusters plus an additional counter. Each cluster information contains the name, the description and a status of the cluster. The latter can be one of:

  • active: the cluster is active and working
  • degraded: the cluster is active, but not all nodes are healthy
  • inactive: the cluster is inactive
{
"total": 3,
"clusters": [
{
"name": "mosquittotests1",
"description": "Mosquitto Test Cluster 1",
"status": {
"clusterstate": "active"
}
},
{
"name": "mosquittotests2",
"description": "Mosquitto Test Cluster 2",
"status": {
"clusterstate": "degraded"
}
},
{
"name": "mosquittotests3",
"description": "Mosquitto Test Cluster 3",
"status": {
"clusterstate": "inactive"
}
},
]
}

Single Cluster

This endpoint will retrieve the status of a single cluster.

URL and HTTP methods

  • URL: /api/monitoring/clusters
  • Method: GET

Response payload

The response body contains the detailed information of one single cluster. For every cluster the same information is included as in the “Clusters” endpoint plus additional detail information, i.e., specific information about each node in the cluster.

{
"name": "mosquittotests1",
"description": "Mosquitto Test Cluster 1",
"status": {
"clusterstate": "active"
},
"details": {
"nodes": [
{
"address": "172.20.1.1",
"port": 7000,
"nodeid": 1,
"broker": "mosquitto1",
"leader": true
},
{
"address": "172.20.1.2",
"port": 7000,
"nodeid": 2,
"broker": "mosquitto2",
"leader": false
},
{
"address": "172.20.1.3",
"port": 7000,
"nodeid": 2,
"broker": "mosquitto3",
"leader": false
}
]
}
}

Authentication

The Monitoring REST API will provide the same authentication mechanism that all other existing REST APIs of the Management Center use. This authentication mechanism is described in the REST API page. You can also use Application Tokens to authenticate described on the separate page as well.

Versioning

In order to be REST compliant the Media Type Versioning will be implemented. This means that the version number will not be included in the URL, but will be provided by the client when accessing the API by the Accept header.

application/json;version=1
application/json;version=2
application/json;version=3

etc.

The first version number will be 1. Whenever in future there is a breaking change to the API a new major version will be released.