Device classes

Device classes are the functional categorization mechanism for Collection Zone and Resource Manager devices. Everything about how a device is modeled and monitored is controlled by its device class unless the device class configuration is overridden specifically for the device.

Example device classes that are defaults in every Collection Zone and Resource Manager deployment:

• /Discovered
• /Network
• /Server

Device classes are one of the most common items added by ZenPacks.

Adding

To add a device class to your ZenPack you must include a device_classes section to your YAML file. The following example shows an example of adding a device class.

zenpack.yaml

device_classes:
  /Server/ACME/Widgeter:
    remove: true

The remove field controls whether the device class will be removed if the ZenPack is removed. It defaults to false. In this example we set it to true because we do want our custom device class removed if the ZenPack that supports it is removed.

Each device class listed in device_classes will be created when the ZenPack is installed. The device classes will be created recursively if necessary. Meaning that if the /Server or /Server/ACME device classes don’t already exist, they will be automatically created.

Since this is a YAML mapping, the minimal specification (name only) would look like:

zenpack.yaml

device_classes:
  /Server/ACME/Widgeter: {}

Setting zProperties

You can also set zProperty values for each device class. These values will be set each time the ZenPack is installed.

zenpack.yaml

device_classes:
  /Server/ACME/Widgeter:
    remove: true
    zProperties:
      zWidgeterEnable: true
      zWidgeterInterval: 60

As of version 2.0, zProperties will not be set on existing device classes during ZenPack installation. Developers wishing to do so should handle these cases via migrate scripts that run during the installation process.

The referenced zProperties must already exist in the Zenoss system, or be added by your ZenPack via a global zProperties entry.

Adding monitoring templates

Within each device class entry you can add monitoring templates. See the following example for adding a simple monitoring template with a single COMMAND datasource.

zenpack.yaml

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

    templates:
      Device:
        description: ACME Widgeter monitoring.

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

            datapoints:
              percent: {}

        graphs:
          Phoniness:
            units: percent
            miny: 0
            maxy: 100

            graphpoints:
              Phoniness:
                dpName: phony_percent
                format: "%7.2lf%%"
                lineType: AREA

This Device monitoring template will be added to the /Server/ACME/Widgeter device class each time the ZenPack is installed. This doesn’t explicitly bind the monitoring template to the device class. To do that you need to set zDeviceTemplates as shown in the example.

For more information about creating monitoring templates, see Monitoring templates.

Fields

The following fields are valid for a device class entry.

path (required, string, default = implied from key in device_classes map)

Path (e.g. /Server/ACME/Widgeter). Must begin with the solidus character (/).

description (required, string, default = "" (empty string))

Description used for devtype entry in device multi-add dialog.

create (optional, boolean, default = true)

Should the device class be created when the ZenPack is installed?

remove (optional, boolean, default = false)

Should the device class be removed when the ZenPack is removed?

reset (optional, boolean, default = false)

Resets zProperties values on upgrade when set to true.

This field is not the preferred way to handle migration or changes to zProperty values between ZenPack versions. It is likely to cause heartache in cases where the target device class is not supplied exclusively by the ZenPack, for instance, since there is no way to control which version of the desired zProperty values would be authoritative or what the expected value should be if a single device class is targeted by multiple ZenPacks. Several other bad scenarios exist, so use this option with extreme caution and preferably use migration scripts to handle these types of changes.

zProperties (optional, map, default = {} (empty map))

zProperty values to set on the device class.

templates (optional, map, default = {} (empty map))

Monitoring templates to add to the device class.

protocol (optional, string, default = "" (empty string))

Modeling and monitoring protocol used for device in this class.