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 rmThe 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
zenpacklibscript with--dump-event-classesoption, 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 Pythonyamlpackage handles strings. Either of these two formats is acceptable when used inzenpack.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
ERRORstatus. 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 --updatecommand 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:
-c, --create: Create a new zenpacklib-enabled ZenPack source directory.
-l, --lint: Review syntax and correctness on a YAML file.
-d, --diagram: Export yUML (yuml.me) class diagram from a YAML file.
-t, --dump-templates: Export existing monitoring templates to YAML.
-e, --dump-event-classes: Export existing event classes and mappings to YAML.
-r, --dump-process-classes: Export existing process classes to YAML.
-p, --paths: Using the specified device, print a report of paths between objects.
-o, --optimize: Optimize the layout of an existing zenpack.yaml file.
--version: Display the verion of ZDK installed on your system.
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 NetBotzSensorRunning 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
verboseparameter, if set to True, will enable logging for this particular ZenPack. We recommend enablingverboseduring ZenPack development so that various error messages can be seen. We also recommend disablingverboseprior to release of your ZenPack as some warning messages may not be useful to the end user.The
levelparameter 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: WidgetzProperties
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, andstring.default(optional)Default value for property. Default value depends on the type:
boolean:
falselines:
[]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: 300Each 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: 300There 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: 300Since 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: trueThe 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: 60As 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: AREAThis 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.
On the
widgeter1device.In the /Server/ACME/Widgeter device class.
In the /Server/ACME device class.
In the /Server device class.
In the / device class.
The first template that matches by name will be used for the device. No template will be bound if no matching template is found in any of these locations.
It is because of this search up the hierarchy that allows the monitoring template’s location to be used to restrict to which devices it can be bound. For example, by locating our monitoring template in the /Server/ACME device class we make it available to be bound for all devices in /Server/ACME and /Server/ACME/Widgeter, but we also make unavailable to be bound in other device classes such as /Server or /Network/Cisco.
After deciding on the right location for a monitoring template should then decide where it should be bound. Remember that to cause the template to be used it must be bound. This is done by adding the template’s name to the zDeviceTemplates zProperty of a device class. See the following example that shows how to bind the WidgeterHealth monitoring template to the /Server/ACME/Widgeter device class.
zenpack.yaml
name: ZenPacks.acme.Widgeter
device_classes:
/Server/ACME/Widgeter:
zProperties:
zDeviceTemplates:
- WidgeterHealth
templates:
WidgeterHealth: {}Note that zDeviceTemplates didn’t have to be declared in the ZenPack’s zProperties field because it’s a standard 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.
targetPythonClassoptional, 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.
The SNMP datasource type performs an SNMP GET operation using the oid field. The field is required (string) and has no default.
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.
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.
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: sumFurther 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
GAUGEorDERIVE.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
typeisn'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.
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.
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,AREAorDONTDRAW.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
AREAtypes.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
dpNamebe 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.
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.
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: WidgetWhen 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.
WidgetorWidget/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 XenServerVirtualMachineDEFAULTS 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: methodFirst, 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 templatesThe 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
nameparameter (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
DEFAULTSfor 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 =labelwithsappended)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_labelwithsappended)Plural form of
short_label.icon(optional, string, default =namewith a.pngsuffix inresources/icon/)Filename (in
resources/) for icon.label_width(optional, integer, default = 80)Width of
labeltext in pixels.plural_label_width(optional, integer, default =label_width+ 7)Width of
plural_labeltext in pixels.content_width(optional, integer, default =label_width)Expected width of object's
titlein 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
impactsandimpacted_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:
Containing components
Properties
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)+/?$’)
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, orentity. All types are strictly enforced exceptentity.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_onlyis true. Must bepropertyormethod.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:
fieldorkeyword.index_scope(optional, string, default =device)Scope of index:
deviceorglobal. Only applies ifindex_typeis 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 =labelof class to which the relationship refers)Human-friendly label for the relationship.
short_label(optional, string, default =labelorshort_labelof the referred class)Short form of label. Used where space is limited.
label_width(optional, integer, default =label_widthof 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:
AVAILABILITYorPERFORMANCEtrigger(optional, string, default =policyPercentageTrigger)Trigger type:
policyPercentageTrigger,policyThresholdTrigger,negativeThresholdTriggerthreshold(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
Device link providers
A device link provider is a subscriber interface that gives a hook for adding context-specific html links (for example, the device links on the Device Details page). Zenpacklib provides a simple class to search the global catalog, device class catalog, or a device local catalog that match a specific query.
zenpack.yaml
name: ZenPacks.zenoss.BasicZenPack
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]To search the global catalog, set global_search to true. If the catalog you wish to search is in a specific device class, set global_search to false and specify the class name with device_class. To search a catalog on the local device, simply set global_search to false and do not set device_class. You can use one or more queries to match up devices/components. In the above example, the XenServer provider will search the global device catalog and match any device’s manageIp attribute with the current device’s vm_id attribute.
Device link provider fields
The following fields are valid for a device link provider entry.
link_title(required, string, default = implied from key in link_providers map)Title that appears on the overview page of the type of device or component.
global_search(optional, boolean, default = true)Search the global catalog?
link_class(optional, string, default =Products.ZenModel.Device.Device)Python class on which this provider will apply. Requires full python class name.
device_class(optional, string, default = None)Device class containing the catalog to search.
catalog(optional, string, default =device)Catalog name to search for linked devices or components.
queries(required, list, default =[](empty list))Queries to use to match a linked device/component.
Each query must be in remote:local format, meaning that the catalog search will match a remote attribute with a local attribute. The local search term could also be actual text. Examples:
id:manageIpwill match the remoteidattribute with the local device’smanageIpattribute, andmeta_type:ClusterDevicewill match themeta_typeon a remote device toClusterDevice.