Skip to main content

Reference pages

zenpack.yaml

Troubleshooting

Using the Python Debugger

One of the most powerful tools when debugging the Python portions of a ZenPack is the Python debugger (pdb). With pdb you can set breakpoints in your code. When the breakpoints are hit, you get a (pdb) prompt that has full access to examine the stack and any local or global variables.

To set a breakpoint in your code you add the following line.

import pdb; pdb.set_trace()

As with any code change, you must restart the Virtana process that executes the code in question.

Saving Data

ZenPackLib v2.0 also adds a decorator, writeDataToFile, that can be used to save real-world results that your plugins will be processing. This data can then be used to determine why a plugin is not behaving as expected or to create your own unit tests.

In order to use this decorator, import it from the ZenPackLib ZenPack:

from ZenPacks.zenoss.ZenPackLib.lib.helpers.utils import writeDataToFile

Then use as a decorator for your plugin’s process function. writeDataToFile is generic and can be used on any python function or class method. It does not pickle file or logger objects. You can also specify keywords which, when matched against an object’s attributes, will cause an object not to be pickled.

class MyPlugin(PythonPlugin):
    @writeDataToFile(keywords=['zCommandPassword', 'windows_password'])
    def process(self, device, results, log):
        '''Perform device specific processing on modeler plugin results'''
        rm = self.relMap()
        # Add data to relationship map
        rm.attr1 = results.attr1
        rm.attr2 = results.attr2
        return rm

The save functionality is disabled unless you use the ZPL_DUMP_DATA environment variable. Be sure to only use in limited runs or you will end up with a large number of pickle files.

export ZPL_DUMP_DATA=1; zenmodeler run -d mydevice; unset ZPL_DUMP_DATA

The pickle file(s) will be written to your /tmp folder using the class name and function name with current timestamp. Using the definition from above, the file name would be MyPlugin_process_XXXXXX.pickle where XXXXXX is the time at which the data was processed. Assuming device has either a zCommandPassword or windows_password attribute, the self, device, and log objects will not be pickled.

Known Issues

  • When dumping existing event classes using the zenpacklib script with --dump-event-classes option, some transforms and explanations might show as either unformatted text within double quotation marks or as formatted text within single quotation marks. This formatting happens because of how the Python yaml package handles strings. Either of these two formats is acceptable when used in zenpack.yaml.

  • ZenPacks using earlier versions of ZenPackLib logged template changes to the console during installation. These messages might have confused some users because they were logged as an ERROR status. These messages have been revised and now log as informational, but the old format appears when upgrading from a pre-ZenPacklib 2.0 ZenPack to one using the latest version. Subsequent installs use the newer format.

  • ZenPackLib 2.1.3 has an issue with building impact relations, dependencies, and dynamic views for multi-YAML ZenPacks. We recommend upgrading to 2.1.4 or later versions. After you upgrade from the 2.1.3 version, execute the additional zenimpactgraph run --update command to fix the broken impact relations.

CLI

While most of benefit of the ZDK is the zenpacklib library to help you build ZenPacks, there is also a zenpacklib command line script that performs some useful actions.

Running the script alone or with --help returns the following usage instructions:

Usage: zenpacklib [options] [FILENAME|ZENPACK|DEVICE]

ZenPack Conversion:
 -t, --dump-templates
                     export existing monitoring templates to YAML
 -e, --dump-event-classes
                     export existing event classes to YAML
 -r, --dump-process-classes
                     export existing process classes to YAML

ZenPack Development:
 -c, --create        Create a new ZenPack source directory
 -l, --lint          check zenpack.yaml syntax for errors
 -o, --optimize      optimize zenpack.yaml format and DEFAULTS
 -d, --diagram       print YUML (http://yuml.me/) class diagram source
                     based on zenpack.yaml
 -p, --paths         print possible facet paths for a given device and
                     whether currently filtered.

The following commands are supported:

create

The --create switch creates a source directory for a ZDK-enabled ZenPack. This will include a setup.py, MANIFEST.in, the namespace and module directories, and a zenpack.yaml in the module directory. The ZenPack is ready to install immediately even though it contains no functionality.

Example usage:

zenpacklib --create ZenPacks.example.MyNewPack

The preceding command yields the following output:

Creating source directory for ZenPacks.test.ZPLTest2:
  - making directory: ZenPacks.test.ZPLTest2/ZenPacks/test/ZPLTest2
  - creating file: ZenPacks.test.ZPLTest2/setup.py
  - creating file: ZenPacks.test.ZPLTest2/MAINFEST.in
  - creating file: ZenPacks.test.ZPLTest2/ZenPacks/__init__.py
  - creating file: ZenPacks.test.ZPLTest2/ZenPacks/test/__init__.py
  - creating file: ZenPacks.test.ZPLTest2/ZenPacks/test/ZPLTest2/__init__.py
  - creating file: ZenPacks.test.ZPLTest2/ZenPacks/test/ZPLTest2/zenpack.yaml

lint

The --lint switch checks YAML files for correctness. It checks that the provided file is syntactically-valid YAML, and it will also perform many others checks that validate that the contained entries, fields and their values are valid.

The following example shows an example of using an unrecognized parameter in a monitoring template.

$ zenpacklib --lint zenpack.yaml
zenpack.yaml:47:9: Unrecognized parameter 'targetPythnoClass' found while processing RRDTemplateSpec

The --lint switch returns no result when a YAML file is valid.

diagram

The --diagram switch uses the classes and relationships in a YAML file to generate the source for a yUML class diagram. For ZenPacks with a non-trivial class model this can provide a useful view of the model.

Example:

zenpack.yaml

name: ZenPacks.example.NetBotz

classes:
  NetBotzDevice:
    base: [zenpacklib.Device]

  NetBotzEnclosure:
    base: [zenpacklib.Component]

  NetBotzSensor:
    base: [zenpacklib.Component]

class_relationships:
  - NetBotzDevice 1:MC NetBotzEnclosure
  - NetBotzDevice 1:MC NetBotzSensor
  - NetBotzEnclosure 1:M NetBotzSensor

Running the zenpacklib script with the --diagram switch yields the following yUML class diagram source, which you can paste this into the sample window at https://yuml.me/diagram/scruffy/class/draw to see a diagram.

## Classes
[NetBotzDevice]
[NetBotzEnclosure]
[NetBotzSensor]

## Inheritence
[Device]^-[NetBotzDevice]
[Component]^-[NetBotzEnclosure]
[Component]^-[NetBotzSensor]

## Containing Relationships
[NetBotzDevice]++netBotzEnclosures-netBotzDevice[NetBotzEnclosure]
[NetBotzDevice]++netBotzSensors-netBotzDevice[NetBotzSensor]

## Non-Containing Relationships
[NetBotzEnclosure]netBotzSensors-.-netBotzEnclosure++[NetBotzSensor]

paths

The --paths switch shows the paths between defined component classes using the device name you have specified as a sample. To obtain useful results, ensure that the device has at least one component of each type you are interested in.

The paths shown are those used to control which devices will show up in the bottom grid of the Virtana Collection Zone or Virtana Service Dynamics browser interface when both a component and a target class are selected from the filter dropdown.

The default behavior is to show components of that type that are directly related to the selected component through 1:M or 1:MC relationships, but additional objects that are indirectly related can be added through the use of the ‘extra_paths’ configuration directive. The —-paths switch is primarily a debugging tool during the development of extra_paths patterns to verify that they are having the intended effect.

Example usage:

zenpacklib --paths mydevice

dump-templates

The --dump-templates switch exports monitoring templates already loaded into your Virtana instance and associated with a ZenPack. It exports them to the YAML format required for zenpack.yaml. It is up to you to merge that YAML with your existing zenpack.yaml file.

Example usage:

zenpacklib --dump-templates ZenPacks.example.BetterAlreadyBeInstalled

dump-event-classes

The --dump-event-classes switch exports event class organizers and mappings already loaded into your Virtana instance and associated with a ZenPack. It exports them to the YAML format required for zenpack.yaml. It is up to you to merge that YAML with your existing zenpack.yaml file.

Only event classes sourced from the ZenPack’s XML are exported; event classes sourced from the ZenPack’s YAML are not exported. If you want the YAML for these event classes, copy it from the ZenPack’s existing YAML.

Example usage:

zenpacklib --dump-event-classes ZenPacks.example.BetterAlreadyBeInstalled

When dumping existing event classes using the zenpacklib script with the --dump-event-classes option, some transforms and/or explanations may show as either unformatted text within double quotes or as formatted text within single quotes. This is due to how the Python yaml package handles strings. Either format is acceptable in zenpack.yaml.

dump-process-classes

The --dump-process-classes switch exports process class organizers and classes already loaded into your Virtana instance and associated with a ZenPack. It exports them to the YAML format required for zenpack.yaml. It is up to you to merge that YAML with your existing zenpack.yaml file.

Only process class organizers sourced from the ZenPack’s XML are exported; process class organizers sourced from the ZenPack’s YAML are not exported. If you want the YAML for these process class organizers, copy it from the ZenPack’s existing YAML.

Example usage:

zenpacklib --dump-process-classes ZenPacks.example.BetterAlreadyBeInstalled

optimize

The --optimize switch (experimental) is designed to examine your zenpack.yaml file and rearrange it for brevity and use of DEFAULTS where detected. Once optimized, the command compares the original YAML file to the optimized version to ensure that the same objects are created. The change detection, however, is still being improved and may output false warnings. It is recommended to double-check the optimized YAML output by hand.

Example usage:

zenpacklib --optimize zenpack.yaml

Compatibility

Starting with version 2.0, zenpacklib.py will ship as a separately installed ZenPack. This change offers several advantages over the earlier distribution method along with many new features and fixes. Existing ZenPacks based on earlier versions of zenpacklib.py should coexist peacefully with those based on the newer version, and eventual migration to version 2.0 should be relatively painless. Future versions of Zenoss-provided ZenPacks will use the newer ZenPackLib version as they are developed and released.

Migrating ZenPacks to 2.0

For the most part, migrating to ZenPackLib 2.0 should be straightforward and requires minimal changes to your ZenPack. These largely involve changing import statements where appropriate and removing the older zenpacklib.py files

ZenPacks based on ZenPackLib 2.0 will need to have a dependency set to prevent potential issues when installing or removing them. If ZenPackLib 2.0 is not installed, a dependent ZenPack should refuse to install until the dependency is met. Similarly, ZenPackLib 2.0 should refuse removal if dependent ZenPacks are still installed. To achieve this, make sure that the INSTALL_REQUIRES variable in the setup.py file contains the following:

setup.py

INSTALL_REQUIRES = ['ZenPacks.zenoss.ZenPackLib']

Please note that INSTALL_REQUIRES may already contain entries, and these should be preserved if they exist.

This can also be configured in the GUI if the dependent ZenPack is installed in develop mode.

The __init__.py file will need its import statements changed.

__init__.py

from . import zenpacklib

changes to:

__init__.py

from ZenPacks.zenoss.ZenPackLib import zenpacklib

while:

__init__.py

CFG = zenpacklib.load_yaml()

remains unchanged unless some of the new logging capabilities are desired such as:

__init__.py

CFG = zenpacklib.load_yaml(verbose=True, level=10)

In addition, the statement (if it exists):

__init__.py

from . import schema

should be changed to:

__init__.py

schema = CFG.zenpack_module.schema

or added if it does not exist.

Care should also be taken to delete the zenpacklib.py and zenpacklib.pyc files in the ZenPack’s source directory, since leaving them in place may cause unforeseen behavior.

Import statements should also be checked throughout any class overrides or other python files, since the statements will fail if they refer to the older zenpacklib.py.

The tag !ZenPackSpec is not necessary and should be removed from your yaml definitions.

Logging

Logging has been substantially enhanced for ZenPackLib version 2.0 and provides numerous features to aid during development or troubleshooting. Logging can now be controlled on a per-ZenPack basis by supplying additional parameters to the load_yaml() method call in the ZenPack’s __init__.py file:

  • The verbose parameter, if set to True, will enable logging for this particular ZenPack. We recommend enabling verbose during ZenPack development so that various error messages can be seen. We also recommend disabling verbose prior to release of your ZenPack as some warning messages may not be useful to the end user.

  • The level parameter controls logging verbosity with the same numeric values used elsewhere in Virtana. The default value is 30 (WARNING), but setting this to 20 (INFO) or 10 (DEBUG) may be useful during ZenPack development.

CFG = zenpacklib.load_yaml(verbose=True, level=10)

In this example, logging verbosity is enabled with at the DEBUG level.

Every class in ZenPackLib has a LOG attribute that can be called within any class override files you may have. For example, given the file BasicComponent.py class extension, logging features would be accessed as follows:

BasicComponent.py

from . import schema

class BasicComponent(schema.BasicComponent):
    """Class override for BasisComponent"""
    def hello_world(self):
        self.LOG.info("You called hello_world")
        return 'Hello World!'

Log messages generated within the new logging framework are written to the Zope logger (event.log) and can be viewed there. Logging used within class extension files will follow the verbosity and level parameters provided to the load_yaml method.

Please note that additional Zope configuration may be required to see log messages, since Zope configuration determines what is accepted for writing to its event log. For example, if Zope logging is set to warn, then any info or debug messages will not be logged regardless of the load_yaml parameters used. Zope logging in this case must be set to info for ZPL info, warning, and critical logging.

Change history

Version 2.1

Release 2.1.5

Fixes

  • Fix monitoring templates representation in infrastructure view for devices created using ZPL that have -addition templates (ZPS-8945)

  • Fix ZenpackLib-based ZenPack removal when the expected suborganizer doesn't exist (ZPS-8863)

Release 2.1.4

Fixes

  • Fix dependencies, dynamic view and impact relations for multi-YAML ZenPacks (ZPS-8835)

Release 2.1.3

Fixes

  • Improve and correct ZenPackLib the -replacement and -addition templates handling (ZPS-8617)

  • Improve ZenPackLib efficiency during loading multiple YAML files (ZPS-8777)

Release 2.1.2

Fixes

  • Allow Class.filter_hide_from option to also work for contained components (ZPS-5107)

Release 2.1.1

Fixes

  • Fix infinite recursion in yaml_load when no yaml files present (ZPS-3880)

  • Update default value of threshold’s escalationCount in the documentation (ZPS-4031)

  • Ensure device class removal during various upgrade scenarios (ZPS-3906)

  • Correct links from ZPL-provided renderers to honor the CSE_VIRTUAL_ROOT (ZEN-30544)

Release 2.1.0

Features

  • Support additional GraphPoint subclasses (ZPS-855)

  • EventClassInstance, OSProcessClass now support zProperties (ZPS-3636)

  • EventClass, OSProcessOrganizer now support zProperties (ZPS-3189, ZPS-3190)

  • Add “optional” field for thresholds (ZPS-1666)

  • Add support for ZProperty “label” and “description” fields (ZPS-747)

Fixes

  • Support Graph “description” attribute (ZPS-3696)

  • Support ABSOLUTE RRD type (ZPS-1733)

  • All organizer classes respect the “create”, “remove”, and “reset” attributes (ZPS-810)

  • Refactor unit tests to avoid build issues (ZPS-3035)

  • Fix invalid RRD datapoint types (ZPS-1734)

  • Update documentation for datapoint description (ZPS-1971)

Version 2.0

Backwards Incompatible Changes

  • Any installed ZenPacks using older versions of zenpacklib.py will continue to function unchanged.

  • Using version 2 is slightly different. The __init__.py file import statements should now contain the following:

    _init_.py

    from ZenPacks.zenoss.ZenPackLib import zenpacklib
    CFG = zenpacklib.load_yaml()
    
    
    # Startup time can be improved by specifying explicit path.
    # CFG = zenpacklib.load_yaml([os.path.join(os.path.dirname(__file__), “zenpack.yaml”)])
    
    schema = CFG.zenpack_module.schema
  • zProperties will not be updated automatically on existing device classes. These should be handled on a case basis by using migrate scripts.

Release 2.0.9

Fixes

  • Fix incorrect removal of organizers such as /Status event class (ZPS-2660)

Release 2.0.8

Fixes

  • Improve component grid loading performance. (ZPS-2033)

  • Fix potential POSKeyError when modeling devices. (ZPS-2371)

  • Improved support for multi-line text in YAML (ZPS-444)

  • Improved component path reporters for mixin platform proxy classes (ZPS-1262)

  • Fix zenpacklib.TestCase when Impact >= 5.2.2 is installed (ZPS-2011)

Release 2.0.7

Fixes

  • Fix all the zenpacklib dump options. (ZPS-1601)

  • Implement template replacement and addition on device level. (ZPS-1704)

Release 2.0.6

Fixes

  • Fix mishandling of 0/clear severity (ZPS-1454)

  • Fix attempts to load non-YAML files (ZPS-1483)

  • Use appropriate sequence for graph points (ZPS-1361)

  • Fix GUI ZenPack export of objects.xml (ZPS-1589)

  • Fix datapoint alias shorthand export handling (ZPS-1589)

Release 2.0.5

Fixes

  • Fix version reported by “zenpacklib –version”. (ZPS-1145)

  • Template backups use YYYYMMDDHHMM format instead of unix timestamp.

  • Fix failure to back up customized templates during upgrade from pre-2.0 ZenPacks. (ZPS-1195)

  • Fix failure to back up customized templates during upgrade. (ZPS-1176)

Release 2.0.4

Fixes

  • Fix for missing Dynamic View on some components (ZPS-703)

  • Fix for failure to create device classes in uncommon case (ZPS-1012)

  • Fix event class mappings with mismatched id and eventClassKey (ZPS-1016)

Release 2.0.3

Fixes

  • Preserve ordering when loading multiple YAML files (ZPS-921)

  • Fix setting of zProperty values when loading multiple YAML files. (ZPS-925)

Release 2.0.2

Fixes

  • Only create a monitoring template if it changes or does not exist (ZPS-570)

  • Ensure display of ZPL classes such as OSProcess in GUI elements (ZPS-572, ZPS-651)

Release 2.0.1

Fixes

  • Ensure all datapoint attributes export to YAML (ZEN-26593)

  • Ensure subsquent installations complete if ZP install fails (ZPS-627)

Release 2.0.0

Features

  • zenpacklib is now an installable ZenPack

  • Added Event Class definitions (ZEN-24903)

  • Support multiple YAML file loading

  • Support directory loading for YAML

  • Support log verbosity per ZenPack

  • Centralized, per-derived ZenPack logging

  • Improved template change detection during install

  • Improved type handling of yaml loaded/dumped data

  • Support centralized use of older monolithic zenpacklib.py

  • Added –optimize parameter to zenpacklib

  • Dramatically enhanced unit testing

  • Support for using enum proprty with datapoint properties (string/int mapping)

  • Ability to call /opt/zenoss/bin/zenpacklib

  • Added ZPLCommand to handle running zenpacklib with arguments

  • Separated zenpacklib.py classes into module files

  • Ability to use ZenPack-provided zenpacklib module

  • Added support for Process Class definitions

  • Deprecated support for python-based “yaml” specifications

  • Support for threshold graphpoint legend and color (ZEN-24904)

  • Ability to specify an initial sort column on a component grid

  • Performance enhancments for grid display of metrics (ZEN-23870)

  • Support for Device Link Providers

  • Added troubleshooting aid for easily saving function data(writeDataToFile)

  • Avoid setting zProperties on existing device class (ZPS-137)

Fixes

  • Fix handling of boolean data source options (ZEN-25315)

  • Merge Detail View groups into ‘Overview’ group (ZEN-24759)

  • Ensure that component detail pane honors relation “details_display” (ZEN-24762)

  • Update ZenPackLib (ZP) Unit tests (ZEN-24599)

  • Ensure that subcomponent nav JS uses relationship label if provided (ZEN-24305)

  • Ensure ability to set label or a subclass on an inherited relationship (ZEN-24303)

  • Ensure inherited relationship name overrides displayed in details pane (ZEN-24302)

  • Ensure extra_paths is working (ZEN-24268)

  • Ensure that ‘extra_params’ get applied to template-related objects (ZEN-24083)

  • Improved handling of “custom columns exceed 750 pixels” warnings (ZEN-24022)

  • Avoid patching _relations on ZPL-derived subclasse (ZEN-24018)

  • Incorrect display of nested custom-named relations (ZEN-23995)

  • Fix missing relations (ZEN-23968)

  • Fix maximum recursion depth exceeded traceback in get_facets (ZEN-23840)

  • Allow specifying properties on an inherited relationship (ZEN-23763)

  • Zenpacklib logging more helpful and less scary (ZEN-23621)

  • Batch buildRelations() commits during ZenPack installs (ZEN-22655)

  • Support adding devtypes (ZEN-22366)

  • Improve ImportError logging in class files (ZEN-22927)

  • Ensure non-cached datapoints return current value (ZEN-22288)

  • Fix issue when setting datapoint_cached to False (ZEN-22287)

  • Set all component property details to correct Python type (ZEN-22057)

  • Honor relationship label containing component overrides in component (ZEN-21966)

  • Prevent attempts to process relationships not in class_relationships (ZEN-21927)

  • Ensure component display properties honored (ZEN-19798)

  • Support setting datapoint alias as string (ZEN-19486)

  • Check datapoint consistency in template graph points and thresholds (ZEN-19461)

  • Check/warn against reserved keyword use (ZEN-19460)

  • getRRDTemplateName can return label of base class (ZEN-19025)

  • Ensure catalog creation respects spec property indexes (ZEN-18269)

  • Ensure device classes can be removed properly (ZEN-18134)

  • Ensure that datapoint alias keys do not exceed 31 chars (ZEN-17950)

  • Log obscure error with ill-defined relationships (ZEN-16701)

  • Fix handling of !ZenPackSpec tag in yaml definitions

Version 1.1

Release 1.1.0

Features

  • Add dynamicview_weight class field.

  • Add overridable getDynamicViewGroup method to generated classes.

  • Class icons beginning with / will be treated as absolute URL paths.

  • Improve performance of entity properties in component grids.

  • Simplify what device status means to critical event(s) in /Status.

  • Improve grid performance with streamlined info adapters

  • Add base class proxies for all platform component classes.

Fixes

  • Fix tracebacks caused by property datapoint_cached. (ZEN-22287)

  • Fix ‘display’ property to honor initialized values. (ZEN-19798)

  • Fix wrong template displayed for subclassed component (ZEN-19025)

  • Fix inheritance for displayed relationship properties (ZEN-23763)

  • Fix traceback in get_facets (maximum recursion depth exceeded) (ZEN-23840)

  • Ensure that ‘extra_params’ get applied to template-related objects (ZEN-24083)

  • Fix for lost relationships on ZPL-derived subclasses (ZEN-24018)

  • Fix for extra_paths failures (ZEN-24268)

  • Fix to gracefully handle unknown relationship properties (ZEN-21927)

  • Ensure that inherited relationship names are used (ZEN-24302)

  • Ensure that inherited relationship names are displayed consistently (ZEN-24303)

  • Ensure that subcomponent nav JS uses relationship label if given (ZEN-24305)

  • Fix for setting of zProperty values before zProperty exists

  • Fix “unexpected keyword default” message

  • Fix support for extending platform component classes. (ZEN-25559)

Documentation

  • Fix YAML reference for dynamicview_group class field.

  • Fix documentation of default value for dynamicview_views.

  • Document new component class proxies such as IpInterface and FileSystem.

Version 1.0

Release 1.0.13

Fixes

  • Honor graph and graphpoint ordering in zenpack.yaml. (ZEN-23590)

Release 1.0.12

Fixes

  • Fix tracebacks due to stale catalog entries. (ZEN-22592)

  • Fix hidden zenpacklib errors due to unitialized logging.

  • Prevent setting values on undefined zProperties.

  • Drastically reduce catalog creation time.

Documentation

  • Add missing types to zProperty documentation.

Release 1.0.11

Fixes

  • Only show Dynamic View for components that support it. (ZEN-22391)

  • Fix created __init__.py to work with zenpacklib.TestCase. (ZEN-22387)

Release 1.0.10

Fixes

  • Fix display of nested component container-of-container. (ZEN-21897)

Documentation

  • Fix graphpoint lineType documentation.

Release 1.0.9

Fixes

  • Fix non-containing setters with standard device types. (ZEN-21747)

  • Fix filtering of YAML templates in ZenPack export. (ZEN-21697)

  • Prevent backups of unchanged monitoring templates. (ZEN-21719)

Release 1.0.8

Fixes

  • Fix various dump_templates issues. (ZEN-18824)

Release 1.0.7

Fixes

  • Fix dynamicview_relations type issue.

Release 1.0.6

Fixes

  • Make YAML-defined JMX data sources work. (ZEN-21467)

Release 1.0.5

Fixes

  • Fix KeyError on install after adding device class. (ZEN-21461)

Release 1.0.4

Features

  • TestCase: Automatically load ZenPack’s configure.zcml if it exists.

  • Default to checkbox renderer for boolean properties. (ZEN-19585)

Fixes

  • TestCase: Fix transaction error without DynamicView or Impact installed.

  • Fix entity grid renderer to make it possible to click links into a new tab. (ZEN-19922)

  • Fix enum property type. (ZEN-20769)

Release 1.0.3

Fixes

  • Fix testing of SNMP data sources by converting OIDs to string.

  • Fix for inherited relationships and properties not appearing in UI.

Release 1.0.2

Fixes

  • Log YAML errors more concisely instead of full traceback. (ZEN-17681)

  • Fix “[Object]” details panel display for custom renderers. (ZEN-17732)

  • Fix handling of nested device class remove field.

  • Fix KeyError when removing non-existent device class.

  • Fix handling of datapoint rrdtype. (ZEN-18188)

Release 1.0.1

Features

  • Add Class.extra_paths for controlling object path indexing.

  • Add Class.filter_hide_from option.

Fixes

  • Fix handling of class _properties and _relationships.

  • Prefix ExtJS components to avoid conflicting zenpacklib versions.

  • Fix handling of Class property types.

  • Fix py_to_yaml for ZenPacks that subclass ZenPack.

  • Remove superfluous YAML type hints from py_to_yaml conversion.

  • Fix “Unable to find TEMPLATE_ID” installation error.

  • Base component status on events in /Status event class.

  • Fix removal of objects when PyYAML isn’t installed.

Release 1.0.0

Features

  • Added ability to define ZenPack with YAML.

  • Added support for model classes and relationships.

  • Added support for zProperties.

  • Added support for device classes.

  • Added support for monitoring templates.

  • Added create command for creating ZenPacks from the command line.

  • Added lint command to check YAML for correctness.

  • Added class_diagram command to create yUML class diagram from YAML.

  • Added dump_templates command to export monitoring templates to YAML.

  • Added py_to_yaml command to convert old Python specs to YAML.

  • Added version command to print zenpacklib’s version.

Documentation

  • Added first pass at documentation.

ZenPack YAML file

The ZenPack YAML file, zenpack.yaml, contains a ZenPack specification. The name field is required and the following fields are optional:

The name field must begin with ZenPacks and the full stop character (.). By convention, the second part is the name of the organization responsible for the ZenPack. For example, ZenPacks.acme.Widgeter.

Example

Here is a file with every optional field.

zenpack.yaml

name: ZenPacks.acme.Widgeter

zProperties:
  zWidgeterEnable: {}

device_classes:
  /Server/ACME/Widgeter: {}

classes:
  ACMEWidgeter:
    base: [zenpacklib.Device]

  ACMEWidget:
    base: [zenpacklib.Component]

class_relationships:
  - Widgeter 1:MC Widget

link_providers:
  Virtual Machine:
    link_class: ZenPacks.example.XenServer
    catalog: device
    device_class: /Server/XenServer
    queries: [vm_id:manageIp]
  XenServer:
    global_search: True
    queries: [manageIp:vm_id]

event_classes:
  /Status/Acme:
    remove: false
    description: Acme event class
    mappings:
      Widget:
        eventClassKey: WidgetEvent
        sequence:  10
        remove: true
        transform: |
          if evt.message.find('Error reading value for') >= 0:
              evt._action = 'drop'

process_class_organizers:
  Widget:
    description: Organizer for Widget process classes
    process_classes:
      widget:
        description: Widget process class
        includeRegex: sbin\/widget
        excludeRegex: "\\b(vim|tail|grep|tar|cat|bash)\\b"
        replaceRegex: .*
        replacement: Widget

zProperties

zProperties are configuration properties that can be specified on any device class including the root /Devices class, and on any individual device. They are one part of a hierarchical configuration system.

Inheritance

The most-specific value for a zProperty within the hierarchy will be used for any given device. For instance, given a device linux1 in the /Server/Linux device class. The value for zSnmpMonitorIgnore will be checked first on the linux1 device. If it is not set locally on the device, the /Server/Linux device class will then be checked. If not set there, /Server will be checked. Finally the value at / (or /Devices) will be checked as a final resort. Since all zProperties must have a default values that is set at the root device class, there will always be a value for the zProperty. Even if it is an empty string.

Caveats

When changing modeler bindings using the zDeviceTemplates property, this will take effect on your ZenPack. Any previously defined bindings will be replaced. The same applies to the device level template bindings using the zCollectorPlugins property.

Beginning with ZenPackLib 2.0, this behavior has changed by default. zProperties will no longer be overwritten if a target device class already exists (that is, during an upgrade or if the YAML affects a preexisting class such as /Devices/Server). Instead, a warning will be displayed to the user during installation, and the target zProperty will be left alone.

Setting reset: true for a specific device class in the YAML will override this behavior, causing the zProperties to be replaced with the YAML-defined values.

Fields

The following fields are valid for a zProperty entry.

name (required, string, default = implied from key in zProperties map)

Name (e.g. zWidgeterEnable). Must be begin with a lowercase `z``.

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

Category name. (e.g. ACME Widgeter). Used to group related zProperties in the UI.

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

Brief description of zProperty.

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

Notes regarding the purpose and function of this zProperty.

type (optional, string, default = string)

Type of property. Valid types are boolean, float, int, lines, long, password, and string.

default (optional)

Default value for property. Default value depends on the type:

  • boolean: false

  • lines: []

  • password: "" (empty string)

  • string: "" (empty string)

  • all others: null (None)

Examples

To add a zProperty to your ZenPack you must include a zProperties section in your YAML file. The following example shows an example of adding two zProperties.

zenpack.yaml

zProperties:
  zWidgeterEnable:
    category: ACME Widgeter
    type: boolean
    default: true

  zWidgeterInterval:
    category: ACME Widgeter
    type: string
    default: 300

Each of these zProperty entries specifies a category, type and default. These are the only valid fields of the a zProperty entry. However, each of these fields has a default value that will be used if the field isn’t explicitly specified. For example, the default value for type is string. So the above example could be shortened slightly by omitting the explicit type on zWidgeterInterval.

zenpack.yaml

zProperties:
  zWidgeterEnable:
    category: ACME Widgeter
    type: boolean
    default: true

  zWidgeterInterval:
    category: ACME Widgeter
    default: 300

There is a special zProperty entry named DEFAULTS that can be used to further shorten definitions in cases where you’re adding many zProperties. The following example shows how DEFAULTS can be used to replace the duplicated category property.

zenpack.yaml

zProperties:
  DEFAULTS:
    category: ACME Widgeter

  zWidgeterEnable:
    type: boolean
    default: true

  zWidgeterInterval:
    default: 300

Since a zProperty is a YAML “mapping”, the minmal specification of a zProperty (name only) would look like:

zenpack.yaml

zProperties:
  zWidgeterMinimal: {}

Each zProperty listed in zProperties will be created when the ZenPack is installed, and removed when the ZenPack is removed.

When changing the default or category for a zProperty in the YAML file, it changes in the system. Removing a zProperty from the YAML file will not remove it from the system. To remove it completely, you must write a migration script.

Device classes

Device classes are the functional categorization mechanism for Virtana Collection Zone and Virtana Service Dynamics 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 Virtana Collection Zone and Virtana Service Dynamics 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 Virtana 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.

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. Virtana 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 Virtana 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 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 Virtana 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 Virtana 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 Virtana, and depending on the value of type, other fields may be valid.

Datasource types

The following datasource types are valid on any Virtana 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 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 Virtana 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 Virtana 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 Virtana, 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 Virtana 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 Virtana 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 Virtana 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.

Event classes

Event Classes are used to group together specific types of events. This can be useful for situations where an event should be dropped or text should be altered to be more human readable. This is typically done through a python transform.

To define a class, supply the path to the class or classes. Then, for each event class, supply the appropriate properties for the class. These include the option to remove the event class during ZenPack installation/uninstallation, description, and a transform. You can also define mappings to apply to events based on a key and supply an explanation and/or resolution to an issue.

When you define an event class and/or mapping which already exists, any settings defined in your ZenPack will overwrite existing settings.

The following example shows an example of a zenpack.yaml file with an example of a definition of an event class.

zenpack.yaml

name: ZenPacks.acme.Events

event_classes:
  /Status/Acme:
    remove: false
    description: Acme event class
    mappings:
      Widget:
        eventClassKey: WidgetEvent
        sequence:  10
        remove: true
        transform: |-
          if evt.message.find('Error reading value for') >= 0:
              evt._action = 'drop'

When assigning values to multi-line fields such as transform or example, the best way to preserve whitespace and readability is to use YAML's |- multiline indicator as shown above.

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

zenpack.yaml

event_classes:
  /Status/Acme: {}

Event class fields

The following fields are valid for an event class entry.

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

Path to the Event Class (e.g. /Status/Acme). Must begin with the solidus character (/).

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

Description of the event class.

create (optional, boolean, default = true)

Should the event class be created when the ZenPack is installed.

remove (optional, boolean, default = false)

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

This only applies to the ZenPack that created the event class.

  • Event classes not created by the ZenPack are not removed.

  • Event classes created by the platform are never removed.

reset (optional, boolean, default = false)

If true, any zProperties defined here will override those of the target event class.

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

zProperty values to set on the event class.

transform (optional, string (multiline), default = "" (empty string))

A python block for transformation.

mappings (optional, map, {} (empty map))

Event class mappings.

Event Class Mapping Fields

The following fields are valid for an event class mapping entry.

name (required, string, default = implied from key in mappings map)

Name of the event class mapping (e.g. WidgetDown).

remove (optional, boolean, default = false)

Remove the mapping when the ZenPack is removed?

eventClassKey (optional, string, default = None)

Event class key matched by the mapping.

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

A python expression to match an event.

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

A regular expression to match an event.

example (optional, string (multiline), default = "" (empty string))

Debugging string to use in the regular expression UI testing.

sequence (optional, integer, default = 0)

Define the match priority. Lower is a higher priority.

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

zProperty values to set on the event class mapping.

transform (optional, string (multiline), default = "" (empty string))

A Python expression for transformation.

explanation (optional, string (multiline), default = "" (empty string))

Textual description for matches of this event class mapping. Use in conjunction with the Resolution field.

resolution (optional, string (multiline), default = "" (empty string))

Use the Resolution field to enter resolution instructions for clearing the event.

Process classes

Process classes are used to define sets of similar running processes using a regular expression. You can then monitor various aspects of the running processes, such as CPU and memory usage, with a datasource.

To define a class, supply the process class organizer under which the process class will reside. Optionally add a description of the organizer. Then, for each process class, supply the processes to include/exclude, description, and replacement text. You can also optionally override specific zProperties of a process class, such as zMonitor or zFailSeverity. See Process class fields.

The following example shows an example of a zenpack.yaml file with an example of a definition of a process class.

zenpack.yaml

name: ZenPacks.acme.Processes

process_class_organizers:
  Widget:
    description: Organizer for Widget process classes
    process_classes:
      widget:
        description: Widget process class
        includeRegex: sbin\/widget
        excludeRegex: "\\b(vim|tail|grep|tar|cat|bash)\\b"
        replaceRegex: .*
        replacement: Widget

When you define a process class organizer and/or class which already exists, any settings defined in your ZenPack will overwrite existing settings.

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

zenpack.yaml

process_class_organizers:
  Widget: {}

Process class organizer fields

The following fields are valid for a process class organizer entry.

name (required, string, default = implied from key in process_class_organizers map)

Name (e.g. Widget or Widget/ACME).

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

Description of the process class organizer.

create (optional, boolean, default = true)

Should the process class organizer be created when the ZenPack is installed?

remove (optional, boolean, default = false)

Should the process class organizer be removed when the ZenPack is removed?

This will only apply to a ZenPack that has created the process class organizer.

  • Process class organizers not created by the ZenPack are removed.

  • Process class organizers created by the platform are never removed.

reset (optional, boolean, default = false)

If true, any zProperties defined here will override those of the target process class organizer.

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

zProperty values to set on the process class organizer.

Process class fields

The following fields are valid for a process class entry.

name (required, string, default = implied from key in process_classes map)

Name of the process class (e.g. widget).

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

Description of the process class.

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

zProperty values to set on the process class.

includeRegex (optional, string, default = name)

Include processes matching this regular expression.

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

Exclude processes matching this regular expression.

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

Replace command line text matching this regular expression.

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

Text which will replace the command line text that matches replaceRegex.

monitor (optional, boolean, default = None (don't override))

Enable monitoring? Overrides parent process class organizer setting.

alert_on_restart (optional, boolean, default = None (don't override))

Send event on restart? Overrides parent process class organizer setting.

fail_severity (optional, integer, default = None (don't override))

Failure event severity. Overrides parent process class organizer setting (0=Clear, 1=Debug, 2=Info, 3=Warning, 4=Error, 5=Critical).

modeler_lock (optional, integer, default = None (don't override))

Lock process components. Overrides parent process class organizer setting (0=Unlocked, 1=Lock from Deletes, 2=Lock from Updates).

send_event_when_blocked (optional, boolean, default = None (don't override))

Send and event when action is blocked? Overrides parent class organizer setting.

Classes and relationships

Classes and relationships form the model that forms the basis for everything Virtana does. Classes are things like Device, FileSystem, IpInterface and OSProcess. Relationships state things like a Device contains many FileSystems. You will need to extend this model when the standard classes and relationships don’t adequately represent the model of a target your ZenPack is attempting to monitor. For example, a XenServer ZenPack needs to represent concepts like pools, storage repositories and virtual machines.

Standard classes

The standard classes exist on all Virtana systems. If these are the only types of things you care to model and monitor then you may not need to create your own classes or relationships.

  • Device

    • DeviceHW (hw)

      • CPU (hw/cpus)

      • ExpansionCard (hw/cards)

      • Fan (hw/fans)

      • HardDisk (hw/harddisks)

      • PowerSupply (hw/powersupplies)

      • TemperatureSensor (hw/temperaturesensors)

    • OperatingSystem (os)

      • FileSystem (os/filesystems)

      • IpInterface (os/interfaces)

      • IpRouteEntry (os/routes)

      • OSProcess (os/processes)

      • IpService (os/ipservices)

      • WinService (os/winservices)

Classes

If you need more than the standard classes provide, you will need to extend one of the following base classes provided by zenpacklib.

  • zenpacklib.Device

  • zenpacklib.Component

    • zenpacklib.HWComponent

      • zenpacklib.CPU

      • zenpacklib.ExpansionCard

      • zenpacklib.Fan

      • zenpacklib.HardDisk

      • zenpacklib.PowerSupply

      • zenpacklib.TemperatureSensor

    • zenpacklib.OSComponent

      • zenpacklib.FileSystem

      • zenpacklib.IpInterface

      • zenpacklib.IpRouteEntry

      • zenpacklib.OSProcess

      • zenpacklib.Service

        • zenpacklib.IpService

        • zenpacklib.WinService

You use zenpacklib.Device to create new device types of which instances will appear on the Infrastructure screen. You use zenpacklib.Component to create new component types of which instances will appear under Components on a device’s left navigation pane. Frequently when ZenPacks need to add new classes, they will add a single new device type with many new components types. For example, a XenServer ZenPack would add a new device type called Endpoint which represents the XenAPI management interface. That Endpoint device type would have many components of types such as Pool, StorageRepository and VirtualMachine.

The other supported classes are proxies for their platform equivalents, and are to be used when you want to extend one of the platform component types rather than creating a totally new component type.

Relationships

Relationships are Virtana’ way of saying objects are related to each other. For example, the DeviceHW class contains many CPUs of the CPU class. You must also declare relationships between classes in your ZenPack. If you only declare types based on zenpacklib.Device you don’t have to do this because they’ll automatically have a relationship to their containing device class among other things. However, you must define at least a containing relationship for every type based on zenpacklib.Component you create. This is because components aren’t contained in any relationship by default, and every object in Virtana must be contained somewhere.

zenpacklib supports the following types of relationships.

  • One-to-Many Containing (1:MC)

  • One-to-Many (1:M)

  • Many-to-Many (M:M)

  • One-to-One (1:1)

It’s important to understand the different between containing and non-containing relationships. Each component type must be contained by exactly one relationship. Beyond that a device or component type may have as many non- containing relationships as you like. This is because every object in Virtana has a single primary path that describes where it is stored in the tree that is the Virtana object database.

A simplified version of XenServer’s classes and relationships provides for a good example. The following list of relationship states the following: An endpoint contains zero or more pools, each pool contains zero or more storage repositories and virtual machines, and each storage repository is related to zero or more virtual machines.

  • Endpoint 1:MC Pool

  • Pool 1:MC StorageRepository

  • Pool 1:MC VirtualMachine

  • StorageRepository M:M VirtualMachine

Once a ZenPack has been installed in a Virtana environment, additional relationships can be added, but existing relationships should never be removed or renamed. Doing so can cause problems in your Virtana environment (for example, errors when attempting to delete devices). Therefore, please carefully consider the naming and organization of your custom relationships before deploying your ZenPack to a Production environment.

Adding classes and relationships

To add classes and relationships to zenpack.yaml you add entries to the top-level classes and class_relationships fields. The following example shows a XenServer Endpoint device type along with Pool, StorageRepository, and VirtualMachine component types.

zenpack.yaml

name: ZenPacks.example.XenServer

classes:
  DEFAULTS:
    base: [zenpacklib.Component]

  XenServerEndpoint:
    base: [zenpacklib.Device]
    label: Endpoint

  XenServerPool:
    label: Pool

    properties:
      ha_enabled:
        type: boolean
        label: HA Enabled
        short_label: HA

      ha_allow_overcommit:
        type: boolean
        label: HA Allow Overcommit
        short_label: Overcommit

  XenServerStorageRepository:
    label: Storage Repository

    properties:
      physical_size:
        type: int
        label: Physical Size
        short_label: Size

  XenServerVirtualMachine:
    label: Virtual Machine

    properties:
      vcpus_at_startup:
        type: int
        label: vCPUs at Startup
        short_label: vCPUs

class_relationships:
  - XenServerEndpoint 1:MC XenServerPool
  - XenServerPool 1:MC XenServerStorageRepository
  - XenServerPool 1:MC XenServerVirtualMachine
  - XenServerStorageRepository M:M XenServerVirtualMachine

DEFAULTS can be used in classes just like in zProperties to avoid repetitively setting the same field for many entries. Note specifically how XenServerPool, XenServerStorageRepository and XenServerVirtualMachine will inherit the default while XenServerEndpoint overrides it.

Classes and their properties allow for a wide range of control. See the following section for details.

Extending ZenPackLib classes

Occasionally, you may wish to add your own custom methods to your YAML-defined classes or otherwise extend their functionality beyond ZenPackLib’s current capabilities. Doing so requires creating a Python file that imports and overrides the class you wish to modify, and this is relatively straightforward.

Suppose we have a component class called “BasicComponent”, and we want to provide a method called “hello world” that, when called, will return the string “Hello World” and display it in the component grid.

Our YAML file looks like this:

zenpack.yaml

name: ZenPacks.zenoss.BasicZenPack

class_relationships:
  - BasicDevice 1:MC BasicComponent

classes:
  BasicDevice:
    base: [zenpacklib.Device]

  BasicComponent:
    base: [zenpacklib.Component]
    properties:
      hello_world:
        # this will appear as the column header
        # in the component grid
        label: Hello World
        # this should be displayed in the component grid
        grid_display: true
        # tells ZenPackLib that this isn't a typical
        # property like a string, integer, boolean, etc...
        api_only: true
        # this is the type of property
        api_backendtype: method

First, the ZenPack’s init file (ZenPacks/zenoss/BasicZenPack/__init__.py) should contain the following content.

__init__.py

from ZenPacks.zenoss.ZenPackLib import zenpacklib

CFG = zenpacklib.load_yaml()
schema = CFG.zenpack_module.schema

Next, we create a file for the component extension (ZenPacks/zenoss/BasicZenPack/BasicComponent.py) with the following content.

BasicComponent.py

from . import schema

class BasicComponent(schema.BasicComponent):
    """Class override for BasisComponent"""

    def hello_world(self):
        return 'Hello World!'

The “Hello World” column will now display in the component grid, and the string “Hello World!” will be printed in each row of component output.

We can also override ZenPackLib’s built-in methods, but must be careful doing so to avoid undesirable results. Supposing that our YAML specifies some monitoring templates (not defined here) for BasicComponent, and for some reason we want to randomly choose which ones are displayed in the GUI. To do so, we need to override the “getRRDTemplates” method.

Our YAML file is modified:

zenpack.yaml

name: ZenPacks.zenoss.BasicZenPack

class_relationships:
  - BasicDevice 1:MC BasicComponent

classes:
  BasicDevice:
    base: [zenpacklib.Device]

  BasicComponent:
    base: [zenpacklib.Component]
    properties:
      hello_world:
        label: Hello World
        api_only: true
        api_backendtype: method
        grid_display: true

    monitoring_templates: [ThisTemplate, ThatTemplate]

And we further modify our BaseComponent.py as follows:

BasicComponent.py

import random
from . import schema

class BasicComponent(schema.BasicComponent):
    """Class override for BasisComponent"""

    def hello_world(self):
        return 'Hello World!'

    def getRRDTemplates(self):
        """Return randomly chosen templates."""
        templates = []
        # make sure we call the base method when we override it
        for template in super(BasicComponent, self).getRRDTemplates():
            # rolling the dice
            if bool(random.randint(0,1)):
                templates.append(template)
        return templates

The key point to remember here is the call to super(BasicComponent, self).getRRDTemplates(). This instructs Python to use the original method before we modify its output. Similar care must be exercised when overriding built-in methods and properties, assuming a safer method cannot be found.

Support for multiple YAML files

For particularly complex ZenPacks the YAML file can grow to be quite large, potentially making management cumbersome. To address this concern, ZenPackLib supports splitting the zenpack.yaml files into multiple files. The following conditions should be observed when using multiple files:

  • The YAML files should have a .yaml extension.

  • The “load_yaml” method will detect and load yaml files automatically. This behavior can be overridden by calling load_yaml(yaml_doc=[doc1, doc2]). In this case the full file paths will need to be specified:

    __init__.py

    import os
    files = ['file1.yaml', 'file2.yaml']
    YAML_DOCS = [os.path.join(os.path.dirname(__file__), f) for f in files]
    from ZenPacks.zenoss.ZenPackLib import zenpacklib
    CFG = zenpacklib.load_yaml(yaml_doc=YAML_DOCS)
    schema = CFG.zenpack_module.schema
  • The name parameter (ZenPack name), if used in multiple files, should be identical between them.

  • If a given YAML section (device_classes, classes, device_classes, etc) is split between files, then each file should give the complete path to the defined objects.

    file1.yaml

    name: ZenPacks.zenoss.BasicZenPack
    
    class_relationships:
      - BaseComponent 1:MC AuxComponent
    
    classes:
      BasicDevice:
        base: [zenpacklib.Device]
        monitoring_templates: [BasicDevice]
    
      BasicComponent:
        base: [zenpacklib.Component]
        monitoring_templates: [BasicComponent]

    file2.yaml

    class_relationships:
      - BaseDevice 1:MC BaseComponent
    
    classes:
      SubComponent:
        base: [BasicComponent]
        monitoring_templates: [SubComponent]
    
      AuxComponent:
        base: [SubComponent]
        monitoring_templates: [AuxComponent]
  • Using conflicting parameters (like setting different DEFAULTS for the same entity in different files) will likely lead to undesirable results.

Class fields

The following fields are valid for a class entry.

name (required, string, default = implied from key in classes map)

Name (e.g. XenServerEndpoint). Must be a valid Python class name.

base (optional, list, default = [zenpacklib.Component])

List of base classes to extend.

meta_type (optional, string, default = name)

Globally unique name for the class.

label (optional, string, default = meta_type)

Human-friendly label for the class.

plural_label (optional, string, default = label with s appended)

Plural form of label.

short_label (optional, string, default = label)

Short form of label. Used when display space is limited.

plural_short_label (optional, string, default = short_label with s appended)

Plural form of short_label.

icon (optional, string, default = name with a .png suffix in resources/icon/)

Filename (in resources/) for icon.

label_width (optional, integer, default = 80)

Width of label text in pixels.

plural_label_width (optional, integer, default = label_width + 7)

Width of plural_label text in pixels.

content_width (optional, integer, default = label_width)

Expected width of object's title in pixels.

auto_expand_column (optional, string, default = name)

Column (property) to auto-expand in component grid.

initial_sort_column (optional, string, default = name)

Column (property) by which component grid is initially sorted.

order (optional, integer, default = 100)

Order to display this class among other classes. See Order field.

filter_display (optional, boolean, default = true)

Will related components be filterable by components of this type?

filter_hide_from (optional, list, default = [] (empty list))

Classes for which this class should not show in the filter dropdown.

monitoring_templates (optional, list, default = [] (empty list))

List of monitoring template names to bind to components of this type.

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

Properties for this class.

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

Relationship overrides for this class.

impacts (optional, list, default = [] (empty list))

Relationship or method names that return an object, or objects. The returned objects are "impacted by" objects of this class.

impacted_by (optional, list, default = [] (empty list))

Relationship or method names that return an object, or objects. The returned objects "impact" objects of this class.

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

Impact trigger policy definitions for this class.

dynamicview_views (optional, list, default = [service_view])

Names of Dynamic Views objects of this class can appear in.

dynamicview_group (optional, string, default = plural_short_label)

Dynamic View group name for objects of this class. Can be overridden by implementing getDynamicViewGroup().

dynamicview_weight (optional, integer, default = (order * 10) + 1000))

Dynamic View weight for objects of this class. Higher numbers are further to the right. Can be overridden by implementing getDynamicViewWeight().

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

Map of Dynamic View relationship types for this class. Map values are lists like those in impacts and impacted_by.

extra_paths (optional, list, default = [] (empty list))

Extra paths under which objects of this class will be indexed.

Order field

The order field takes any integer value between 1 and 100. However, its behavior depends on whether it applies to a Class, a Property, or a Relationship. For a relationship, order behavior can further depend on the type of relationship.

There is an overall clustering for like items in the GUI component grid, following this order:

  1. Containing components

  2. Properties

  3. Contained components

With containing relationships listed before visible properties and finally any non-containing relationships.

Earlier (pre-2.0) versions of ZenPackLib accepted float arguments for order. However, ZenPackLib now normalizes these values behind the scenes to integers between 1 and 100.

Extra paths field

Each item in extra_paths is expressed as a tuple of regular expression patterns that are matched in order against the actual relationship path structure as it is traversed.

To facilitate matching, we construct a compiled set of regular expressions that can be matched against the entire path string, from root to leaf.

The following:

("orgComponent", "(parentOrg)+")

Is transformed into a “pattern stream”, which is a list of regular expressions that can be applied incrementally as we traverse the possible paths:

(re.compile(^orgComponent), re.compile(^orgComponent/(parentOrg)+), re.compile(^orgComponent/(parentOrg)+/?$&rsquo;)

Once traversal embarks upon a stream, these patterns are matched in order as the traversal proceeds, with the first one to fail causing recursion to stop. When the final one is matched, then the objects on that relation are matched. Note that the final one may match multiple times if recursive relationships are in play.

Class property fields

The following fields are valid for a class property entry.

name (required, string, default = implied from key in relationships map)

Name (e.g. ha_enabled). Must be a valid Python variable name.

type (optional, string, default = string)

Type of property: string, int, float, boolean, lines, password, or entity. All types are strictly enforced except entity.

default (optional)

Default value of property.

label (optional, string, default = name)

Human-friendly label for the property.

short_label (optional, string, default = label)

Short form of label. Used as a column header where space is limited.

label_width (optional, integer, default = 80)

Width of label text in pixels.

content_width (optional, integer, default = label_width)

Expected width of property's value in pixels.

display (optional, boolean, default = true)

Should this property be shown as a column and in details?

details_display (optional, boolean, default = true)

Should this property be shown in details?

grid_display (optional, boolean, default = true)

Should this property be shown as a column?

order (optional, integer, default= 100)

Order to display this property among other properties (1-100).

editable (optional, boolean, default = false)

Should this property be editable in details?

renderer (optional, string, default = None (renders value as-is))

JavaScript renderer for relationship value.

api_only (optional, boolean, default = false)

Should this property be for the API only? The property or method (see api_backendtype) must be manually implemented if this is set to true.

api_backendtype (optional, string, default = property)

Implementation style for the property if api_only is true. Must be property or method.

enum (optional, map, default = {})

Enumeration map for property. Set to something like {1: OK, 2: ERROR} to provide text labels for property values.

datapoint (optional, string, default = None)

The datasource_datapoint value to use as the value for this property.

datapoint_default (optional, any, default = None)

Default value for property if datapoint is set, but no data exists.

datapoint_cached (optional, boolean, default = true)

Should the value for datapoint be cached for a limited time? Can improve UI performance.

index_type (optional, string, default = None (no indexing))

Type of indexing for the property: field or keyword.

index_scope (optional, string, default = device)

Scope of index: device or global. Only applies if index_type is set.

Relationship override fields

The following fields are valid for a relationship override entry.

name (required, string, default = implied from key in relationships map)

Name (e.g. xenServerPools). Must match a relationship name defined in class_relationships.

label (optional, string, default = label of class to which the relationship refers)

Human-friendly label for the relationship.

short_label (optional, string, default = label or short_label of the referred class)

Short form of label. Used where space is limited.

label_width (optional, integer, default = label_width of the referred class)

Width of label text in pixels.

content_width (optional, integer, default = varies depending on relationship type)

Expected width of relationship's value in pixels.

display (optional, boolean, default = true)

Should this relationship be shown as a column and in details?

details_display (optional, boolean, default = true)

Should this relationship be shown in details?

grid_display (optional, boolean, default = true)

Should this relationship be shown as a column?

order (optional, integer, default = 100)

Order to display this relationship among other relationships and properties (1-100).

renderer (optional, string, default = None)

JavaScript renderer for relationship value.

render_with_type (optional, boolean, default = false)

Should related object be rendered with its type?

Impact trigger fields

The following fields are valid for an Impact trigger entry.

name (required, string, default = implied from key in properties map)

Name (e.g. avail_pct_5). Must be a valid Python variable name.

policy (optional, string, default = AVAILABILITY)

Policy type: AVAILABILITY or PERFORMANCE

trigger (optional, string, default = policyPercentageTrigger)

Trigger type: policyPercentageTrigger, policyThresholdTrigger, negativeThresholdTrigger

threshold (optional, integer, default = 50)

Numerical boundary for the trigger.

state (optional, string, default = UNKNOWN)

State of this object when trigger criteria met (see note).

dependent_state (optional, string, default = UNKNOWN)

State of dependent objects meeting trigger criteria (see note).

Note

Valid values for both state and dependent_state depend on the choice of policy parameter:

  • AVAILABILITY: DOWN, UP, DEGRADED, ATRISK, or UNKNOWN

  • PERFORMANCE: UNACCEPTABLE, DEGRADED, ACCEPTABLE, or UNKNOWN

  • CAPACITY: UNACCEPTABLE, REDUCED, ACCEPTABLE, or UNKNOWN