Chapter 13: Statistics Value Retrieval

Home Prev	cOS Core 15.00.01 REST API Guide	Next

This feature of the REST API is to designed to provide retrieval of all or a selected set of the available cOS Core statistical values in real time. This is similar to the capabilities that an SNMP client might provide. The information is sent back by cOS Core in JSON format.

This feature has some overlap with the retrieval described in Chapter 14, Summary Statistics Retrieval but differs in that it can provide all of the several hundred available statistics or a given subset of them.

Retrieving All Available Statistics

To retrieve all of the available statistical values, an HTTP GET should be sent to the following URI with no parameters:

/api/oper/statvalues

Below is an example of the beginning of a typical JSON reply to a GET with no parameters:

{
  "error": false,
  "values": {
    "core/uptime": 157345,
    "core/cpuload": "2.00",
    "core/fwdbps": 0,
    "core/fwdpps": 0,
    "core/bufusage": "45.00",
    "core/conns": 0,
    "core/timers": 64,
    "core/connrate/conn_opened": 0,
           "
           "
           "
  }
}

Adding a Filter

The complete statistics list consists of many hundreds of values and often only a subset of these may be required. To achieve this, the GET can have an optional filter added which requests a single statistic or a comma separated list of statistics. For example:

/api/oper/statvalues?filter=core/uptime,core/cpuload

This would give a truncated version of the previous output:

{
  "error": false,
  "values": {
    "core/uptime": 157345,
    "core/cpuload": "2.00"
  }
}

Showing Extended Details

The GET can return extended information about all or selected statistics by adding the show=extended option. For example:

/api/oper/statvalues?filter=core/uptime,core/cpuload&show=extended

The following example illustrates the extended JSON reply that will be received:

{
  "error": false,
  "values": {
    "core/uptime": {
      "unit": "seconds",
      "description": "Uptime",
      "value": 94
     },
     "core/cpuload": {
       "unit": "%",
       "description": "CPU",
       "value": "5.00"
     }
  }
}

Statistics Filter Names

It should be noted that statistic names fall into one of two categories:

Statistic names that are not configuration dependent

These are the statistics that are available from all cOS Core configurations and do not change across the underlying computing platform. Some examples related to the rate that connections are opened and closed are listed below:
```
core/connrate/conn_opened
core/connrate/conn_closed
core/connrate/conn_replaced
```
Statistic names that are configuration dependent

These are the statistics that depend on the cOS Core configuration or the underlying computing platform. For example, if a particular configuration has an If1 Ethernet interface, the following names will be valid for retrieval of the statistics related to that interface:
```
ifaces/If1/recvpps
ifaces/If1/sentpps
ifaces/If1/totpps
ifaces/If1/recvbps
ifaces/If1/sentbps
ifaces/If1/totbps
ifaces/If1/drops
ifaces/If1/errin
ifaces/If1/sendfails
ifaces/If1/fragsin
ifaces/If1/fragreassok
ifaces/If1/fragreassfail
```

The names of the statistics used for the GET filter have some similarity with the names used in the cOS Core SNMP MIB file. However, not all statistics in the MIB file can be retrieved using the REST API. Conversely, there are some statistics that can be retrieved by the REST API but which cannot be retrieved using SNMP.