Monitor::MetricsAPI::Server::Routes
You should not interact with this module directly in your code. Please refer to Monitor::MetricsAPI for how to integrate this service with your application.
The base Dancer2 application which provides HTTP API routes for MetricsAPI.
The following routes are provided by this server for viewing the collected metrics.
Returns a small JSON structure with metadata about the metrics collector. May be used as a heartbeat for the service, as it performs no computations and does not invoke any metrics callbacks.
Returns a full export of all metrics that have been configured in the containing application. This will include the invoking of all callback metrics. Depending on your metrics collection, this can be a computationally expensive process.
If you have any non-trivial callback metrics collected by your application, you should exercise care in your calls to this route.
Returns a single named metric, instead of the entire collection of metrics. The use of this route is substantially preferred for monitoring systems which use checks against individual metrics, as it limits the invocations of potentially expensive callback metrics (assuming your application configures any).
A complete metric name must be provided. For returning groups of metrics under a common namespace, use the /metrics/ route instead.
Returns a collection of metrics under the given namespace. Each component of the namespace prefix you wish to return must be fully specified, but you can select as deep or as shallow a namespace as you like. In other words, if you have the following metrics:
messages/incoming/total messages/incoming/rejected messages/outgoing/total messages/outgoing/supressed users/total
And your monitoring application calls this service with the following path:
/metrics/messages/outgoing
Then this route will return two metrics:
messages/outgoing/total messages/outgoing/supressed
But if you try to call this service with:
/metrics/messages/out
You will receive an error response.
If you specify the full name of a single metric, you will receive only that metric back in the response output. Given that, why would you ever use the "/metric/**" route over this one? Using the single-metric route when you truly only want a single metric will return an error if the name you give is a namespace instead of a single metric. It is possible this may be useful in some circumstances.
Unless otherwise noted, all routes return a similar data structure to the one described in this section.
{ "status": "ok", "message: "Request processed successfully.", "service": { "name": "Monitor::MetricsAPI", "version": "0.001", }, "metrics": { "messages": { "incoming": { "total": 5019, "rejected": 104 }, "outgoing": { "total": 1627, "suppressed": 5 }, }, "users": { "total": 1928 } } }
The status attribute is present in every response, and anything other than the string "ok" indicates an error condition. Responses with a non-"ok" status may not contain any additional attributes beyond a message which will contain an error message.
Note that the API server will still return an HTTP status code of 200 even when there is an error displaying your metrics (e.g. you have requested a metric which does not exist). The HTTP status codes are used only for indicating whether the HTTP server itself is functioning properly and is able to process the incoming HTTP request. HTTP status codes are not overloaded to also serve as indicators of metrics "health."
Contains a human-readable message, useful for discerning the reason for failed requests. Otherwise easily ignored.
The value of the service attribute is an object containing metadata about the metrics reporting service.
The metrics attribute contains an object of all metrics which matched the request, nested according to the categories you used when defining your metrics. In the case of requests to the "/all" route, this will be every metric collected by the service for your application. For both the "/metric" and "/metrics" routes, only those metrics which matched your request will appear in the object, and all others will be omitted from the output. Callback metrics which are not present in the API output are not invoked when constructing the response.
The data type of each metric's value will depend on the type of metric that is being collected. Counters and gauges will return numbers, boolean metrics will return 1 (true), 0 (false), or null, and string metrics will return, well, strings. Callback metrics can return any type, entirely dependent upon what the subroutine you provided for the callback does. List metrics will return an array containing values of whatever type was push()'ed onto the list within your application.
Jon Sime <jonsime@gmail.com>
This software is copyright (c) 2015 by OmniTI Computer Consulting, Inc.
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
To install Monitor::MetricsAPI, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Monitor::MetricsAPI
CPAN shell
perl -MCPAN -e shell install Monitor::MetricsAPI
For more information on module installation, please visit the detailed CPAN module installation guide.