Fetching Active Metrics

If we want to search for what metrics are available in an environment, we can do that using the Metrics page in the app, or we can use the /metrics endpoint. You will need an API token, represented in each example as <API_TOKEN>.

Here’s an example:

curl 'https://app.vividcortex.com/api/v2/metrics?limit=25&from=-3600&host=1&filter=os.disk.*' \
  -H 'Authorization: Bearer <API_TOKEN>' \
  -H 'Accept: application/json' \
  -H 'X-Indent: true'

This will fetch the first 25 metrics begin with os.disk.. The response looks like this:

  "data": [
      "name": "os.disk.dr1.read_sectors",
      "firstSeen": 1448036400,
      "lastSeen": 1462294800
      "name": "os.disk.dr2.bytes_used",
      "firstSeen": 1447170060,
      "lastSeen": 1462294800

The parameters to the request we made above are:

  • limit The number of metrics to fetch in a single request. The API has an internal limit of 20,000. The API will return a response header to indicate if the number of results exceeds the limit specified on a request (or the absolute maximum allowed). Look for the x-vc-meta-more response header; it is a boolean flag that will be set to true in cases where more items can be returned. In this case, use the offset parameter (described below).

  • from The starting time for the request window to fetch metrics for. This can be a relative timestamp or an absolute one. You must include a filter when specifying from.

  • host The ID(s) of the hosts to consider when fetching metrics. This can be a single host, or a list of hosts (e.g. 203,204,205…). You must include a filter when specifying host.

  • filter A wildCarded metric name to match results against, e.g. os.cpu.* will fetch all CPU-related metrics. There are many thousands of metrics being collected, however, so we do not recommend attempting to paginate through all of them without using a filter. If you do not specify a filter the API will not use the host, from, or until options, if provided. For information about the categories of metrics available see our Metrics Documentation.

There are also three more parameters you can use that are omitted from the above example:

  • offset Retrieve metrics after the specified metric name, e.g. if we want the next set of results from the example above we would specify os.disk.dr2.bytes_used, to start returning metrics after that entry. The API indicates if there is more data available for a request with the x-vc-meta-more response header (see the limit parameter above).

  • until The end point for the request window. This can be a relative timestamp or an absolute one. You must include a filter when specifying until.

  • new Set to 1 to indicate that the API should only return metrics that were first seen within the specified interval. This is ignored if from and until are not specified.