Skip to content

Metric resources

Use the metric resources of the dictionary service to override default dictionary entries with your own definitions, create new entries for metrics not included in the default dictionary, and manage custom entries.

Resource list

Authentication

All Zenoss API endpoints require HTTPS, expect JSON in the request body when a body is required, and return a JSON response. You must have an authentication key to send requests to a Zenoss API endpoint. The key is sent in the zenoss-api-key header of each request.

All of the following API examples use curl to send a JSON request from a Bash shell to an endpoint. All examples use YOUR-API-ENDPOINT and YOUR-API-KEY as placeholders for endpoints and authentication keys.

POST /v1/dictionary/metrics

Create a custom metric entry.

If the default dictionary includes an entry for the metric name specified in a create request, the custom entry becomes the effective entry. Subsequently, if the custom entry is deleted, the default entry becomes the effective entry.

Request template

An abstract preview of a JSON request to create one custom metric entry.

{
  "name": "<name>",
  "label": "<label>",
  "description": "<description>",
  "tags": [ "<tag>" ],
  "units": "<units>",
  "minimum": "<minimum>",
  "maximum": "<maximum>",
  "scaleFactor": "<factor>",
  "scaleFactorUnits": "<units>"
}

Request fields

name (string, required)
The metric name.
label (string, optional)
A short name for a metric.
description (string, optional)
A longer, free-form statement about a metric.
tags (array, optional)
A list of arbitrary terms to associate with a metric. The tags namespace is shared among all dictionary types. By convention, this field is used to record the source of an entry.
units (string, optional)

A label describing the data point units, used in the vertical axis label in graphs of the metric. For example, GB, IOIPs, Percent.

If scaleFactor is used, the units value should be the units that result from the conversion.

minimum (string, optional)
A guideline for the lowest possible value of data points in a graph: 0 for counters, 0 for percentages, and so on.
maximum (string, optional)
A guideline for the highest possible value of data points in a graph: 100 for percentages, and so on.
scaleFactor (string, optional)
The multiplier in data point conversions, which are only performed for displays like dashboards and Smart View. For example, 0.01.
scaleFactorUnits (string, optional)
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.

Status Codes

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

Example

curl https://<YOUR-API-ENDPOINT>/v1/dictionary/metrics \
  -H "zenoss-api-key: <YOUR-API-KEY>" \
  -X POST -s \
  -d '{
  "name": "sysUpTime_sysUpTime",
  "label": "Custom Uptime"
}'

{
  "name": "sysUpTime_sysUpTime",
  "layer": "YOUR-ORGANIZATION-NAME",
  "label": "Custom Uptime"
}

GET /v1/dictionary/metrics/{name}

Get one metric entry.

Response fields

layer
DEFAULT for Zenoss-defined entries or TENANT for entries defined by a user in your organization.
default
null for Zenoss-defined entries or an object containing the default value of a Zenoss-defined entry that has been overridden by a user in your organization.

Status Codes

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

Example

curl https://<YOUR-API-ENDPOINT>/v1/dictionary/metrics/sysUpTime_sysUpTime \
  -H "zenoss-api-key: <YOUR-API-KEY>" \
  -X GET -s

{
  "name": "sysUpTime_sysUpTime",
  "label": "Uptime",
  "description": "The time (in hundredths of a second) ...",
  "units": "centiseconds",
  "minimum": "0"
}

{
  "name": "sysUpTime_sysUpTime",
  "layer": "<YOUR-ORGANIZATION-NAME>",
  "description": "This has been overridden."
}

POST /v1/dictionary/metrics:batchGet

Get multiple metric entries.

Specify the list of entries to get with the name field.

Response fields

layer
DEFAULT for Zenoss-defined entries or TENANT for entries defined by a user in your organization.
default
null for Zenoss-defined entries or an object containing the default value of a Zenoss-defined entry that has been overridden by a user in your organization.

Status Codes

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

Example

curl https://<YOUR-API-ENDPOINT>/v1/dictionary/metrics:batchGet \
  -H "zenoss-api-key: <YOUR-API-KEY>" \
  -X POST -s \
  -d '{
  "names": [
    "ClusterInfo_pendingTasksCount",
    "ClusterInfo_runningTasksCount"
  ]
}'

{
  "metrics": [
    {
      "name": "ClusterInfo_pendingTasksCount",
      "label": "Pending Tasks",
      "description": "The number of tasks in the cluster that are in the PENDING state.",
      "units": "count",
      "minimum": "0"
    },
    {
      "name": "ClusterInfo_runningTasksCount",
      "label": "Running Tasks",
      "description": "The number of tasks in the cluster that are in the RUNNING state.",
      "units": "count",
      "minimum": "0"
    }
  ]
}

GET /v1/dictionary/metrics

Get all effective metric entries. This includes all default entries (except those you have overridden) and all entries you have created or overridden.

Response fields

layer
DEFAULT for Zenoss-defined entries or TENANT for entries defined by a user in your organization.
default
null for Zenoss-defined entries or an object containing the default value of a Zenoss-defined entry that has been overridden by a user in your organization.

Status Codes

  • 200 (entries exist)

Example

curl https://<YOUR-API-ENDPOINT>/v1/dictionary/metrics \
  -H "zenoss-api-key: <YOUR-API-KEY>" \
  -X GET -s

{
  "metrics": [
    {
      "name": "ActiveConnectionCount_ActiveConnectionCount",
      "label": "Active Connection Count",
      "description": "The total number of concurrent TCP connections active from clients to the load balancer and from the load balancer to targets.\n\nSource: AWS CloudWatch\nNamespace: AWS/ApplicationELB\nMetric: ActiveConnectionCount",
      "units": "connections",
      "minimum": "0"
    },
    {
      "name": "ActiveFlowCount_ActiveFlowCount",
      "label": "Active Flow Count",
      "description": "The total number of concurrent flows (or connections) from clients to targets. This metric includes connections in the SYN_SENT and ESTABLISHED states. TCP connections are not terminated at the load balancer, so a client opening a TCP connection to a target counts as a single flow.\n\nSource: AWS CloudWatch\nNamespace: AWS/NetworkELB\nMetric: ActiveFlowCount",
      "units": "flows",
      "minimum": "0"
    },
    {
      "name": "ActiveTransactions_ActiveTransactions",
      "label": "Active Transactions",
      "description": "Active Transactions",
      "units": "transactions",
      "minimum": "0"
    },
    .
    .
    .
  ],
  "totalCount": "1604"
}

PATCH /v1/dictionary/metrics/{name}

Update an existing custom metric entry.

To override a default entry, create a new custom entry.

Request fields

Update requests use the same fields as create requests. The name field is required but cannot be changed.

Status Codes

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

Example

curl https://<YOUR-API-ENDPOINT>/v1/dictionary/metrics/sysUpTime_sysUpTime \
  -H "zenoss-api-key: <YOUR-API-KEY>" \
  -X PATCH -s \
  -d '{
  "name": "sysUpTime_sysUpTime",
  "label": "Updated Uptime"
}'

{
  "name": "sysUpTime_sysUpTime",
  "layer": "YOUR-ORGANIZATION-NAME",
  "label": "Updated Uptime"
}

DELETE /v1/dictionary/metrics/{name}

Delete a custom metric entry.

If a default entry exists for the specified name, the default entry becomes the effective entry.

Status Codes

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

Example

curl https://<YOUR-API-ENDPOINT>/v1/dictionary/metrics/sysUpTime_sysUpTime \
  -H "zenoss-api-key: <YOUR-API-KEY>" \
  -X DELETE -s

{}