Fetching Data for a Metric

If we want to see the data for a specfic metric (or metrics), we can use the /metrics/series endpoint. You will need an API token, represented in each example as <API_TOKEN>.

Here is a sample request:

curl 'https://app.vividcortex.com/api/v2/metrics/series?from=1462377347&host=203&metrics=os.cpu.user_us&samplesize=4&until=1462380947' \
-H 'Authorization: Bearer <API_TOKEN>' \
-H 'Accept: application/json' \
-H 'X-Indent: true'

Which gives a response like this:

{
"data": [
    {
      "total": 1,
      "elements": [
        {
          "rank": 1,
          "metric": "os.cpu.user_us",
          "series": [
            7500,
            5000,
            7500, ...

Each requested metric is returned as its own element, with the metric name and series. The series is expressed as an array of values for the time-interval that was requested; no timestamps are returned from the API.

Let’s take a look at the parameters that were passed to the request:

  • from/until: The begin/end timestamps to retrieve series data for. Unlike other endpoints, these must be absolute times and not relative.
  • samplesize: This specifies the resolution to request data at. The series returned will have values interpolated, so every (samplesize) seconds of data will be represented as a single value in the response. Valid samplesizes are currently restricted to a factor of 60, so if you specify a samplesize that is not a valid factor, it will be rounded to the nearest valid sampleSize.
  • host: The ID(s) to retrieve the specified metrics for; can be a single ID or a comma-separated list.
  • metrics: The list of metrics to retrieve series for. This can be an explicit metric name as above, a list of names, or a template that resolves into a list. For instance, os.cpu.* would retrieve all metrics with the os.cpu. prefix; we could use os.cpu.user_us|sys_us if we want just user and system time. This form is essentially equivalent to retrieving os.cpu.user_us,os.cpu.sys_us. Note that templates of the following form are not permitted: os.cpu|disk.*; you cannot combine a * and a | in a single template.

There are a few additional parameters not shown in the example above:

  • separatehosts: Specify 1 for this parameter to split the response for a given request, so that each host has its own series. By default, querying a series for multiple hosts will return an aggregated response.
  • rank: When specifying a metrics parameter with a wildcard (e.g. os.cpu.*), specify rank=1 to have the responses returned in descending order based on the sum value of each series.
  • limit: Only return the first N series that match the metric template, rather than all matches.