search

Using the dictionary features of the Zenoss API

Much of the data that Zenoss Cloud collects from your environment and applications is machine-generated. Often, the meanings of strings or terms used as identifiers are not intuitive. You can use the dictionary feature of the Zenoss API to replace the default identifiers with human-readable content or to provide additional contextual information that is more relevant for your operators. 

This release of the dictionary features of the Zenoss API includes methods for metrics only.

All Zenoss API methods 

  • require a valid Zenoss API key in the zenoss-api-key header
  • expect JSON in the request body (when a body is required)
  • return a JSON response

Metrics

All metrics stored in Zenoss Cloud have names, which vary considerably depending on their source. For example:

Metric names like these may not be enough on their own to allow an operator to understand what their values really represent. For example, you may not know that sysUpTime_sysUpTime is measured in centiseconds (100/sec), or whether k8s.cluster.memory.bytes is the total or used amount of memory in a Kubernetes cluster.

Use the dictionary features of the Zenoss API to define the following additional fields for any metric name:

FieldDescription
labelA short, human-friendly name for a metric.
descriptionA longer, free-form statement about a metric.
units The determinate quality of a metric: percent, bytes, centiseconds, and so on.
minimum The lowest possible value of a metric: 0 for counters, 0 for percentages, and so on.
maximum The highest possible value of a metric: 100 for percentages, and so on.
tags A list of arbitrary terms to associate with a metric.

Zenoss Cloud includes default field definitions for many known metric names, including sysUpTime_sysUpTime and k8s.cluster.memory.bytes. You can override the defaults with your own definitions, create new definitions for metrics not included in the default dictionary, and otherwise manage your custom metric definitions.

Metric methods

The dictionary features of the Zenoss API include the following methods:

ListMetrics (GET /v1/dictionary/metrics)

The ListMetrics method returns a list of all metric definitions in use. This includes all the Zenoss Cloud default definitions (except those you have overridden), and all definitions you have created or overridden.

ListMetrics Status Codes

  • 200 (definitions exist)

ListMetrics Examples

ListMetrics Request
curl https://api.zenoss.io/v1/dictionary/metrics \
  -H "zenoss-api-key: YOUR-API-KEY" \
  -X GET -s
ListMetrics Response
{
  "metrics": [
    {
      "name": "sysUpTime_sysUpTime",
      "label": "Uptime",
      "description": "The time (in hundredths of a second) ...",
      "units": "centiseconds",
      "minimum": "0"
    },
    {
      "name": "k8s.cluster.memory.bytes",
      "label": "Cluster Memory Usage",
      "description": "Total memory bytes used by all containers in the Kubernetes cluster.",
      "units": "bytes",
      "minimum": "0"
    },
    {
      "name": "CPUUtilization_CPUUtilization",
      "label": "CPU Utilization",
      "description": "The percentage of allocated EC2 compute units ...",
      "minimum": "0",
      "maximum": "100"
    }
}

GetMetric (GET /v1/dictionary/metrics/{name})

The GetMetric method returns the definition for a single metric name. If a custom definition has been created for the metric, it will be returned with its layer field set to TENANT. Otherwise the Zenoss Cloud default definition will be returned with no layer field set.

GetMetric Status Codes

  • 200 (definition exists for requested name)
  • 404 (no definition exists for requested name)

GetMetric Examples

GetMetric Request
curl https://api.zenoss.io/v1/dictionary/metrics/sysUpTime_sysUpTime \
  -H "zenoss-api-key: YOUR-API-KEY" \
  -X GET -s
GetMetric Response (Default)
{
  "name": "sysUpTime_sysUpTime",
  "label": "Uptime",
  "description": "The time (in hundredths of a second) ...",
  "units": "centiseconds",
  "minimum": "0"
}
GetMetric Response (Custom)
{
  "name": "sysUpTime_sysUpTime",
  "layer": "TENANT",
  "description": "This had been overridden."
}

BatchGetMetrics (POST /v1/dictionary/metrics:batchGet)

The BatchGetMetrics method returns definitions for more than one metric (where GetMetric works), but not all metrics (where ListMetrics works).

BatchGetMetrics Status Codes

  • 200 (request was good)
  • 400 (no metric names requested)

BatchGetMetrics Examples

BatchGetMetrics Request
curl https://api.zenoss.io/v1/dictionary/metrics:batchGet \
  -H "zenoss-api-key: YOUR-API-KEY" \
  -X POST -s \
  -d '{"names": ["sysUpTime_sysUpTime", "invalid"]}'
BatchGetMetrics Response
{
  "metrics": [
    {
      "name": "sysUpTime_sysUpTime",
      "label": "Uptime",
      "description": "The time (in hundredths of a second) ...",
      "units": "centiseconds",
      "minimum": "0"
    }
  ]
}

CreateMetric (POST /v1/dictionary/metrics)

The CreateMetric method creates a custom metric definition. If the metric name exists in the Zenoss Cloud default dictionary, the custom definition will supercede the default definition. If the custom definition is deleted, the default definition will be restored.

CreateMetric Status Codes

  • 200 (custom definition was created)
  • 400 (no metric name provided)
  • 409 (a custom metric by the same name already exists)

CreateMetric Examples

CreateMetric Request
curl https://api.zenoss.io/v1/dictionary/metrics \
  -H "zenoss-api-key: YOUR-API-KEY" \
  -X POST -s \
  -d '{"name": "sysUpTime_sysUpTime", "label": "Custom Uptime"}'
CreateMetric Response
{
  "name": "sysUpTime_sysUpTime",
  "layer": "TENANT",
  "label": "Custom Uptime"
}

UpdateMetric (PATCH /v1/dictionary/metrics/{name})

The UpdateMetric method updates fields of existing custom metric definitions. To override a definition in the default dictionary, use CreateMetric, which creates a new custom metric.

UpdateMetric Status Codes

  • 200 (custom definition was updated)
  • 404 (no custom definition exists with the requested name)

UpdateMetric Examples

UpdateMetric Request
curl https://api.zenoss.io/v1/dictionary/metrics/sysUpTime_sysUpTime \
  -H "zenoss-api-key: YOUR-API-KEY" \
  -X PATCH -s \
  -d '{"name": "sysUpTime_sysUpTime", "label": "Updated Uptime"}'
UpdateMetric Response
{
  "name": "sysUpTime_sysUpTime",
  "layer": "TENANT",
  "label": "Updated Uptime"
}

DeleteMetric (DELETE /v1/dictionary/metrics/{name})

The DeleteMetric method deletes custom metric definitions. If a default definition exists for the metric name, it will become active again once the custom definition is deleted.

DeleteMetric Status Codes

  • 200 (custom definition was deleted)
  • 404 (no custom definition exists with the requested name)

DeleteMetric Examples

DeleteMetric Request
curl https://api.zenoss.io/v1/dictionary/metrics/sysUpTime_sysUpTime \
  -H "zenoss-api-key: YOUR-API-KEY" \
  -X DELETE -s
DeleteMetric Response
{}