Skip to content

Metric dictionary service

The metric dictionary service provides resources for overriding default dictionary entries with your own definitions, creating new entries for metrics not included in the default dictionary, and otherwise managing your custom metric entries.

Resource list

POST /v1/dictionary/metrics

Creates a custom 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.

Fields

The name field is required; all other fields are optional.

Field Description
name The metric name. This field is required and read-only.
label A short name for a metric.
description A longer, free-form statement about a metric.
units 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 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.
scaleFactor The multiplier in data point conversions, which are only performed for displays like dashboards and Smart View. For example, 0.01.
scaleFactorUnits 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.

Status Codes

  • 200 (custom entry was created)
  • 400 (no metric name provided)
  • 409 (a custom entry by the same metric 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 entry.

If a custom entry has been created for the metric, the custom entry is returned with its layer field set to your organization's name. Otherwise the default entry is returned with no layer field.

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

Gets multiple entries.

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

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

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

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}

Updates fields of existing custom entry.

To override an entry in the default dictionary, create a new custom entry.

Fields

The name field is required; all other fields are optional.

Field Description
name The metric name. This field is required and read-only.
label A short name for a metric.
description A longer, free-form statement about a metric.
units 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 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.
scaleFactor The multiplier in data point conversions, which are only performed for displays like dashboards and Smart View. For example, 0.01.
scaleFactorUnits 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.

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}

Deletes a custom 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
{}