Monitoring

Monitoring API

Available API Paths

• /api/monitoring/brokers
  
• /api/monitoring/brokers/{brokerId}
  
• /api/monitoring/clusters
  
• /api/monitoring/clusters/{clusterName}
  

---

Path: /api/monitoring/brokers

Methods

GET

Returns the monitoring overview of all the brokers

Responses

Status	Description	Response Content or Scheme
200	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	{ "total": { "description": "Total number of brokers. Length of the \"brokers\" property array", "type": "integer", "format": "int32" }, "brokers": { "type": "array", "items": { "$ref": "#/components/schemas/BrokerInfo" } } }

Example

{
  "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"
      }
    }
  ]
}

Status	Description	Response Content or Scheme
401	Access to resource is denied. User not authenticated (logged in) or session expired	{ "code": { "type": "string", "enum": [ "UNAUTHORIZED" ], "description": "Name of the error" }, "message": { "type": "string", "enum": [ "Unauthorized" ], "description": "Message of the error" } }
403	User does not have enough permissions to access the resource	{ "code": { "type": "string", "enum": [ "NOT_ALLOWED" ], "description": "Name of the error" }, "message": { "type": "string", "enum": [ "Not allowed" ], "description": "Message of the error" } }
404	Plugin is not enabled or not found	{ "code": { "type": "string", "enum": [ "NOT_FOUND" ], "description": "Name of the error" }, "message": { "type": "string", "enum": [ "Plugin not found" ], "description": "Message of the error" } }
410	Requested entity does not exists or was removed	{ "code": { "type": "string", "enum": [ "GONE" ], "description": "Name of the error" }, "message": { "type": "string", "enum": [ "Broker does not exist", "Cluster doesn't exist" ], "description": "Message of the error" } }
500	An internal server error has occured	{ "code": { "type": "string", "enum": [ "SOMETHING_WRONG", "INTERNAL_ERROR" ], "description": "Name of the error" }, "message": { "type": "string", "enum": [ "Something went wrong. Check that cluster-management plugin is enabled", "An internal server error occurred" ], "description": "Message of the error" } }

---

Path: /api/monitoring/brokers/{brokerId}

Methods

GET

Returns the monitoring overview of a signle broker

Parameters

Name	Location	Type	Required	Description
brokerId	path	string	true	Id of the broker which the information is requestsed for

Responses

Status	Description	Response Content or Scheme
200	Contains detailed monitoring information on one single broker	{ "id": { "type": "string", "description": "ID of the broker. Same as brokerId" }, "name": { "type": "string", "description": "Text name of the broker" }, "status": { "type": "object", "required": [ "timestamp", "connected" ], "properties": { "timestamp": { "type": "integer", "format": "int32", "description": "Time when broker was connected to MMC" }, "connected": { "type": "boolean", "description": "Indicates if the broker is connected" }, "error": { "type": "object", "required": [ "code" ], "properties": { "errno": { "type": "integer", "format": "int32" }, "code": { "type": "string", "description": "Error name" }, "syscall": { "type": "string", "description": "Command that failed" }, "address": { "type": "string", "description": "IP address of the broker" }, "port": { "type": "integer", "format": "int32", "description": "Port of the broker connection" } }, "description": "Specifies connection error if any (present only in case of an error)" } } }, "metrics": { "type": "object", "properties": { "version": { "type": "string", "description": "Version of the broker. Static" }, "clients": { "type": "object", "properties": { "total": { "type": "string", "description": "Total number of active and inactive clients currently connected and registered on the broker" }, "active": { "type": "string", "description": "Number of currently connected clients (deprecated)" }, "connected": { "type": "string", "description": "Number of currently connected clients" } } }, "load": { "type": "object", "description": "Moving averages. Contains differnt events with 1min, 5min or 15min averages. The values represent the number of events done in 1 minute, averaged over 1, 5 or 15 minutes", "properties": { "publish": { "type": "object", "properties": { "sent": { "type": "object", "properties": { "1min": { "type": "string" }, "5min": { "type": "string" }, "15min": { "type": "string" } }, "description": "The moving average of the number of publish messages sent by the broker over different time intervals" } } }, "sockets": { "type": "object", "properties": { "15min": { "type": "string" }, "1min": { "type": "string" }, "5min": { "type": "string" } }, "description": "The moving average of the number of socket connections opened to the broker over different time intervals" }, "connections": { "type": "object", "properties": { "15min": { "type": "string" }, "1min": { "type": "string" }, "5min": { "type": "string" } }, "description": "The moving average of the number of CONNECT packets received by the broker over different time intervals" }, "messages": { "type": "object", "properties": { "received": { "type": "object", "properties": { "1min": { "type": "string" }, "5min": { "type": "string" }, "15min": { "type": "string" } }, "description": "The moving average of the number of all types of MQTT messages received by the broker over different time intervals" }, "sent": { "type": "object", "properties": { "1min": { "type": "string" }, "5min": { "type": "string" }, "15min": { "type": "string" } }, "description": "The moving average of the number of all types of MQTT messages sent by the broker over different time intervals" } } }, "bytes": { "type": "object", "properties": { "received": { "type": "object", "properties": { "1min": { "type": "string" }, "5min": { "type": "string" }, "15min": { "type": "string" } }, "description": "The moving average of the number of bytes received by the broker over different time intervals" }, "sent": { "type": "object", "properties": { "1min": { "type": "string" }, "5min": { "type": "string" }, "15min": { "type": "string" } }, "description": "The moving average of the number of bytes sent by the broker over different time intervals" } } } } }, "messages": { "type": "object", "properties": { "stored": { "type": "string", "description": "The number of messages currently held in the message store. This includes retained messages and messages queued for durable clients" }, "received": { "type": "string", "description": "The total number of messages of any type received since the broker started" }, "sent": { "type": "string", "description": "The total number of messages of any type sent since the broker started" } } }, "store": { "type": "object", "properties": { "messages": { "type": "object", "properties": { "count": { "type": "string", "description": "The number of messages currently held in the message store. This includes retained messages and messages queued for durable clients" }, "bytes": { "type": "string", "description": "The number of bytes currently held by message payloads in the message store. This includes retained messages and messages queued for durable clients" } } } } }, "subscriptions": { "type": "object", "properties": { "count": { "type": "string", "description": "The total number of subscriptions active on the broker" } } }, "retained messages": { "type": "object", "properties": { "count": { "type": "string", "description": "The total number of retained messages active on the broker" } } }, "publish": { "type": "object", "properties": { "messages": { "type": "object", "properties": { "sent": { "type": "string", "description": "The total number of PUBLISH messages sent since the broker started" } } }, "bytes": { "type": "object", "properties": { "sent": { "type": "string", "description": "The total number of bytes of PUBLISH messages sent since the broker started" } } } } }, "bytes": { "type": "object", "properties": { "received": { "type": "string", "description": "The total number of bytes received since the broker started" }, "sent": { "type": "string", "description": "The total number of bytes sent since the broker started" } } }, "uptime": { "type": "string", "description": "Uptime of the broker in seconds" } } } }

Example

{
  "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"
  }
}

Status	Description	Response Content or Scheme
401	Access to resource is denied. User not authenticated (logged in) or session expired	{ "code": { "type": "string", "enum": [ "UNAUTHORIZED" ], "description": "Name of the error" }, "message": { "type": "string", "enum": [ "Unauthorized" ], "description": "Message of the error" } }
403	User does not have enough permissions to access the resource	{ "code": { "type": "string", "enum": [ "NOT_ALLOWED" ], "description": "Name of the error" }, "message": { "type": "string", "enum": [ "Not allowed" ], "description": "Message of the error" } }
404	Plugin is not enabled or not found	{ "code": { "type": "string", "enum": [ "NOT_FOUND" ], "description": "Name of the error" }, "message": { "type": "string", "enum": [ "Plugin not found" ], "description": "Message of the error" } }
410	Requested entity does not exists or was removed	{ "code": { "type": "string", "enum": [ "GONE" ], "description": "Name of the error" }, "message": { "type": "string", "enum": [ "Broker does not exist", "Cluster doesn't exist" ], "description": "Message of the error" } }
500	An internal server error has occured	{ "code": { "type": "string", "enum": [ "SOMETHING_WRONG", "INTERNAL_ERROR" ], "description": "Name of the error" }, "message": { "type": "string", "enum": [ "Something went wrong. Check that cluster-management plugin is enabled", "An internal server error occurred" ], "description": "Message of the error" } }

---

Path: /api/monitoring/clusters

Methods

GET

Returns statuses of all the clusters

Responses

Status	Description	Response Content or Scheme
200	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	{ "total": { "type": "integer", "format": "int32", "description": "Total number of clusters returned. Length of \"clusters\" property array" }, "clusters": { "type": "array", "items": { "$ref": "#/components/schemas/ClusterInfo" } } }

Example

{
  "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"
      }
    }
  ]
}

Status	Description	Response Content or Scheme
401	Access to resource is denied. User not authenticated (logged in) or session expired	{ "code": { "type": "string", "enum": [ "UNAUTHORIZED" ], "description": "Name of the error" }, "message": { "type": "string", "enum": [ "Unauthorized" ], "description": "Message of the error" } }
403	User does not have enough permissions to access the resource	{ "code": { "type": "string", "enum": [ "NOT_ALLOWED" ], "description": "Name of the error" }, "message": { "type": "string", "enum": [ "Not allowed" ], "description": "Message of the error" } }
404	Plugin is not enabled or not found	{ "code": { "type": "string", "enum": [ "NOT_FOUND" ], "description": "Name of the error" }, "message": { "type": "string", "enum": [ "Plugin not found" ], "description": "Message of the error" } }
410	Requested entity does not exists or was removed	{ "code": { "type": "string", "enum": [ "GONE" ], "description": "Name of the error" }, "message": { "type": "string", "enum": [ "Broker does not exist", "Cluster doesn't exist" ], "description": "Message of the error" } }
500	An internal server error has occured	{ "code": { "type": "string", "enum": [ "SOMETHING_WRONG", "INTERNAL_ERROR" ], "description": "Name of the error" }, "message": { "type": "string", "enum": [ "Something went wrong. Check that cluster-management plugin is enabled", "An internal server error occurred" ], "description": "Message of the error" } }

---

Path: /api/monitoring/clusters/{clusterName}

Methods

GET

Returns status of a single cluster

Parameters

Name	Location	Type	Required	Description
clusterName	path	string	true	Name of the cluster which the information is requestsed for

Responses

Status	Description	Response Content or Scheme
200	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": { "type": "string", "description": "Name of the cluster" }, "description": { "type": "string", "description": "Description of the cluster" }, "status": { "type": "object", "properties": { "clusterstate": { "type": "string", "description": "active - cluster is active and working; degraded - cluster is active, but not all nodes are healthy; inactive - cluster is inactive", "enum": [ "active", "degraded", "inactive" ] } } }, "details": { "type": "object", "properties": { "nodes": { "type": "array", "description": "Represents nodes/brokers which form a cluster", "items": { "type": "object", "properties": { "address": { "type": "string", "description": "Address of the node" }, "port": { "type": "integer", "format": "int32", "description": "Port used to connect to the node" }, "nodeid": { "type": "integer", "format": "int32", "description": "ID of the node. Node is an abstraction on top of the broker used in cluster" }, "broker": { "type": "string", "description": "ID of the broker. The same as brokerId" }, "leader": { "type": "boolean", "description": "Indicates if node is a " } } } } } } }

Example

{
  "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
      }
    ]
  }
}

Status	Description	Response Content or Scheme
401	Access to resource is denied. User not authenticated (logged in) or session expired	{ "code": { "type": "string", "enum": [ "UNAUTHORIZED" ], "description": "Name of the error" }, "message": { "type": "string", "enum": [ "Unauthorized" ], "description": "Message of the error" } }
403	User does not have enough permissions to access the resource	{ "code": { "type": "string", "enum": [ "NOT_ALLOWED" ], "description": "Name of the error" }, "message": { "type": "string", "enum": [ "Not allowed" ], "description": "Message of the error" } }
404	Plugin is not enabled or not found	{ "code": { "type": "string", "enum": [ "NOT_FOUND" ], "description": "Name of the error" }, "message": { "type": "string", "enum": [ "Plugin not found" ], "description": "Message of the error" } }
410	Requested entity does not exists or was removed	{ "code": { "type": "string", "enum": [ "GONE" ], "description": "Name of the error" }, "message": { "type": "string", "enum": [ "Broker does not exist", "Cluster doesn't exist" ], "description": "Message of the error" } }
500	An internal server error has occured	{ "code": { "type": "string", "enum": [ "SOMETHING_WRONG", "INTERNAL_ERROR" ], "description": "Name of the error" }, "message": { "type": "string", "enum": [ "Something went wrong. Check that cluster-management plugin is enabled", "An internal server error occurred" ], "description": "Message of the error" } }

---