search

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:

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:

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