Getting Multiple Statistics
The REST API allows cluster-statistics to be retrieved for multiple metrics, in a single call.
Description
This method and URI allow cluster-statistics to be retrieved, based on the specification of one or more metrics. Statistics can be further defined through the specifying of functions; and/or labels with values. Metrics, functions, labels, and values are expressed as an array of JSON objects; which is provided as data accompanying the call.
An instance of Prometheus runs on each node of the cluster; and the metrics for each node are duly stored in that node’s instance of Prometheus.
Curl Syntax
curl -X POST /pools/default/stats/range -d [ <data> ]
Each data
object within the array can contain the following parameters:
{ "metric": [ [ <metric-specification> ], "applyFunctions": [ <function> ], "nodes": [ <node> ], "nodesAggregation": <function>, "start": <start_timestamp>, "end": <end_timestmamp>, "step": <step>, "timeout": <timeout>, "alignTimestamps": true | false ] }
The parameters are as follows:
-
One or more
metric-specification
objects must be provided as an array. Each object takes the following form:
{ "label": <label_name>, "value": <label_val>, "operator": "=" | "!=" | "=~" | "~=" }
The value of the key label
, label_name
, must be a string that specifies how the metric is identified: for example, name
, or proc
.
The value of the key value
, label_val
, must be a string that is the actual name used to identify the metric: for example, sys_cpu_utilization_rate
.
The value of the key "operator"
must be =
, !=
, =~
, or ~=
.
-
applyFunctions.
Can be any of the functions described in the section function, on the page Getting a Single Statistic. -
nodes
. An array each of whose elements is a string whose value is the IP address or domain name of a node in the cluster. If this is not specified, the default is that all nodes are inferred. -
nodesAggregation
. Whether and how aggregation of retrieved statistics is to be performed. Possible values aremax
,min
,sum
, andavg
. The default is that no aggregation is performed. -
start
. The point at which the gathering of metrics commences, specified in seconds as a negative integer. The negative integer-value is added to the current time when execution occurs, so as to derive a historic timestamp. Metrics are then gathered for the time-period that starts at the historic timestamp. If nostart
value is specified, it defaults to-60
. If noend
value is specified, it defaults to the time of execution. -
end
. The point at which the gathering of metrics concludes, specified in seconds as a negative integer. The negative integer-value is added to the current time when execution occurs, so as to derive a historic timestamp. Metrics are then gathered for the time-period that starts at the historic timestamp specified forstart
, and ends at the historic timestamp specified forend
. If noend
value is specified, it defaults to the time of execution. -
step
. The length of the interval that occurs between each statistic-retrieval during the time-period that commences withstart
and concludes withend
, specified as a positive integer. For example, ifstart
is-100
,end
is-40
, andstep
is15
, a statistic is gathered at-100
.-85
,-70
,-55
, and-40
. If no value is specified forstep
, it defaults to10
. -
timeout
. The period after which execution times out, in milliseconds. The default is5
minutes. -
alignTimestamps
. Whether to align timestamps so that each is a multiple of10
milliseconds. The value can betrue
orfalse
(which is the default). For example, if the value isfalse
, consecutive timestamps might be1617274978
,1617274988
, and1617274998
; whereas if the value istrue
, they might be1617275000
,1617275010
, and1617275020
.
Responses
A malformed URI returns 404 Object Not Found
.
Failure to authenticate returns 401 Unauthorized
.
If an internal error causes the call the fail, 500
is returned.
If the URI is correct, and authentication succeeds, the operation is deemd successful.
Success returns 200 OK
, and an object of the following kind.
Note that incorrect specification of metric-name
or function-expression
does not produce execution-failure: indications of errors appear in the returned object.
Examples
The following example returns information on the metrics sysproc_cpu_utilization
(specifying the indexer
process) and kv_disk_write_queue
(specifying the travel-sample
bucket).
Note that the example uses jq, to format the output for readability:
curl -u Administrator:password -X POST http://10.144.210.101:8091/pools/default/stats/range \ -d '[ { "metric": [ {"label": "name", "value": "sysproc_cpu_utilization"}, {"label": "proc", "value": "indexer"} ], "applyFunctions": ["avg"], "alignTimestamps": true, "step": 15, "start": -60 }, { "metric": [ {"label": "name", "value": "kv_disk_write_queue"}, {"label": "bucket", "value": "travel-sample"} ], "applyFunctions": ["sum"], "step": 60, "start": -300 } ]' | jq '.'
If successful, this call returns a JSON array such as the following:
[ { "data": [ { "metric": { "nodes": [ "10.144.210.101:8091" ] }, "values": [ [ 1623745200, "3" ], [ 1623745215, "3" ], [ 1623745230, "3" ], [ 1623745245, "4" ], [ 1623745260, "3" ] ] } ], "errors": [], "startTimestamp": 1623745200, "endTimestamp": 1623745260 }, { "data": [ { "metric": { "nodes": [ "10.144.210.101:8091" ], "name": "kv_disk_write_queue" }, "values": [ [ 1623745200, "0" ], [ 1623745260, "0" ] ] } ], "errors": [], "startTimestamp": 1623744960, "endTimestamp": 1623745260 } ]
See Also
A single statistic can be returned by means of a single call. See Getting a Single Statistic. For a complete list of available metrics that can be queried, see the Metrics Reference.