Monitoring templates

Monitoring templates are containers for monitoring configuration. Specifically data sources, thresholds and graphs. A monitoring template must be created to perform periodic collection of data, associate thresholds with that data, or define how that data should be graphed.

Location and binding

Two important concepts in understanding how monitoring templates are used are location and binding. Location is the device class in which a monitoring template is contained. Binding is the device class, device or component to which a monitoring template is bound.

A monitoring template’s location is important because it restricts to which devices the template may be bound. Assume you have a device named widgeter1 in the /Server/ACME/Widgeter device class that as a monitoring template named WidgeterHealth bound. Zenoss will attempt to find a monitoring template named WidgeterHealth in the following places in the following order.

On the widgeter1 device.
In the /Server/ACME/Widgeter device class.
In the /Server/ACME device class.
In the /Server device class.
In the / device class.

The first template that matches by name will be used for the device. No template will be bound if no matching template is found in any of these locations.

It is because of this search up the hierarchy that allows the monitoring template’s location to be used to restrict to which devices it can be bound. For example, by locating our monitoring template in the /Server/ACME device class we make it available to be bound for all devices in /Server/ACME and /Server/ACME/Widgeter, but we also make unavailable to be bound in other device classes such as /Server or /Network/Cisco.

After deciding on the right location for a monitoring template should then decide where it should be bound. Remember that to cause the template to be used it must be bound. This is done by adding the template’s name to the zDeviceTemplates zProperty of a device class. See the following example that shows how to bind the WidgeterHealth monitoring template to the /Server/ACME/Widgeter device class.

zenpack.yaml

name: ZenPacks.acme.Widgeter

device_classes:
  /Server/ACME/Widgeter:
    zProperties:
      zDeviceTemplates:
        - WidgeterHealth

    templates:
      WidgeterHealth: {}

Note that zDeviceTemplates didn’t have to be declared in the ZenPack’s zProperties field because it’s a standard Zenoss zProperty.

Binding templates using zDeviceTemplates is only applicable for monitoring templates that should be bound to devices. For information on how monitoring templates are bound to components, see Classes and relationships.

Alternatives to YAML

It’s possible to create monitoring templates and add them to a ZenPack entirely through the Zenoss web interface. If you don’t have complex or many monitoring templates to create and prefer to click through the web interface, you may choose to create your monitoring templates this way instead of through the zenpack.yaml file.

There are some advantages to defining monitoring templates in YAML.

Using text editor features such as search can be an easier way to make changes than clicking through the web interface.
Having monitoring templates defined in the same document as the zProperties they use, and the device classes they’re bound to can be easier to understand.
Changes made to monitoring templates in YAML are much more diff-friendly than the same changes made through the web interface then exported to objects.xml. For those keeping ZenPack source in version control this can make changes clearer. For the same reason it can also be of benefit when multiple authors are working on the same ZenPack.

If you want to export monitoring templates already created in the web interface to YAML, see the the --dump-templates option of the zenpacklib script.

Adding monitoring templates

To add a monitoring template to zenpack.yaml you must first add the device class where it is to be located. Then within this device class entry you must add a templates field. The following example shows a WidgeterHealth monitoring template being added to the /Server/ACME/Widgeter device class. It also shows that template being bound to the device class by setting zDeviceTemplates.

zenpack.yaml

name: ZenPacks.acme.Widgeter

device_classes:
  /Server/ACME/Widgeter:
    zProperties:
      zDeviceTemplates:
        - WidgeterHealth

    templates:
      WidgeterHealth:
        description: ACME Widgeter monitoring.

        datasources:
          health:
            type: COMMAND
            parser: Nagios
            commandTemplate: "echo OK|percent=100"

            datapoints:
              percent:
                rrdtype: GAUGE
                rrdmin: 0
                rrdmax: 100

        thresholds:
          unhealthy:
            dsnames: [health_percent]
            eventClass: /Status
            severity: Warning
            minval: 90

        graphs:
          Health:
            units: percent
            miny: 0
            maxy: 0

            graphpoints:
              Health:
                dpName: health_percent
                format: "%7.2lf%%"

Many different entry types are shown in the above example. See the references below for more information on each.

Monitoring template fields

The following fields are valid for a monitoring template entry.

name (required, string, default = implied from key in templates map): Name (e.g. WidgeterHealth). Must be a valid Zenoss object ID.
description (optional, string, default = "" (empty string)): Description of the templates purpose and function.
targetPythonClass optional, string, default = "" (equivalent to Products.ZenModel.Device)): Python module name to which this template is intended to be bound (for example, ZenPacks.acme.Widgeter.Widgeter).
datasources (optional, map, default = {} (empty map)): Datasources to add to the template.
thresholds (optional, map, default = {} (empty map)): Thresholds to add to the template.
graphs (optional, map, default = {} (empty map)): Graphs to add to the template.

ZenPackLib also allows for defining a replacement or additional template by adding “-replacement” or “-addition” to the end of the template name. For example, a defined Device-replacement template will replace the existing Device template on a device class. A defined Device-addition template will be applied in addition to the existing Device template on a device class.

Datasource fields

The following fields are valid for a datasource entry.

name (required, string, default = implied from key in datasources map): Name (e.g. health). Must be a valid Zenoss object ID.
type (required, string, default = None): Type of datasource. Must be a valid source type; see Datasource types.
enabled (optional, boolean, default = true): Should the datasource be enabled by default?
component (optional, string, default = "" (empty string)): Value for the component field on events generated by the datasource. Accepts TALES expressions. Default value can vary depending on type.
eventClass (optional, string, default = "" (empty string)): Value for the eventClass field on events generated by the datasource. Default value can vary depending on type.
eventKey (optional, string, default = "" (empty string)): Value for the eventKey field on events generated by the datasource. Default value can vary depending on type.
severity (optional, integer, default = 3): Value for the severity field on events generated by the datasource (0=Clear, 1=Debug, 2=Info, 3=Warning, 4=Error, 5=Critical). Default value can vary depending on type.
cycletime (optional, integer, default = 300): How often the datasource will be executed in seconds. Both the data type and the default value can vary depending on type.
datapoints (optional, map, default = {} (empty map)): Datapoints to add to the datasource.

Datasources also allow other ad-hoc options to be added not referenced in the above list. This is because datasources are an extensible type in Zenoss, and depending on the value of type, other fields may be valid.

Datasource types

The following datasource types are valid on any Zenoss system. They are the default types that are part of the platform. This list is not exhaustive as datasources types are commonly added by ZenPacks.

SNMP

The SNMP datasource type performs an SNMP GET operation using the oid field. The field is required (string) and has no default.

COMMAND

The COMMAND datasource type runs the command in the commandTemplate field.

commandTemplate (required, string, default = None): The command to run.
usessh (optional, boolean, default = false): Run command on bound device using SSH?
parser (optional, string, default = Auto): Parser used to parse output from command. Must be a valid parser name.

PING

The PING datasource type pings (ICMP echo-request) an IP address.

cycleTime (optional, integer, default = 60): How many seconds between ping attempts (note capitalization).
attempts (optional, integer, default = 2): How many ping attempts to perform each cycle.
sampleSize (optional, integer, default = 1): How many echo requests to send with each attempt.

Built-in

The Built-in datasource type performs no collection. It assumes associated data will be populated by an external mechanism.

There are no additional fields.

Custom datasource and datapoint types

Some datasource (and datapoint) types are provided by a particular ZenPack and only available if that ZenPack is installed. These types often have unique parameters that control their function. ZenPackLib allows the specification of these parameters, but the degree of documentation for each varies. As a result, designing YAML templates using these requires a bit of investigation. The available properties depend on the datasource or datapoint type being used. Currently, examination of the related source code is a good way to investigate them, but an alternative is given below.

The following example demonstrates how to create a YAML template that relies on the ZenPacks.zenoss.CalculatedPerformance ZenPack. Please note that the datasource properties used are not documented below, since they are provided by the CalculatedPerformance ZenPack.

First, we want to determine a list of available parameters, and we can use ZenDMD to display them as follows:

## This is the reference class and its properties are documented here.
from Products.ZenModel.RRDDataSource import RRDDataSource as Reference

## replace the import path and class with the class you are interested in
from ZenPacks.zenoss.CalculatedPerformance.datasources.AggregatingDataSource import AggregatingDataSource as Comparison

## this prints out the list of non-standard properties and their types
props = [p for p in Comparison._properties if p not in Reference._properties]
print '\n'.join(['{} ({})'.format(p['id'], p['type']) for p in props])

In this case, we should see the following output:

targetMethod (string)
targetDataSource (string)
targetDataPoint (string)
targetRRA (string)
targetAsRate (boolean)
debug (boolean)

An example template using the CalculatedPerformance datasources might resemble the following:

zenpack.yaml

name: ZenPacks.zenoss.ZenPackLib
device_classes:
  /Device:
    templates:
      ExampleCalculatedPerformanceTemplate:
        datasources:
          # standard SNMP datasources
          memAvailReal:
            type: SNMP
            oid: 1.3.6.1.4.1.2021.4.6.0
            datapoints:
              memAvailReal: GAUGE
          memAvailSwap:
            type: SNMP
            oid: 1.3.6.1.4.1.2021.4.4.0
            datapoints:
              memAvailSwap: GAUGE
          # CalculatedPerformance datasources
          totalAvailableMemory
            type: Calculated Performance
            # "expression" paramter is unique to the
            # CalculatedPerformance datasource
            expression: memAvailReal + memAvailSwap
            datapoints:
              totalAvailableMemory: GAUGE
          # Aggregated Datasource
          agg_out_octets:
            # These are standard parameters
            type: Datapoint Aggregator
            # The following parameters are "extra" parameters,
            # attributes of the "Datapoint Aggregator" datasource
            targetDataSource: ethernetcmascd_64
            targetDataPoint: ifHCOutOctets
            targetMethod: os.interfaces
            # AggregatingDataPoint is subclassed from RRDDataPoint and
            # has the unique "operation" paramter
            datapoints:
              aggifHCOutOctets:
                operation: sum

Further experimentation is required to determine proper values for these properties, and creating templates manually using the Zenoss GUI is a good way to do so.

Datapoint fields

The following fields are valid for a datapoint entry.

name (required, string, default = implied from key in datapoints map): Name (e.g. percent). Must be a valid Zenoss object ID.
description (optional, string, default = "" (empty string)): Description of the datapoint’s purpose and function.
rrdtype (optional, string, default = GAUGE): Type of datapoint. Must be GAUGE or DERIVE.
rrdmin (optional, integer, default = None (no lower bound)): Minimum allowable value that can be written to the datapoint.
rrdmax (optional, integer, default = None (no upper bound)): Maximum allowable value that can be written to the datapoint.
aliases (optional, map<name,formula>, default = {} (empty map)): Analytics aliases for the datapoint with optional RPN calculation.

Datapoints also allow other ad-hoc options to be added not referenced in the above list. This is because datapoints are an extensible type, and depending on the value of the datasource’s type, other fields may be valid.

YAML datapoint specification also supports the use of an alternate “shorthand” notation for brevity. Shorthand notation follows a pattern of RRDTYPE_MIN_X\_MAX_X where RRDTYPE is GAUGE or DERIVE, and the MIN_X/MAX_X parameters are optional.

For example, DERIVE, DERIVE_MIN_0, and DERIVE_MIN_0\_MAX_100 are all valid shorthand notation.

Threshold fields

The following fields are valid for a threshold entry.

name (required, string, default = implied from key in thresholds map): Name (e.g. unhealthy). Must be a valid Zenoss object ID.
type (optional, string, default = MinMaxThreshold): Type of threshold; see Threshold types.
enabled (optional, boolean, default = true): Should the threshold be enabled by default?
dsnames (optional, list, default = [] (empty list)): List of datasource_datapoint combinations to threshold.
eventClass (optional, string, default = /Perf/Snmp (varies by type)): Value for the eventClass field on events generated by the threshold.
severity (optional, integer, default = 3): Value for the severity field on events generated by the threshold (0=Clear, 1=Debug, 2=Info, 3=Warning, 4=Error, 5=Critical). Default value varies depending on type.
optional (optional, boolean, default = false): Set to true will prevent ZenPack installation if type isn't a valid type.

Thresholds also allow other ad-hoc options to be added not referenced in the above list. This is because thresholds are an extensible type in Zenoss, and depending on the value of the threshold’s type, other fields may be valid.

Threshold types

The following threshold types are valid on all systems. They are the default types that are part of the platform. This list is not exhaustive as additional threshold types can be added by ZenPacks.

MinMaxThreshold

The MinMaxThreshold threshold type creates an event if values are below or above specified limits.

minval (optional, string, default = None (no lower bound)): The minimum allowable value. Lesser values raise an event. The value must evaluate to a number and may be a Python expression.
maxval (optional, string, default = None (no upper bound)): The maximum allowable value. Greater values raise an event. The value must evaluate to a number and may be a Python expression.

ValueChangeThreshold

The ValueChangeThreshold threshold type creates an event if the value is different than last time it was collected.

There are no additional fields.

Graph fields

The following fields are valid for a graph entry.

name (required, string, default = implied from key in graphs map): Name (e.g. Health). Must be a valid Zenoss object ID.
description (optional, string, default = "" (empty string)): Description of the graph’s purpose and function.
units (optional, string, default = "" (empty string)): Units displayed on graph. Used as the vertical axis label.
miny (optional, integer, default = -1, which causes the minimum y-axis to float to fit the data): Value for bottom of the vertical axis.
maxy (optional, integer, default = -1, which causes the maximum y-axis to float to fit the data): Value for top of the vertical axis.
log (optional, boolean, default = false): Should the vertical axis be a logarithmic scale?
base (optional, boolean, default = false): Is the plotted data in base 1024 like storage or memory size?
hasSummary (optional, boolean, default = true): Should the graph legend be shown?
height (optional, integer, default = 500): The graph’s height in pixels.
width (optional, integer, default = 500): The graph’s width in pixels.
graphpoints (optional, map, default = {} (empty map)): Graph points to add to the graph.
comments (optional, list, default = [] (empty list)): List of comments to display in the graph’s legend.

Graphpoint fields

The following fields are valid for a graphpoint entry.

name (required, string, default = implied from key in graphpoints map): Name (e.g. Health). Must be a valid Zenoss object ID.
type (optional, string, default = DataPointGraphPoint): Type of graph point; see GraphPoint types.
legend (optional, string, default = name): Label to be shown for this graph point in the legend.
skipCalc (optional, boolean, default = false): Don't scale value in legend - show full value
dpName (required, string, default = None): The datasource_datapoint combination to plot.
lineType (optional, string, default = LINE): How to plot the data: LINE, AREA or DONTDRAW.
lineWidth (optional, integer, default = 1): How thick the line should be for the line type.
stacked (optional, boolean, default = false): Should this graph point be stacked (added) to the last? Ideally both area AREA types.
color (optional, string, default = cycles through preset list): Color for the line. Specified as RRGGBB (e.g. 1f77b4).
colorindex (optional, integer, default = None): Color index for the line. Alternative to specifying color.
format (optional, string, default = %5.2lf%s): String format for this graph point in the legend (e.g. %7.2lf%s).
cFunc (optional, string, default = AVERAGE): Consolidation function. One of AVERAGE, MIN, MAX, LAST.
limit (optional, integer, default = -1): Maximum permitted value. Value larger than this will be nulled. Not used if negative.
rpn (optional, string, default = "" (empty string)): RPN (Reverse Polish Notation) calculation to apply to datapoint.
includeThresholds (optional, boolean, default = false): Should thresholds associated with dpName be automatically added to the graph?
thresholdLegends (optional, map, default = {} (empty map)): Mapping of threshold id to legend (string) and color (RRGGBB).

Graphpoint types

The following graphpoint types are valid on any Zenoss system. They are the default types that are part of the platform. This list is not exhaustive as additional graphpoint types can be added by ZenPacks.

ThresholdGraphPoint

The ThresholdGraphPoint graphpoint type allows a threshold to be plotted and supports the following additional field.

threshId (required, string, default = None): Reference to the id of related threshold.

CommentGraphPoint

The CommentGraphPoint graphpoint type allows a comment to be added to the graph legend and supports the following additional field.

text (required, string, default = None): Comment to be added to graph's legend.