/ 
Monitor-MetricsAPI-0.900
River stage zero No dependents
/ Monitor::MetricsAPI::Server::Routes

NAME

Monitor::MetricsAPI::Server::Routes

SYNOPSIS

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.

DESCRIPTION

The base Dancer2 application which provides HTTP API routes for MetricsAPI.

ROUTES

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.

/all

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.

/metric/**

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.

/metrics/**

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.

OUTPUT STRUCTURE

Unless otherwise noted, all routes return a similar data structure to the one described in this section.

Complete Example

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

Status

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."

Message

Contains a human-readable message, useful for discerning the reason for failed requests. Otherwise easily ignored.

Service

The value of the service attribute is an object containing metadata about the metrics reporting service.

Metrics

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.

AUTHORS

Jon Sime <jonsime@gmail.com>

LICENSE AND COPYRIGHT

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.