action.skip

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

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. The tags namespace is shared among all dictionary types. By convention, this field is used to record the source of an entry.

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 entry.

Fields

Responses include the fields in the following table.

Field Description
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

Gets multiple entries.

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

Fields

Responses include the fields in the following table.

Field Description
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

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

Fields

Responses include the fields in the following table.

Field Description
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}

Updates fields of an existing custom entry.

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

Fields

The name field is required but cannot be changed. The fields you specify replace the existing fields.

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. The tags namespace is shared among all dictionary types. By convention, this field is used to record the source of an entry.

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

{}