Classes and Relationships
Classes and relationships form the model that forms the basis for everything Zenoss 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.
Contents
Standard Classes
The standard classes exist on all Zenoss 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)
- DeviceHW (hw)
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
- zenpacklib.HWComponent
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 Zenoss’ 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 Zenoss 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 Zenoss has a single primary path that describes where it is stored in the tree that is the Zenoss 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 Zenoss environment, additional relationships can be added, but existing relationships should never be removed or renamed. Doing so can cause problems in your Zenoss 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.
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:
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.
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.
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:
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:
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_.pyimport 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.yamlname: 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.yamlclass_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 | Description | Required | Type | Default Value |
---|---|---|---|---|
name | Name (e.g. XenServerEndpoint). Must be a valid Python class name. | yes | string | (implied from key in classes map) |
base | List of base classes to extend. See Classes. | no | list<classname> | [zenpacklib.Component] |
meta_type | Globally unique name for the class. | no | string | (same as name) |
label | Human-friendly label for the class. | no | string | (same as meta_type) |
plural_label | Plural form of label. | no | string | (same as label with an "s" suffix) |
short_label | Short form of label. Used when display space is limited. | no | string | (same as label) |
plural_short_label | Plural form of short_label. | no | string | (same as short_label with an "s" suffix) |
icon | Filename (in resources/) for icon. | no | string | (same as name with a ".png" suffix in resources/icon/) |
label_width | Width of label text in pixels. | no | integer | 80 |
plural_label_width | Width of plural_label text in pixels. | no | integer | (same as label_width + 7) |
content_width | Expected width of object's title in pixels. | no | integer | (same as label_width) |
auto_expand_column | Column (property) to auto-expand in component grid. | no | string | name |
initial_sort_column | Column (property) by which component grid is initially sorted. | no | string | name |
order | Order to display this class among other classes. | no | integer (1-100) | 100 (See Order Field) |
filter_display | Will related components be filterable by components of this type? | no | boolean | true |
filter_hide_from | Classes for which this class should not show in the filter dropdown. | no | list<classname> | [] (empty list) |
monitoring_templates | List of monitoring template names to bind to components of this type. | no | list<string> | [] (empty list) |
properties | Properties for this class. | no | map<name, Class Property> | {} (empty map) |
relationships | Relationship overrides for this class. | no | map<name, Relationship Override> | {} (empty map) |
impacts | Relationship or method names that return an object, or objects. The returned objects are "impacted by" objects of this class. | no | list<relationship_or_method_name> | [] (empty list) |
impacted_by | Relationship or method names that return an object, or objects. The returned objects "impact" objects of this class. | no | list<relationship_or_method_name> | [] (empty list) |
impact_triggers | Impact trigger policy definitions for this class. | no | map<name, Impact Trigger> | {} (empty map) |
dynamicview_views | Names of Dynamic Views objects of this class can appear in. | no | list<dynamicview_view_name> | [service_view] |
dynamicview_group | Dynamic View group name for objects of this class. Can be overridden by implementing getDynamicViewGroup(). | no | string | (same as plural_short_label) |
dynamicview_weight | Dynamic View weight for objects of this class. Higher numbers are further to the right. Can be overridden by implementing getDynamicViewWeight(). | no | integer | (order * 10) + 1000 |
dynamicview_relations | Map of Dynamic View relationship types for this class. Map values are lists like those in impacts and impacted_by. | no | map<type, list<relation_or_method>> | {} (empty map) |
extra_paths | Extra paths under which objects of this class will be indexed. | no | list<list<regexp>> See Extra Paths Field. | [] (empty list) |
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 | Description | Required | Type | Default Value |
---|---|---|---|---|
name | Name (e.g. ha_enabled). Must be a valid Python variable name. | yes | string | (implied from key in properties map) |
type | Type of property: string, int, float, boolean, lines, password or entity. All types are strictly enforced except for entity. | no | string | string |
default | Default value for property. | no | (varies depending on type) | None |
label | Human-friendly label for the property. | no | string | (same as name) |
short_label | Short form of label. Used as a column header where space is limited. | no | string | (same as label) |
label_width | Width of label text in pixels. | no | integer | 80 |
content_width | Expected width of property’s value in pixels. | no | integer | (same as label_width) |
display | Should this property be shown as a column and in details? | no | boolean | true |
details_display | Should this property be shown in details? | no | boolean | true |
grid_display | Should this property be shown as a column? | no | boolean | true |
order | Order to display this property among other properties. (1-100) | no | integer | 100 |
editable | Should this property be editable in details? | no | boolean | false |
renderer | JavaScript renderer for property value. | no | string | None (renders value as-is) |
api_only | 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. | no | boolean | false |
api_backendtype | Implementation style for the property if api_only is true. Must be one of: property or method . | no | string | property |
enum | Enumeration map for property. Set to something like {1: OK, 2: ERROR} to provide text labels for property values. | no | map<value, label> | {} (empty map) |
datapoint | datasource_datapoint value to use as the value for this property. | no | string | None |
datapoint_default | Default value for property if datapoint is set, but no data exists. | no | any | None |
datapoint_cached | Should the value for datapoint be cached for a limited time? Can improve UI performance. | no | boolean | true |
index_type | Type of indexing for the property: field or keyword. | no | string | None (no indexing) |
index_scope | Scope of index: device or global. Only applies if index_type is set. | no | string | device |
Relationship Override Fields
The following fields are valid for a relationship override entry.
Name | Description | Required | Type | Default Value |
---|---|---|---|---|
name | Name (e.g. xenServerPools). Must match a relationship name defined in class_relationships. | yes | string | (implied from key in relationships map) |
label | Human-friendly label for the relationship. | no | string | (label of class to which the relationship refers) |
short_label | Short form of label. Used where space is limited. | no | string | (same as label or referred class' short_label) |
label_width | Width of label text in pixels. | no | integer | (same as referred class' label_width) |
content_width | Expected width of relationship's value in pixels. | no | integer | (varies depending on relationship type) |
display | Should this relationship be shown as a column and in details? | no | boolean | true |
details_display | Should this relationship be shown in details? | no | boolean | true |
grid_display | Should this relationship be shown as a column? | no | boolean | true |
order | Order to display this relationship among other relationships and properties. (1-100) | no | integer | 100 |
renderer | JavaScript renderer for relationship value. | no | string | None |
render_with_type | Should related object be rendered with its type? | no | boolean | false |
Impact Trigger Fields
The following fields are valid for an Impact trigger entry.
Name | Description | Required | Type | Default Value |
---|---|---|---|---|
name | Name (e.g. avail_pct_5). Must be a valid Python variable name. | yes | string | (implied from key in properties map) |
policy | Policy type: AVAILABILITY or PERFORMANCE | no | string | AVAILABILITY |
trigger | Trigger type: policyPercentageTrigger , policyThresholdTrigger , negativeThresholdTrigger | no | string |
|
threshold | Numerical boundary for the trigger. | no | integer | 50 |
state | State of this object when trigger criteria met (see note). | no | string | UNKNOWN |
dependent_state | State of dependent objects meeting trigger criteria (see note). | no | string | UNKNOWN |
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