diff --git a/doc/rest-api/Administration-backend_swagger.yml b/doc/rest-api/Administration-backend_swagger.yml index 7e22bdbe4d..a992240f9e 100644 --- a/doc/rest-api/Administration-backend_swagger.yml +++ b/doc/rest-api/Administration-backend_swagger.yml @@ -663,11 +663,7 @@ paths: description: The bin has been cleaned. The number of rows removed is returned as the body. /inbox/{hostType}/{days}/bin: parameters: - - name: hostType - in: path - description: A host type where inbox is configured - required: true - type: string + - $ref: '#/parameters/hostType' - $ref: '#/parameters/days' delete: tags: @@ -803,6 +799,155 @@ paths: description: "Other errors." examples: application/json: {"what": "database error"} + /metrics/: + get: + description: Returns a list of host type names and metric names + tags: + - "Metrics" + responses: + 200: + description: Host type names and metric names. + schema: + type: object + properties: + host_types: + schema: + type: array + items: + type: string + example: + - "localhost" + metrics: + schema: + type: array + items: + type: string + example: + - "xmppErrorIq" + - "xmppPresenceReceived" + - "xmppMessageBounced" + global: + schema: + type: array + items: + type: string + example: + - "nodeSessionCount" + - "totalSessionCount" + - "uniqueSessionCount" + /metrics/all: + get: + description: Returns a list of metrics aggregated for all host types + tags: + - "Metrics" + responses: + 200: + description: Metrics + schema: + type: object + properties: + metrics: + type: object + example: + modRosterPush: + one: 0 + count: 0 + /metrics/all/{metric}: + parameters: + - $ref: '#/parameters/metric' + get: + description: Returns the metric value aggregated for all host types + tags: + - "Metrics" + responses: + 200: + description: Aggregated metric value + schema: + type: object + properties: + metric: + type: object + example: + one: 0 + count: 0 + 404: + description: There is no such metric + /metrics/host_type/{hostType}: + parameters: + - $ref: '#/parameters/hostType' + get: + description: Returns the values of all host-type metrics + tags: + - "Metrics" + responses: + 200: + description: Metrics + schema: + type: object + properties: + metrics: + type: object + example: + modRosterPush: + one: 0 + count: 0 + 404: + description: There is no such host type + /metrics/host_type/{hostType}/{metric}: + parameters: + - $ref: '#/parameters/hostType' + - $ref: '#/parameters/metric' + get: + description: Returns the value of a host-type metric + tags: + - "Metrics" + responses: + 200: + description: Metric value + schema: + type: object + properties: + metric: + type: object + example: + one: 0 + count: 0 + 404: + description: There is no such metric + /metrics/global: + get: + description: Returns the values of all global metrics + tags: + - "Metrics" + responses: + 200: + description: Metrics + schema: + type: object + properties: + type: object + example: + nodeUpTime: + value: 6604 + /metrics/global/{metric}: + parameters: + - $ref: '#/parameters/metric' + get: + description: Returns the value of a global metric + tags: + - "Metrics" + responses: + 200: + description: Metric value + schema: + type: object + properties: + metric: + type: object + example: + value: 6604 + 404: + description: There is no such global metric parameters: MUCServer: @@ -818,7 +963,12 @@ parameters: description: The XMPP host served by the server. required: true type: string - format: hostname + hostType: + name: hostType + in: path + description: Host type configured on the server + required: true + type: string roomName: name: roomName in: path @@ -837,6 +987,12 @@ parameters: description: Number of days for an entry to be considered old enough to be removed, zero allowed (which clears all) required: true type: integer + metric: + name: metric + description: Metric name + in: path + required: true + type: string definitions: messageList: diff --git a/doc/rest-api/Metrics-backend.md b/doc/rest-api/Metrics-backend.md deleted file mode 100644 index 57c58b9d61..0000000000 --- a/doc/rest-api/Metrics-backend.md +++ /dev/null @@ -1,136 +0,0 @@ -## Introduction - -!!! Warning - This API is considered obsolete. - Please use [WombatOAM](https://www.erlang-solutions.com/capabilities/wombatoam/) for monitoring or one of the [exometer reporters](../operation-and-maintenance/Logging-&-monitoring.md#monitoring) and your favourite statistics service. - -To expose MongooseIM metrics, an adequate endpoint must be included in the [listen](../configuration/listen.md) -section of `mongooseim.toml`. The specific configuration options are described in -the [metrics API handlers](../configuration/listen.md#handler-types-metrics-api-obsolete-mongoose_api) -section. - -An example configuration: - -```toml -[[listen.http]] - port = 5288 - transport.num_acceptors = 5 - transport.max_connections = 10 - - [[listen.http.handlers.mongoose_api]] - host = "localhost" - path = "/api" - handlers = ["mongoose_api_metrics"] -``` - -If you'd like to learn more about metrics in MongooseIM, please visit [MongooseIM metrics](../operation-and-maintenance/MongooseIM-metrics.md) page. - -### Security notice - -An auth mechanism is available only for the new administration API. -That's why we recommend to expose this API only using a private interface or a port hidden behind a firewall to limit the access to the API. -The above configuration starts the API only on a loopback interface. - -## Response format - -The responses are composed in a JSON format with a root element containing one or more attributes as response elements. - -Example response: -```json -{ - "hosts": [ - "localhost" - ], - "metrics": [ - "xmppErrorIq", - "xmppPresenceReceived", - "xmppMessageBounced", - (...) - ], - "global": [ - "nodeSessionCount", - "totalSessionCount", - "uniqueSessionCount", - (...) - ] -} -``` - -## Services - -### GET /api/metrics - -Returns ```200 OK``` and two elements: - -* `host_types` - A list of host type names available on the server. -* `metrics` - A list of per-host metrics. -* `global` - A list of global metrics. - -### GET /api/metrics/all - -Returns ```200 OK``` and an element: - -* `metrics` - A list of aggregated (sum of all domains) per host type metrics with their values. - -### GET /api/metrics/all/:metric - -On success returns ```200 OK``` and an element: - -* `metric` - An aggregated (sum of all domains) per host type metric. - -Returns ```404 Not Found``` when metric `:metric` doesn't exist. - -### GET /api/metrics/host_type/:host_type - -On success returns ```200 OK``` and an element: - -* `metrics` - A list of per host type metrics and their values for host_type `:host_type`. - -Returns ```404 Not Found``` when host_type `:host_type` doesn't exist. - -### GET /api/metrics/host_type/:host_type/:metric - -On success returns ```200 OK``` and an element: - -* `metric` - A per host type metric `:metric` and its value for host_type `:host_type`. - -Returns ```404 Not Found``` when the pair (host_type `:host_type`, metric `:metric`) doesn't exist. - -### GET /api/metrics/global - -On success returns ```200 OK``` and an element: - -* `metrics` - A list of all global metrics and their values. - -### GET /api/metrics/global/:metric - -On success returns ```200 OK``` and an element: - -* `metric` - A global metric `:metric` and its value. - -Returns ```404 Not Found``` when metric `:metric` doesn't exist. - -## collectd integration - -The interface is compatible with the collectd curl_json plugin. -Data fetched by collectd may be later visualized by tools like Graphite. - -Here's an example of a collectd configuration entry that will fetch all available metrics for a given host: -```json -LoadPlugin curl_json -... - - :/api/metrics/host/"> - Instance "mongooseim" - - Type "absolute" - - - Type "absolute" - - - Type "absolute" - - - -``` diff --git a/doc/rest-api/Metrics-backend_swagger.yml b/doc/rest-api/Metrics-backend_swagger.yml deleted file mode 100644 index e69de29bb2..0000000000