search

Monitoring Templates

Monitoring templates are containers for monitoring configuration. Specifically datasources, 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 a 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.

  1. On the widgeter1 device.
  2. In the /Server/ACME/Widgeter device class.
  3. In the /Server/ACME device class.
  4. In the /Server device class.
  5. 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. See Classes and Relationships for information on how monitoring templates are bound to components.

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.

See Command Line Reference for information on the --dump-templates option if you’re interested in exporting monitoring templates already created in the web interface to YAML.

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.

NameDescriptionRequiredTypeDefault Value
nameName (e.g. WidgeterHealth). Must be a valid Zenoss object ID.yesstring(implied from key in templates map)
descriptionDescription of the templates purpose and function.nostring"" (empty string)
targetPythonClass

Python module name to which this template is intended to be bound.
(e.g. ZenPacks.acme.Widgeter.Widgeter)

nostring"" (empty string is equivalent to Products.ZenModel.Device)
datasourcesDatasources to add to the template.nomap<name, Datasource>

{} (empty map)

thresholdsThresholds to add to the template.nomap<name, Threshold>{} (empty map)
graphsGraphs to add to the template.nomap<name, Graph>{} (empty map)


ZenPackLib also allows for defining a replacement or additional template by adding “-replacement” or “-additional” 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.

NameDescriptionRequiredTypeDefault Value
nameName (e.g. health). Must be a valid Zenoss object ID.yesstring(implied from key in datasources map)
typeType of datasource. See Datasource Types.yesstring (must be a valid source type)None. Must be specified.
enabledShould the datasource be enabled by default?nobooleantrue
componentValue for the component field on events generated by the datasource.
Accepts TALES expressions.
nostring"" (empty string)

can vary depending on type

eventClassValue for the eventClass field on events generated by the datasourcenostring"" (empty string)
can vary depending on type
eventKeyValue for the eventKey field on events generated by the datasource.nostring

"" (empty string)
can vary depending on type

severityValue for the severity field on events generated by the datasource.nointeger3 (0=Clear, 1=Debug, 2=Info, 3=Warning, 4=Error, 5=Critical)
can vary depending on type
cycletimeHow often the datasource will be executed in seconds.nointeger
can vary depending on type
300
can vary depending on type
datapointsDatapoints to add to the datasource.nomap<name, Datapoint>{} (empty map)

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.

Additional Fields
NameDescriptionRequiredTypeDefault Value
oidThe SNMP OID to get.yesstringNone. Must be specified.
COMMAND

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

Additional Fields
NameDescriptionRequiredTypeDefault Value
commandTemplateThe command to run.yesstringNone. Must be specified.
usesshRun command on bound device using SSH?nobooleanfalse
parserParser used to parse output from command.nostring (must be a valid parser name)Auto
PING

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

Additional Fields
NameDescriptionRequiredTypeDefault Value
cycleTimeHow many seconds between ping attempts. (note capitalization)nointeger60
attemptsHow many ping attempts to perform each cycle.nointeger2
sampleSizeHow many echo requests to send with each attempt.nointeger1

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

NameDescriptionRequiredTypeDefault Value
nameName (e.g. percent). Must be a valid Zenoss object ID.yesstring(implied from key in datapoints map)
descriptionDescription of the datapoint’s purpose and function.nostring"" (empty string)
rrdtypeType of datapoint. Must be GAUGE or DERIVE.nostring (must be either GAUGE or DERIVE)GAUGE
rrdminMinimum allowable value that can be written to the datapoint.nointegerNone (no lower-bound)
rrdmaxMaximum allowable value that can be written to the datapoint.nointegerNone (no upper-bound)
aliasesAnalytics aliases for the datapoint with optional RPN calculation.nomap<name, formula>{} (empty map)

Datapoints also allow other ad-hoc options to be added not referenced in the above list. This is because datapoints are an extensible type in Zenoss, 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.

NameDescriptionRequiredTypeDefault Value
nameName (e.g. unhealthy). Must be a valid Zenoss object ID.yesstring(implied from key in thresholds map)
typeType of threshold. See Threshold Types.nostring (must be a valid threshold type)MinMaxThreshold
enabledShould the threshold be enabled by default?nobooleantrue
dsnamesList of datasource_datapoint combinations to threshold.nolist

[] (empty list)

eventClassValue for the eventClass field on events generated by the threshold.nostring/Perf/Snmp
varies depending on type
severityValue for the severity field on events generated by the threshold.nointeger3 (0=Clear, 1=Debug, 2=Info, 3=Warning, 4=Error, 5=Critical)
varies depending on type
optionalSet to true will prevent ZenPack installation if type isn't a valid type.nobooleanfalse

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 any Zenoss system. 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.

Additional Fields
NameDescriptionRequiredTypeDefault Value
minvalThe minimum allowable value. Values below this will raise an event.nostring (must evaluate to a number)
accepts Python expressions
None (no lower-bound)
maxvalThe maximum allowable value. Values above this will raise an event.nostring (must evaluate to a number)
accepts Python expressions

None (no upper-bound)

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.

NameDescriptionRequiredTypeDefault Value
nameName (e.g. Health). Must be a valid Zenoss object ID.yesstring(implied from key in graphs map)
descriptionDescription of the graph’s purpose and function.nostring"" (empty string)
unitsUnits displayed on graph. Used as the y-axis label.nostring"" (empty string)
minyValue for bottom of y-axisnointeger-1 (-1 causes the minimum y-axis to float to fit the data)
maxyValue for top of y-axis.nointeger-1 (-1 causes the maximum y-axis to float to fit the data)
logShould the y-axis be a logarithmic scale?nobooleanfalse
baseIs the plotted data in base 1024 like storage or memory size?nobooleanfalse
hasSummaryShould the graph legend be shown?nobooleantrue
heightThe graph’s height in pixels.nointeger500
widthThe graph’s width in pixels.nointeger500
graphpointsGraphpoints to add to the graph.nomap<name, Graphpoint>{} (empty map)
commentsList of comments to display in the graph’s legend.nolist<string>

[] (empty list)

Graphpoint Fields

The following fields are valid for a graphpoint entry.

NameDescriptionRequiredTypeDefault Value
nameName (e.g. Health). Must be a valid Zenoss object ID.yesstring(implied from key in graphpoints map)
typeType of graphpoint. See GraphPoint Types.nostringDataPointGraphPoint
legendLabel to be shown for this graphpoint in the legend.nostringname field value.
dpNamedatasource_datapoint combination to plot.yesstringNone.
lineTypeHow to plot the data: LINE, AREA or DONTDRAWnostringLINE
lineWidthHow thick the line should be for the line type.nointeger1
stackedShould this graphpoint be stacked (added) to the last? Ideally both area AREA types.nobooleanfalse
colorColor for the line. Specified as RRGGBB (e.g. 1f77b4).nostringCycles through preset list.
colorindexColor index for the line. Alternative to specifying color.nointegerNone
formatString format for this graphpoint in the legend (e.g. %7.2lf%s).nostring%5.2lf%s
cFuncConsolidation function. One of AVERAGE, MIN, MAX, LAST.nostringAVERAGE
limitMaximum permitted value. Value larger than this will be nulled. Not used if negative.nointeger-1
rpnRPN (Reverse Polish Notation) calculation to apply to datapoint.nostring"" (empty string)
includeThresholdsShould thresholds associated with dpName be automatically added to the graph?nobooleanfalse
thresholdLegendsMapping of threshold id to legend (string) and color (RRGGBB)nomap<threshold, legends>{} (empty map)

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.

Additional Fields
NameDescriptionRequiredTypeDefault Value
threshIdReference to the id of related threshold.yesstringNone
CommentGraphPoint

The CommentGraphPoint graphpoint type allows a comment to be added to the graph legend.

Additional Fields
NameDescriptionRequiredTypeDefault Value
textComment to be added to graph's legend.yesstringNone