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—metric names—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. For more information about the metric dictionary, see Using the metric dictionary.

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


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:

labelA short, human-friendly name for a metric.
descriptionA longer, free-form statement about a metric.

A label describing the data point units, used in the Y-axis label in graphs of the metric.

For example, GB, IOIPs, Percent. If scaleFactor is used, this value should be the units that result from the conversion.

minimum A guideline for the lowest possible value of data points in a graph: 0 for counters, 0 for percentages, and so on.
maximum A guideline for the highest possible value of data points in a graph: 100 for percentages, and so on.

The multiplier in data point conversions, which are only performed for displays like dashboards and Smart View.

For example, 0.01


The units received for a metric and the units to which data points are converted, separated by the hyphen and greater than characters (->).

For example, centiseconds -> seconds.

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:

All Zenoss API methods 

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