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
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
{}