Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

Getting a Single Statistic

    +
    The REST API allows cluster-statistics to be retrieved from a single metric.

    HTTP Method and URI

    GET /pools/default/stats/range/<metric_name>/[function-expression]

    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 rate function exposed by this API is the same as the Prometheus rate function.

    • 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 irate function exposed by this API is the same as the Prometheus irate function.

    • increase. The increase in the time series in the range vector.

      The increase function exposed by this API is the same as the Prometheus increase function.

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

    label and val

    Supported labels are of two kinds; which are general and Couchbase-specific.

    General Labels

    The possible specifications and associated values, are as follows.

    • start. The starting timestamp for the sample period, in milliseconds. This value must be specified as a negative integer: the integer represents the number of milliseconds prior to end at which sampling commences. The default value is -60.

    • end. The ending timestamp for the sample period, in milliseconds. The default value is the timestamp of the current time when sampling concludes. Therefore, if start is -60, the default value of end ensures that sampling runs for 60 milliseconds. By contrast, if start is -60 and end is -30, this ensures that sampling runs for 30 milliseconds.

    • step. The interval between successive value-retrievals, over the sample period, in milliseconds. The default is 10. Therefore if step, start, and end all 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 are max, min, sum, and avg. The default is that no aggregation is performed.

    • timeWindow. A time window, such as is required by the functions rate, irate, avg_over_time, and max_over_time; specified in milliseconds. The default value is 1 minute.

    • timeout. The period after which execution times out, in milliseconds. The default is 5 minutes.

    • alignTimestamps. Whether to align timestamps so that each is a multiple of 10 milliseconds. The value can be true or false (which is the default). For example, if the value is false, consecutive timestamps might be 1617274978, 1617274988, and 1617274998; whereas if the value is true, they might be 1617275000, 1617275010, and 1617275020.

    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 specified nodes, bucket, and instance (such as kv, ns_server, or n1ql) from which the returned statistics were derived; and the specific name of the metric (such as kv_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 the node on which an error occurred, and the other the reason for the error.

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