Admin > Metric Dictionary

Review:

• Entities are anything that can provide or generate metrics.
• Models are how you define/describe those entities
  • Models only need to be sent once, unless something changes.
  • If you change the dimensions, you have now created a new entity.
  • Always a good idea to include a name field in the metadataFields
• Source field groups entities and metrics together in dashboards.
  • When a dashboard is created, you select one or more sources.
  • Entities that match those sources become the scope for that dashboard.
  • Only metrics belonging to entities within a dashboard’s scope are displayed by that dashboard’s tiles.

Metrics Dictionary

The Zenoss Cloud metric dictionary contains supplemental information about metrics published through the API and by Collection Zones.

Zenoss cloud uses the metric dictionary for the following features:

• Must have Manager role/permissions to edit the dictionary
• Provide a display name or description for a metric
  • Example: display the name Uptime for metric name uptime_sysUpTime
• Normalize the display of data points in graphs
  • Example: if the data points of a metric are collected and stored as milliseconds, convert their value into seconds before displaying them in graphs.
• Provide a label for the Y-axis of a metric’s graph
  • Example: GB, IOPS or Percent.
• Create guidelines for the minimum and maximum values of a metric’s graph
  • If a data points fall outside of the minimum or maximum values you define, the metric’s graph is automatically adjusted; data points are never discarded.

The Metric Dictionary does NOT modify the actual data.  It only configures the way they are displayed.

Default Metric Dictionary

• Zenoss Cloud includes default definitions for most of the metrics created by Zenoss
• You can override Zenoss default definitions and add definitions for metrics you create
• Any changes to the metric dictionary made by your organization are only visible in your Zenoss Cloud instance (tenant)
• Overriding a Zenoss default definition does NOT delete it or modify it.  The Zenoss definition remains but the custom definition takes precedence and will be used in place of the default definition.
• Deleting Definitions
  • If you delete a custom definition, the default will be restored.
  • If you delete a custom definition where there is no default, it will be completely removed.
  • You cannot delete Zenoss metric definitions.  You can only override them.

Example Definition

Zenoss Defined

"name": "sysUpTime_sysUpTime",
"label": "Uptime",
"description": "The time the system has been running.",
"units": "centiseconds",
"minimum": "0"

Example override

"name": "sysUpTime_sysUpTime",
"label": "System Uptime",
"description": "The time the system has been running.",
"units": "centiseconds",
"minimum": "0"

Field Definitions

• Metric Name: Must exactly match the metric name called used in the JSON "metric": "your-metric-name-here"
• Layer: TENANT or does not exist.
  • Only returned as a field from the API.  You cannot send this.
  • If is included, will be TENANT which signifies the dictionary entry is custom or overridden.
• Label: Friendly name
• Description: User-defined.
• Units: Select from drop down (not working?) – This will be displayed as the Y-Axis label
• Conversion: Select a pre-defined conversion, such as convert bits to megabytes.
• Scale Factor: A floating point multiplier, similar to Conversion but user-defined.
• Minimum and Maximum value:  Defines the default range to display on the graph (vs auto scale).
  • If the value of the metric falls outside of these ranges the actual values will be used as limits.
  • At no time will a metric fall outside of the displayed range, regardless of the range set using these values.
• Tags: Add tags as desired.  Currently only used in Smart View.

Filter Metric Dictionary definitions

• No filter: Display all definitions
• Zenoss default dictionary: Display all default definitions only
• Overridden: Only display definitions that have been custom defined.

Metric Dictionary Shortcut

• You can quickly access a metric’s definition by clicking the options menu icon on a graph.

Metrics Dictionary API Methods

https://help.zenoss.com/dev/zenoss-api/using-the-dictionary-features-of-the-zenoss-api

• BatchGetMetrics
  • Returns the definitions of the specified metrics
  • POST /v1/dictionary/metrics:batchGet
• CreateMetric
  • Create a custom metric definition
  • POST /v1/dictionary/metrics
• DeleteMetric
  • Delete a custom metric definition
  • DELETE /v1/dictionary/metrics/METRIC-NAME
• GetMetric
  • Return the definition for the metric named in the URL
  • GET /v1/dictionary/metrics/METRIC-NAME

$ curl -s -S https://api.zenoss.io/v1/dictionary/metrics/troberts.random.percentage -H "Content-type: application/json" -H "zenoss-api-key: $(cat ~/.zenoss.key)" -X GET
{"name":"troberts.random.percentage","layer":"TENANT","label":"Random Percentage","units":"Percent","minimum":"-30","maximum":"130"}

• ListMetrics
  • Returns all metic dictionary definitions
  • GET /v1/dictionary/metrics
• UpdateMetric
  • Update an existing custom metric definition
  • To override fields in a default dictionary definition, use CreateMetric
  • UpdateMetric replaces the entire custom metric definition
    • Any fields not included in the JSON request will be empty in the new definition
    • Might be a good idea to get the data before using this
  • PATCH /v1/dictionary/metrics/METRIC-NAME

Metric Dictionary API Fields

* Must represent a numeric value