Getting Statistics from a Single Metric
The REST API allows cluster-statistics to be retrieved from a single metric.
Description
This method and URI allow cluster-statistics to be retrieved, based on the specification of a single metric. Optionally, the cluster-statistics can be further defined through the specifying of a function; and/or labels with values.
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 GET -u <username:password> \ http://<ip-address-or-domain-name>:<port-number>/pools/default/stats/range/<metric-name>/ [function-expression]
When present, the optional function-expression should take the following form:
[[<function>?][<label>=<val>&]*]
As this indicates, any number of <label>=<val> pairs can be specified, with or without a preceding <function>.
If a function is specified, it is applied to all statistics; if none is specified, all statistics are returned unmodified.
A <function> can be specified with or without one or more <label>=<val> pairs.
If a <function> and at least one <label>=<val> pair are specified, the <function> must be followed with the ? character.
If multiple <label>=<val> pairs are specified, each is separated from the next with the & character.
All syntactic elements are described in the subsections immediately below.
function
The optional function parameter can be specified as follows:
<function> := rate | irate | increase | avg_over_time | min_over_time | max_over_time | deriv | delta | idelta | sum | min | max | avg | p[1-99]
-
rate. The per-second average rate of increase of the time series, over the time window used when retrieving the time series. If the time window is not explicitly specified, it defaults to 1 minute (see the description of the optional timeWindow parameter).The
ratefunction exposed by this API is the same as the Prometheusratefunction. -
irate. The per-second instant rate of increase of the time series in the range vector. This is based on the last two data points.The
iratefunction exposed by this API is the same as the Prometheusiratefunction. -
increase. The increase in the time series in the range vector.The
increasefunction exposed by this API is the same as the Prometheusincreasefunction. -
avg_over_time. The average value over a specified time window. -
min_over_time. The minimum value over a specified time window. -
max_over_time. The maximum value over a specified time window. -
deriv. The per-second derivative of the time series in a range vector, using simple linear regression. -
delta. The difference between the first and last value of each time series element in a range vector, returning an instant vector with the given deltas and equivalent labels. The delta is extrapolated to cover the full time range as specified in the range vector selector, so that it is possible to get a non-integer result even if the sample values are all integers. -
idelta. The difference between the last two samples in the range vector, returning an instant vector with the given deltas and equivalent labels. -
sum. The sum of values retrieved over the sample period. -
min. The minimum value retrieved over the sample period. -
max. The maximum value retrieved over the sample period. -
avg. The average of values retrieved over the sample period. -
p[1-99]The number of results to be displayed per page.
General Labels
The possible specifications and associated values, are as follows.
-
start. The starting timestamp for the sample period, in seconds. This value must be specified as a negative integer: the integer represents the number of milliseconds prior toendat which sampling commences. The default value is-60. -
end. The ending timestamp for the sample period, in seconds. The default value is the timestamp of the current time when sampling concludes. Therefore, ifstartis-60, the default value ofendensures that sampling runs for60milliseconds. By contrast, ifstartis-60andendis-30, this ensures that sampling runs for30milliseconds. -
step. The interval between successive value-retrievals, over the sample period, in seconds. The default is10. Therefore ifstep,start, andendall have their default values, sampling proceeds over six intervals; which are delineated by seven timestamps — these being the starting and ending timestamps, and the five in between. -
nodes. A specific node that is to be queried. If none is specified, all are queried. -
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. -
timeWindow. A time window, such as is required by the functionsrate,irate,avg_over_time, andmax_over_time; specified in milliseconds. The default value is6minutes. -
timeout. The period after which execution times out, in milliseconds. The default is5minutes. -
alignTimestamps. Whether to align timestamps so that each is a multiple of10milliseconds. The value can betrueorfalse(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.
Couchbase-Specific Labels
The possible specifications and associated values, are as follows.
-
bucket. A specific bucket that is to be queried. If none is specified, all are queried. -
scope. A specific scope that is to be queried. If none is specified, all are queried. -
collection. A specific collection that is to be queried. If none is specified, all are queried. -
index. A specific index that is to be queried. If none is specified, all are queried. -
connection_type. A specific connection-type that is to be queried. If none is specified, all are queried.
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.
{
"data": [
{
"metric": <NameAndMetricLabels>,
"values": [
[ <Timestamp>, <Value> ],
...
]
}
],
"errors": [{"node": <NodeName>,
"error": <Reason>}]
"startTimestamp": <Value>,
"endTimestamp": <Value>
}
The value of data is thus an array containing a single object.
Within this object are represented:
-
metric. Values include the specifiednodes,bucket, andinstance(such askv,ns_server, orn1ql) from which the returned statistics were derived; and the specificnameof the metric (such askv_disk_write_queue). -
values. An array of arrays, each of which contains a timestamp and the value collected at that time. -
errors. An array of objects, each of which contains two key-value pairs: one providing the name of thenodeon which an error occurred, and the other the reason for theerror. -
startTimestamp. The timestamp at which information-gathering commenced. -
endTimestamp. The timestamp at which information-gathering ended.
Successful location of a specified repository returns 200 OK and an object containing information on the repository.
If the specified repository is not located, 404 is returned, with the following object: {"status": 404, "msg": "no repositories found"}.
Examples
The following examples demonstrate how the method and URI can be used.
Retrieve CPU Rate
The following expression retrieves the CPU rate for the specified node, using jq to format the output for readability:
curl -v -X GET \ http://10.144.210.101:8091/pools/default/stats/range/sys_cpu_sys_rate \ -u Administrator:password | jq '.'
If successful, the call returns an object such as the following:
{
"data": [
{
"metric": {
"nodes": [
"10.144.210.101:8091"
],
"category": "system",
"instance": "ns_server",
"name": "sys_cpu_sys_rate"
},
"values": [
[
1617698532,
"15.899122807017545"
],
[
1617698542,
"40.451977401129945"
],
[
1617698552,
"25.087514585764293"
],
[
1617698562,
"40"
],
[
1617698572,
"34.420697412823394"
],
[
1617698582,
"39.71238938053097"
],
[
1617698592,
"35.75547866205306"
]
]
}
],
"errors": [],
"startTimestamp": 1617698532,
"endTimestamp": 1617698592
}
Retrieve CPU Rate, with a Metric-Specific Label
The following expression retrieves the sysproc CPU rate for the ns_server process, for the specified node:
curl -v -u Administrator:password -X GET http://10.144.210.101:8091/pools/default/stats/range/\ sysproc_cpu_utilization?proc=ns_server&start=-5 | jq '.'
If successful, the call returns an object such as the following:
{
"data": [
{
"metric": {
"nodes": [
"10.144.210.101:8091"
]
},
"values": [
[
1617698567,
"82486"
],
[
1617698577,
"79234"
],
[
1617698587,
"78214"
],
[
1617698597,
"77824"
],
[
1617698607,
"76826"
],
[
1617698617,
"72067"
],
[
1617698627,
"41213"
]
]
}
],
"errors": [],
"startTimestamp": 1617698567,
"endTimestamp": 1617698627
}
Retrieve Average Value for a Given Metric and Bucket
The following example retrieves the avg value of the kv_disk_write_queue for the bucket travel-sample:
curl -v -X GET \ http://10.144.210.101:8091/pools/default/stats/range/kv_disk_write_queue/\ avg?bucket=travel-sample \ -u Administrator:password | jq '.'
If successful, the call returns an object such as the following:
{
"data": [
{
"metric": {
"nodes": [
"10.144.210.101:8091"
]
},
"values": [
[
1617182615,
"0"
],
[
1617182625,
"0"
],
[
1617182635,
"0"
],
[
1617182645,
"0"
],
[
1617182655,
"0"
],
[
1617182665,
"0"
],
[
1617182675,
"0"
]
]
}
],
"errors": [],
"startTimestamp": 1617182615,
"endTimestamp": 1617182675
}
Get Metric-Rate
The following example uses the irate function to derive the rate of the n1ql_requests metric:
curl -v -u Administrator:password -X GET \ http://10.144.210.101:8091/pools/default/stats/range/n1ql_requests/irate?start=-180&step=60 | jq '.'
If successful, the call returns an object such as the following:
{
"data": [
{
"metric": {
"nodes": [
"10.144.210.101:8091"
],
"instance": "n1ql",
"name": "n1ql_requests"
},
"values": [
[
1617184321,
"0"
],
[
1617184331,
"0"
],
[
1617184341,
"0"
],
[
1617184351,
"0"
],
[
1617184361,
"0"
],
[
1617184371,
"0"
],
[
1617184381,
"0"
],
[
1617184391,
"0"
],
[
1617184401,
"0"
],
[
1617184411,
"0"
],
[
1617184421,
"0"
],
[
1617184431,
"0"
],
[
1617184441,
"0"
],
[
1617184451,
"0"
],
[
1617184461,
"0"
],
[
1617184471,
"0"
],
[
1617184481,
"0"
],
[
1617184491,
"0"
],
[
1617184501,
"0"
]
]
}
],
"errors": [],
"startTimestamp": 1617184321,
"endTimestamp": 1617184501
}
See Also
Multiple statistics can be returned by means of a single call. See Getting Multiple Statistics. For a complete list of available metrics that can be queried, see the Metrics Reference.