Metric resources

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

Resource list

Create an entry (POST /v1/dictionary/metrics)
Get one entry (GET /v1/dictionary/metrics/{name})
Get multiple entries (POST /v1/dictionary/metrics:batchGet)
Get all entries (GET /v1/dictionary/metrics)
Update an entry (PATCH /v1/dictionary/metrics/{name})
Delete an entry (DELETE /v1/dictionary/metrics/{name})

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

RequestResponse

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

RequestResponse (default)Response (custom)

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

RequestResponse

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

RequestResponse (truncated)

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

RequestResponse

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

RequestResponse

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

{}