Tutorials
The following tutorials provide step-by-step instructions on using zenpacklib to extend Virtana is common ways.
This tutorial starts with the very basics of creating a ZenPack through Virtana’ web interface and adding configuration to it. Then it progresses to extending the model, creating a modeler plugin, monitoring components, and then to event management with SNMP traps as an example.
This is most likely the first tutorial you should do.
In this tutorial the basics are skipped and we jump right into extending the model, modeling a custom HTTP API, and monitoring the same API using the zenpython daemon provided by the PythonCollector ZenPack.
This is a more advanced tutorial that contains more advanced Python code.
Prerequisites
To follow the steps in these tutorials you will need to have access to the following:
A Linux server with Virtana installed on it. This should not be a Virtana server you care about. We will break things.
An SSH client to connect to your Virtana server. PuTTY works well for Windows, ssh from the command line works well for macOS and Linux.
These tutorials.
You may need experience in the following areas to more easily follow these tutorials.
Virtana: Familiarity administration and configuration.
Linux: Ability to move around the file system, manage files and run commands.
Programming: Any type of programming or scripting experience will help.
SNMP
This tutorial describes a common approach to monitoring an SNMP-enabled device. We’ll start with the basics that can be done without writing a line of code, and then move on to more sophisticated capabilities.
For purposes of this guide we’ll be building a ZenPack to support a NetBotz environmental sensor device. This device has a variety of sensors that monitor temperature, humidity, dew point, audio levels and air flow.
This tutorial assumes your system is already setup as described in Development environment and Getting started.
Tools
To configure Virtana to monitor a device using SNMP, it is necessary to understand a bit about SNMP and the specific capabilities of your device. This section will walk you through using Net-SNMP, smidump, and snmpsim to learn about SNMP and your device.
Installing Net-SNMP
In the SNMP world the client is referred to as a manager and the server is referred to as the agent. Net-SNMP is software that provides both an agent that’s used in all sorts of devices, and many command line tools that act as manager. We’re only going to need the command line tools, so we’ll be installing the net-snmp-utils package.
You can install Net-SNMP’s command line tools by running the following command as root.
yum -y install net-snmp-utils
Installing libsmi
smidump is a useful command line tool for converting MIBs to other formats. We’ll be using it later in this tutorial to research what a MIB provides.
Install smidump by installing the libsmi package with the following command.
yum -y install libsmi
Installing the SNMP Simulator
When developing a ZenPack to monitor an SNMP-enabled device it can often be useful to simulate the device’s SNMP agent. There are many tools available to do this. For this guide we will be using the free snmpsim because it’s easy to install on our Virtana host.
Run the following commands as root to install
snmpsim:yum -y groupinstall "Development Tools" yum -y install python-devel easy_install snmpsim mkdir -p /usr/share/snmpsim/data mkdir -p /var/run/snmpsim useradd -U snmpsim chown snmpsim:snmpsim /var/run/snmpsim
Run the following command as root to install a NetBotz recording.
wget https://goo.gl/OJe2vL -O /usr/share/snmpsim/data/public.snmprec
Run the following command as root to run snmpsim.
snmpsimd.py \ --process-user=snmpsim \ --process-group=snmpsim \ --agent-udpv4-endpoint=172.17.0.1:161 \ --daemonize
Test the simulator with the following
snmpwalkcommand.snmpwalk -v2c -c public 172.17.0.1 sysDescr
You should see the following output.
SNMPv2-MIB::sysDescr.0 = STRING: Linux Netbotz01 2.4.26 #1 Wed Oct 31 18:09:53 CDT 2007 ppc
Using snmpwalk
The tool you’ll be using most often is called snmpwalk. All SNMP values are arranged on a tree, and snmpwalk allows you to query for all data under a given branch of that tree. See the following example that walks all values under the system branch.
Run the snmpwalk command.
snmpwalk -v2c -c public 172.17.0.1 system
SNMPv2-MIB::sysDescr.0 = STRING: Linux Netbotz01 2.4.26 #1 Wed Oct 31 18:09:53 CDT 2007 ppc SNMPv2-MIB::sysObjectID.0 = OID: SNMPv2-SMI::enterprises.5528.100.20.10.2006 DISMAN-EVENT-MIB::sysUpTimeInstance = Timeticks: (7275488) 20:12:34.88 SNMPv2-MIB::sysContact.0 = STRING: unknown SNMPv2-MIB::sysName.0 = STRING: Netbotz01 SNMPv2-MIB::sysLocation.0 = STRING: Z1 Rack02 NetBotz01
We can see that this NetBotz device seems to be based on Linux and that we have some more-or-less useful information about the device’s name, location and administrative contact.
The second line with the sysObjectID has an unusual value. It’s a partially decoded OID. It isn’t decoded enough for us to know what it means. SNMP tools including Net-SNMP use MIB files to decode these OIDs into human readable values. In fact, we’re only able to read most of the output above because Net-SNMP has a set of standard MIBs enabled by default.
Let’s run that command again, but use the -On flag to tell snmpwalk not to decode OIDs.
snmpwalk -v2c -c public -On 172.17.0.1 system
.1.3.6.1.2.1.1.1.0 = STRING: Linux Netbotz01 2.4.26 #1 Wed Oct 31 18:09:53 CDT 2007 ppc .1.3.6.1.2.1.1.2.0 = OID: .1.3.6.1.4.1.5528.100.20.10.2006 .1.3.6.1.2.1.1.3.0 = Timeticks: (7275488) 20:12:34.88 .1.3.6.1.2.1.1.4.0 = STRING: unknown .1.3.6.1.2.1.1.5.0 = STRING: Netbotz01 .1.3.6.1.2.1.1.6.0 = STRING: Z1 Rack02 NetBotz01
While this data is mostly less valuable than the decoded version above, it’s more useful for a single reason. We can take that .1.3.6.1.4.1.5528.100.20.10.2006 value and search the Internet for it. It’s best to remove the leading . and search for 1.3.6.1.4.1.5528.100.20.10.2006 instead. This should lead you to the NETBOTZV2-MIB which will contain the decoding information we need to learn more about this device.
Run the following command to download NETBOTZ-V2-MIB.mib into /usr/share/snmp/mibs/.
wget https://goo.gl/0v4Kti -O /usr/share/snmp/mibs/NETBOTZV2-MIB.mib
Now we can run the original snmpwalk command again with the addition of the -m all option. This option tells Net-SNMP tools to use all MIBs.
snmpwalk -v2c -c public -m all 172.17.0.1 system
SNMPv2-MIB::sysDescr.0 = STRING: Linux Netbotz01 2.4.26 #1 Wed Oct 31 18:09:53 CDT 2007 ppc SNMPv2-MIB::sysObjectID.0 = OID: NETBOTZV2-MIB::netBotz420ERack DISMAN-EVENT-MIB::sysUpTimeInstance = Timeticks: (7275488) 20:12:34.88 SNMPv2-MIB::sysContact.0 = STRING: unknown SNMPv2-MIB::sysName.0 = STRING: Netbotz01 SNMPv2-MIB::sysLocation.0 = STRING: Z1 Rack02 NetBotz01
Now we can see that the sysObjectID is NETBOTZV2-MIB::netBotz420ERack. This gives us a better idea of exactly what kind of device it is. We’ll see that as we look deeper into this device that the NETBOTZV2-MIB will prove more useful.
Default Net-SNMP options
The snmpwalk usage showed three primary command line options that we tend to use most of the time. Net-SNMP allows you to specify these in a configuration file so you don’t have to type them every time. I recommend doing this.
Create /etc/snmp/snmp.conf and add the following lines.
defVersion v2c defCommunity public mibs ALL
These lines add the following equivalent command line options respectively:
-v2c-c public-m all
So now we can run this command.
snmpwalk 172.17.0.1 sysObjectID
And get the same results as if we ran.
snmpwalk -v2c -c public -m all 172.17.0.1 sysObjectID
This will save you time while developing this ZenPack, and others in the future.
Decoding and Encoding OIDs
Often it can be useful to turn numeric OIDs into their human-readable equivalent, or vice-versa. The snmptranslate command can be used for this. See the following examples.
OID to name:
snmptranslate .1.3.6.1.4.1.5528.100.20.10.2006
NETBOTZV2-MIB::netBotz420ERack
Name to OID:
snmptranslate -On NETBOTZV2-MIB::netBotz420ERack
.1.3.6.1.4.1.5528.100.20.10.2006
Device monitoring
This section will cover monitoring device-level metrics using SNMP. This requires no code, and you can find instructions for doing it in the normal Virtana documentation. However, there are some extra considerations and steps required to package your configuration in a ZenPack.
Commands in this section should be run on the host as the zenoss user unless otherwise noted.
Create a ZenPack
The first step will be to create and install a ZenPack to contain all of the NetBotz monitoring functionality we’re going to build.
cd /z zenpacklib --create ZenPacks.training.NetBotz zenpack --link --install ZenPacks.training.NetBotz
We should also restart at least Zope after installing the ZenPack so that we can work with it in the web interface.
serviced service restart Zope
Create a Device Class
To support our new NetBotz environmental sensor device we will want to create a new device class. This will give us full control over how these types of devices are modeled and monitored. Use the following steps to add a new device class.
Navigate to the Infrastructure view.
Select the root of the DEVICES tree.
Click the + button at the bottom of the list to add a new organizer.
Set the Name to
NetBotzthen click SUBMIT.The new NetBotz device will now be selected. We’ll want to check on some important configuration properties using the following steps.
Set device class properties
Click the DETAILS button at the top of the list.
Select Modeler Plugins.
The modeler plugins are what model information about the device. We should see a list something like the following. This list is being acquired from the root (
/or/Devices) device class.zenoss.snmp.NewDeviceMap
zenoss.snmp.DeviceMap
zenoss.snmp.InterfaceMap
zenoss.snmp.RouteMap
This is a good basic list that uses standard MIB-2 support that works with most SNMP-enabled devices. However, it’s unlikely that we care about the routing table on our environmental sensors, so there’s no reason to model it.
Remove zenoss.snmp.RouteMap from the list.
Click Save.
Now you can see the Path at which our modeler plugin configuration is set has changed from / to /NetBotz. This allows us to know that regardless of what the user sets their default modeler plugins to in the system that NetBotz appliances will be collected using the set of modeler plugins we configure here.
Select Configuration Properties from the left navigation pane.
There are a lot of configuration properties. You don’t have to worry about understanding all of them. However, some will be critical to monitoring NetBotz appliances. We know that we’re going to be using SNMP so let’s make sure that it’s enabled.
Find the zSnmpMonitorIgnore property and set its value to true.
Now set the value for zSnmpMonitorIgnore to false.
The reason for flipping the value back to it’s original value is the same as saving the list of modeler plugins. While the system default is to have SNMP monitoring enabled, a user could easily disable it globally and cause our NetBotz monitoring to stop working. By flipping the value, we’ve set it locally within our device class and will prevent changes in the global default from affecting the operation of our ZenPack.
Add device class to ZenPack
Now that we’ve setup the NetBotz device class, it’s time to add it to our ZenPack using the following steps. Adding a device class to your ZenPack causes all settings in that device class to be added to the ZenPack. This includes modeler plugin configuration, configuration property values and monitoring templates.
Make sure that you have the NetBotz device class selected in the Infrastructure view.
Choose Add to ZenPack from the gear menu in the bottom-left.
Select your NetBotz ZenPack then click SUBMIT.
Add a NetBotz device
This would be a great time to add a NetBotz device to our new /NetBotz device class. We haven’t done anything in the way of customer monitoring. It can often be helpful to see what Virtana’ default settings will return for a device before we start adding features.
You can add a the device through the web interface, or on the command line using zendisc as follows:
z zendisc run --deviceclass=/NetBotz --device=172.17.0.1
I’ll often use zendisc from the command line only because the zenjobs daemon must be running to add jobs from the web interface. The zenjobs daemon is not required to be running when adding devices using zendisc from the command line because it immediately adds the device instead of scheduling a job to do it.
You should now see that Virtana was able to model some information about the device even though we haven’t added any custom monitoring. For example, you should see the following on the device in the web interface.
Overview
Hardware Manufacturer: NetBotz
Hardware Model: .1.3.6.1.4.1.5528.100.20.10.2006
OS Manufacturer: Unknown
OS Model: Linux 2.4.26
Components - Interfaces: 2 - eth0 and lo
If we were running the zenperfsnmp daemon, we’d start to see that Virtana was monitoring the uptime and interface metrics after about 10 minutes.
Configure monitoring templates
Before adding a monitoring template we should look to see what monitoring templates are already being used in our new device class.
Validate existing monitoring templates
We created the NetBotz device class directly within the root (or /) device class. This means that we’ll be inheriting the system default monitoring templates and binding. Use the following steps to validate this.
Select the NetBotz device class in the Infrastructure view.
Choose Bind Templates from the gear menu in the bottom-left.
You should only see Device (/Devices) in the Selected box. Depending on what other ZenPacks you have installed in the system you may see zero or more other templates listed in the Available box.
Now we investigate what this system default Device monitoring template does.
Click CANCEL on the Bind Templates dialog.
Click the DETAILS button at the top of the device class tree.
Select Device (/Devices) under Monitoring Templates.
You’ll see that there’s a single SNMP datasource named sysUpTime. If you expand this datasource you will see that it contains a single datapoint which is also named sysUpTime. This single datapoint named the same as its containing datasource is always what you’ll see for SNMP datasources. The reason for having the conceptual separation between datasources and datapoints is that other types of datasources such as COMMAND are capable of returning multiple datapoints.
You’ll note that this monitoring template has no threshold or graphs defined. This is unusual. Typically there’d be no reason to collect data that you weren’t going to either threshold against or show in a graph. The sysUpTime datapoint is an exception because it is shown on a device’s Overview page in the Uptime field and therefore doesn’t need to be graphed.
Let’s use snmpwalk to check if our NetBotz device supports sysUpTime. The OID listed for the sysUpTime datasource is 1.3.6.1.2.1.1.3.0 so we run the following command:
snmpwalk 172.17.0.1 1.3.6.1.2.1.1.3.0 DISMAN-EVENT-MIB::sysUpTimeInstance = Timeticks: (7275488) 20:12:34.88
This response indicates that the NetBotz device does support the sysUpTime OID. This is a mandatory field for SNMP devices to support so you will be able to get it in almost all cases.
Add a monitoring template
Now that we’ve validated that the existing Device monitoring template will work on our NetBotz device, we’ll add another monitoring template to collect additional information.
We could create a local copy of the Device monitoring template in the NetBotz device class and add new datasources, thresholds and graphs to it. However, this prevents us from taking advantage of changes made to the system default Device template in the future.
Follow these steps to create and bind a new template to the NetBotz device class.
Navigate to Advanced > Monitoring Templates.
Click the + button in the bottom-left to add a template.
Set the Name field to
NetBotzDevice.Set the Template Path field to /NetBotz.
Click SUBMIT.
Bind this template to the NetBotz device class.
Navigate to Infrastructure.
Select the NetBotz device class.
Choose Bind Templates from the gear menu in the bottom-left.
Move NetBotzDevice from available to selected.
Click SAVE.
Build the monitoring template
Now that we’ve created the NetBotzDevice monitoring template and bound it to the NetBotz device class, we need to add datasources, thresholds and graphs. We don’t already know what might be interesting to graph for each NetBotz device, so let’s go exploring with snmpwalk:
snmpwalk 172.17.0.1 .1.3 SNMPv2-MIB::sysDescr.0 = STRING: Linux Netbotz01 2.4.26 #1 Wed Oct 31 18:09:53 CDT 2007 ppc SNMPv2-MIB::sysObjectID.0 = OID: NETBOTZV2-MIB::netBotz420ERack ... lots of lines removed ... SNMPv2-MIB::snmpInTotalReqVars.0 = Counter32: 4406 ... and more removed ...
There isn’t much of interest to collect at the device level. By “device-level” I mean values that only have a single instance for the device. Typical examples of these kinds of metrics would be memory utilization or the previous sysUpTime example. With SNMP it can be easy to find these kinds of single-instance values because their OID ends in .0 as in SNMPv2-MIB::snmpInTotalReqVars.0.
We’ll get into monitoring multi-instance values in the component monitoring section.
Since there aren’t any extremely interesting single-instance values to collect, we’ll collect that snmpInTotalReqVars for illustrative purposes. We’ll need to know the numeric OID for this value. Use snmptranslate to find it:
$ snmptranslate -On SNMPv2-MIB::snmpInTotalReqVars.0 .1.3.6.1.2.1.11.13.0
Add an SNMP datasource
Use the steps below to add an SNMP datasource for snmpInTotalReqVars.
Navigate to Advanced > Monitoring Templates.
Expand NetBotzDevice then select /NetBotz.
Click + on the Data Sources pane.
Set Name to
snmpInTotalReqVars.Set Type to
SNMP.Click SUBMIT.
Best practice is to name SNMP datasources according to the name of the OID that’s being polled from the MIB.
Double-click to edit the snmpInTotalReqVars datasource.
Set OID to
1.3.6.1.2.1.11.13.0.Click SAVE.
A common mistake to make when setting the OID in a device-level template is to omit the trailing
.0. The reason this is common is that if you were using the MIB as reference instead of thesnmpwalkabove, you’d see that the OID forSNMPv2-MIB::snmpInTotalReqVarswas1.3.6.1.2.1.11.13instead of1.3.6.1.2.1.11.13.0. Due to this, I always recommend usingsnmpwalkto verify exactly what OID you should be polling.While Virtana will accept the OID with the leading
., I recommend omitting it. It isn’t necessary.
We now have a choice about how we want to handle the value that comes back from polling that OID. As you can see above in the snmpwalk output, it is a Counter32 type. This means that it starts at 0 and, in this case, increments each time an SNMP variable is requested. The most common way to handle counters like these is as a delta. It’s not very interesting to know how many variables have been requested since the device last rebooted, but it might be interesting to know how many variables are requested per second.
The default type for a datapoint is GAUGE which would record the actual value you see in the snmpwalk output. If we’d rather monitor the rate of requests, we’d change the datapoint type to DERIVE using the following steps.
Double-click on the snmpInTotalReqVars.snmpInTotalReqVars datapoint.
You may need to expand the snmpInTotalReqVars datasource first.
Set RRD Type to DERIVE.
Set RRD Minimum to
0.Click SAVE.
It is very important to always set the RRD Minimum to
0for DERIVE type datapoints. If you fail to do this, you will get large negative spikes in your data anytime the device reboots or the counter resets for any other reason.The only time you wouldn’t set a minimum of 0 is when the value you’re monitoring can increase and decrease and you’re interested in tracking rates of negative change as well as rates of positive change.
Add a threshold
Now we can add a threshold to our monitoring template. Let’s say we want to raise a warning event anytime the rate of SNMP variable requests exceeds 10 per second. This can be done with the following steps.
Click + on the Thresholds pane.
Set Name to
high SNMP variable request rate.Set Type to MinMaxThreshold.
Click ADD.
Double-click to edit the high SNMP variable request rate threshold.
Drag the snmpInTotalReqVars datapoint to the left box.
Set Severity to Warning.
Set Maximum Value to
10.Set Event Class to /Perf/Snmp.
Click SAVE.
A MinMaxThreshold can be used to handle a variety of conditions including over a maximum value, under a minimum value, outside a defined range or within a defined range. See the regular Virtana documentation for how to use each of these options.
Add a graph definition
Now we’ll add a graph so the user will be able to see the trend of SNMP variable requests per second over time. This can be done with the following steps.
Click + on the Graph Definitions pane.
Set Name to
SNMP Rates.Click SUBMIT.
Double-click to edit the SNMP Rates graph definition.
Set Units to
requests/sec.Set Min Y to
0.Click SUBMIT.
Always set the units for your graph. Also set the minimum Y axis and maximum Y axis values if you know what the possible limits are for the data. This results in graphs that are easier to read.
The format field should also be tweaked to best present the kind of data that is to be graphed. You can find more information on what can be used in the format field in the RRDtool rrdgraph_graph documentation under the PRINT section.
Select the SNMP Rates graph definition.
Choose Manage Graph Points from the gear menu.
Choose Data Point from the + menu.
Set Data Point to
snmpInTotalReqVars.Check Include Related Thresholds
Click SUBMIT.
Double-click to edit the snmpInTotalReqVars graph point.
Set Name to
Variables.Click SAVE.
The name of a graph point is what is displayed for it in the graph legend. You should always choose something short that describes the data and makes sense in context of the units chosen above.
Test monitoring template
The quick way to check if we’ve been successful in creating and binding our monitoring template is to navigate to the NetBotz device we added to the system and verify that we see our NetBotzDevice (/NetBotz) monitoring template listed at the bottom of the device’s left navigation pane.
Now we can test that our datasource will be collected by running the following command to do a single collection of the NetBotz device:
z zenperfsnmp run -v10 --device=Netbotz01
We can look through the output to see what zenperfsnmp does. I usually look for any lines that contain MetricWriter. These lines will show the collected data being published to the database. If data isn’t collected, these lines won’t be present. Because of this you might run the following command instead to only see lines that contain this pattern:
z zenperfsnmp run -v10 --device=Netbotz01 | grep "MetricWriter"
We should see about 18 datapoints being published. You’ll see two of eventQueueLength, sysUpTime, 14 interface datapoints and our custom snmpInTotalReqVars in there somewhere.
Export the ZenPack
Now that we’ve created a ZenPack and added some configuration to it, we need to export it. Exporting a ZenPack takes all of the object’s you’ve added to your ZenPack through the web interface and compiles them into an objects.xml file that gets saved into your ZenPack’s source directory in the file system.
Follow these steps to export a ZenPack.
Navigate to Advanced > ZenPacks > Your ZenPack in the web interface.
Scroll to the bottom of the page to see what objects the ZenPack provides.
All objects listed in the ZenPack Provides section and objects contained within them will be exported.
Choose Export ZenPack from the gear menu in the bottom-left of the screen.
Choose to only export and not download then click OK.
You could also choose to download the ZenPack through your web browser. However, the downloaded file will be the built
eggdistribution format of the ZenPack. This means that it can be installed into other Virtana systems, but is not suitable for further development.
This will export everything under ZenPack Provides to a directory within your ZenPack’s source called objects/. No other files in your ZenPack’s source directory are created or modified. You can find this file in a path such as the following.
/z/ZenPacks.acme.Widgeter/ZenPacks/acme/Widgeter
Each time you add a new object to you ZenPack within the web interface, or modify an object that’s already contained within your ZenPack, you should export the ZenPack again to update objects.xml. If you’re using version control on your ZenPack’s source directory this would be a good time to commit the resulting changes.
Exporting a ZenPack overwrites files in the objects/ directory. For this reason it is recommended that files in this directory never be modified by hand.
Device modeling
This section will cover creation of a custom Device subclass and modeling of device attributes.
For purposes of this example, we’ll add a temp_sensor_count attribute to NetBotz devices. We’ll walk through adding the attribute to the model, modeling it from the device, and displaying it in the overview screen for NetBotz devices.
Starting in this section we’ll be working with files within the NetBotz ZenPack’s directory. To keep the path names short, I’ll assume the $ZP_TOP_DIR and $ZP_DIR environment variables have been set as follows.
export ZP_TOP_DIR=/z/ZenPacks.training.NetBotz export ZP_DIR=$ZP_TOP_DIR/ZenPacks/training/NetBotz
Create the NetBotzDevice class
A Device subclass should not be confused with a device class. In the previous section we created the /NetBotz device class from the web interface. Creating a Device subclass means to extend the actual Python class of a Device object. You’d do this to add new attributes, methods or relationships to special device types.
Use the following steps to create a NetBotzDevice class with a new attribute called temp_sensor_count.
Update
$ZP_DIR/zenpack.yamlto contain following contents.zenpack.yaml
name: ZenPacks.training.NetBotz classes: NetBotzDevice: base: [zenpacklib.Device] label: NetBotz properties: temp_sensor_count: type: int device_classes: /NetBotz: zProperties: zPythonClass: ZenPacks.training.NetBotz.NetBotzDevice zSnmpMonitorIgnore: false zCollectorPlugins: - training.snmp.NetBotz - zenoss.snmp.NewDeviceMap - zenoss.snmp.DeviceMap - zenoss.snmp.InterfaceMapThe
namefield is mandatory and must match the full Python module name of your ZenPack.The classes section is where we define extensions to the standard Virtana model. In this case we’re creating a special device type called
NetBotzDevicebecause we want to add a new property calledtemp_sensor_count. For more information about defining classes, see Classes and relationships.The
device_classessection allows us to also configure the/NetBotzdevice class in YAML. Note that we’re configuring the same options that we already set through the web interface. You can set them either way, but once you add a device class tozenpack.yamlyou’ll likely find its easier to maintain all of the information in one place.The most important property we’re setting on the
/NetBotzdevice class iszPythonClass. This is required so that the newNetBotzDeviceclass we’ve defined will be used for devices in this device class.You’ll also note that we’re adding
training.snmp.NetBotzto the list of modeler plugins (zCollectorPlugins) even though it doesn’t yet exist. This is safe to do, and we’ll shortly be creating the modeler plugin.
Reinstall the ZenPack to have the device class changes made.
zenpack --link --install $ZP_TOP_DIR
Restart
Zopeprocess so the web interface can load our new module.serviced service restart zope
Reset the Python class of our existing device.
Run
zendmdand execute the following snippet.device = find("Netbotz01") print device.__class__You should see
<class 'Products.ZenModel.Device.Device'>. We see this instead of the Python class we just created because thezPythonClassproperty is only used when a new device is created in a device class, or when a device is moved into a device class with a differingzPythonClassvalue.So we have two options for getting our NetBotz device to use the new Python class we created. We can either delete the device and add it back, or move it to a different device class and back. Actually, there’s a third option that I use most frequently to solve this problem. I move it into the same device class using
zendmd. Execute the following snippet withinzendmdto reset the device’s Python class.dmd.Devices.NetBotz.moveDevices('/NetBotz', 'Netbotz01') commit() device = find("Netbotz01") print device.__class__Now you should see
<class 'ZenPacks.training.NetBotz.NetBotzDevice.NetBotzDevice'>printed. This confirms that ourDevicesubclass works, and that we’ve configurezPythonClasscorrectly for the/NetBotzdevice class.
Find temperature sensor count
Before we can write a modeler plugin to populate our new temp_sensor_count attribute, we need to figure out how to get the information. There are a few ways we could approach this. One way is to use that NETBOTZV2-MIBas a reference to see if we can find anything about temperature sensors specifically.
Find temperature information in NETBOTZV2-MIB using the following command.
smidump -f identifiers /usr/share/snmp/mibs/NETBOTZV2-MIB.mib | grep -Ei temp
You should see the following in the output:
NETBOTZV2-MIB tempSensorTable table 1.3.6.1.4.1.5528.100.4.1.1 NETBOTZV2-MIB tempSensorEntry row 1.3.6.1.4.1.5528.100.4.1.1.1 NETBOTZV2-MIB tempSensorId column 1.3.6.1.4.1.5528.100.4.1.1.1.1 NETBOTZV2-MIB tempSensorValue column 1.3.6.1.4.1.5528.100.4.1.1.1.2 NETBOTZV2-MIB tempSensorErrorStatus column 1.3.6.1.4.1.5528.100.4.1.1.1.3 NETBOTZV2-MIB tempSensorLabel column 1.3.6.1.4.1.5528.100.4.1.1.1.4 NETBOTZV2-MIB tempSensorEncId column 1.3.6.1.4.1.5528.100.4.1.1.1.5 NETBOTZV2-MIB tempSensorPortId column 1.3.6.1.4.1.5528.100.4.1.1.1.6 NETBOTZV2-MIB tempSensorValueStr column 1.3.6.1.4.1.5528.100.4.1.1.1.7 NETBOTZV2-MIB tempSensorValueInt column 1.3.6.1.4.1.5528.100.4.1.1.1.8 NETBOTZV2-MIB tempSensorValueIntF column 1.3.6.1.4.1.5528.100.4.1.1.1.9
You’ll also see another node and a bunch of notification entries. These are related to SNMP traps, and not relevant to what we’re interested in polling right now.
What we see here is that there isn’t a single OID we can request that will tell us the number of temperature sensors. We’re going to have to do an snmpwalk of the table then count how many rows are in the response. Specifically we want to remember the name and OID for the row: tempSensorEntry. Due to the hierarchical nature of a MIBs representation this is the most specific OID that will return the data we need.
snmpwalk 1172.17.0.1 1.3.6.1.4.1.5528.100.4.1.1.1
You’ll see a lot of output that starts with:
NETBOTZV2-MIB::tempSensorId.21604919 = STRING: nbHawkEnc_1_TEMP NETBOTZV2-MIB::tempSensorId.1095346743 = STRING: nbHawkEnc_0_TEMP NETBOTZV2-MIB::tempSensorId.1382714817 = STRING: nbHawkEnc_2_TEMP1 NETBOTZV2-MIB::tempSensorId.1382714818 = STRING: nbHawkEnc_2_TEMP2 NETBOTZV2-MIB::tempSensorId.1382714819 = STRING: nbHawkEnc_2_TEMP3 NETBOTZV2-MIB::tempSensorId.1382714820 = STRING: nbHawkEnc_2_TEMP4 NETBOTZV2-MIB::tempSensorId.1382714833 = STRING: nbHawkEnc_3_TEMP1 NETBOTZV2-MIB::tempSensorId.1382714834 = STRING: nbHawkEnc_3_TEMP2 NETBOTZV2-MIB::tempSensorId.1382714865 = STRING: nbHawkEnc_1_TEMP1 NETBOTZV2-MIB::tempSensorId.1382714866 = STRING: nbHawkEnc_1_TEMP2 NETBOTZV2-MIB::tempSensorId.1382714867 = STRING: nbHawkEnc_1_TEMP3 NETBOTZV2-MIB::tempSensorId.1382714868 = STRING: nbHawkEnc_1_TEMP4 NETBOTZV2-MIB::tempSensorId.2169088567 = STRING: nbHawkEnc_3_TEMP NETBOTZV2-MIB::tempSensorId.3242830391 = STRING: nbHawkEnc_2_TEMP
What you’re seeing above is the tempSensorId column for all 14 rows in the tempSensorTable. Continuing on you will see 14 rows for each of the other columns in the table.
Create a modeler plugin
The next step is to build a modeler plugin. A modeler plugin’s responsibility reach out into the world, gather data, and plug it into the attributes and relationships of our model classes. In this example, this means to make the SNMP requests necessary to determine how many temperature sensors a NetBotz device has, and populate our temp_sensor_count attribute with the result.
Use the following steps to create our modeler plugin.
Make the directory that’ll contain our modeler plugin.
mkdir -p $ZP_DIR/modeler/plugins/training/snmp
Note that we’re using our ZenPack’s
trainingnamespace, thensnmp. This is the recommended approach to make it clear what protocol the modeler plugin will use, and to avoid our modeler plugin conflicting with one from someone else’s ZenPack.Create
__init__.pyordunder-initfiles.touch $ZP_DIR/modeler/__init__.py touch $ZP_DIR/modeler/plugins/__init__.py touch $ZP_DIR/modeler/plugins/training/__init__.py touch $ZP_DIR/modeler/plugins/training/snmp/__init__.py
These empty
__init__.pyfiles are mandatory if we ever expect Python to import modules from these directories.Create
$ZP_DIR/modeler/plugins/training/snmp/NetBotz.pywith the following contents.from Products.DataCollector.plugins.CollectorPlugin import ( SnmpPlugin, GetTableMap, ) class NetBotz(SnmpPlugin): snmpGetTableMaps = ( GetTableMap( 'tempSensorTable', '1.3.6.1.4.1.5528.100.4.1.1.1', { '.1': 'tempSensorId', } ), ) def process(self, device, results, log): temp_sensors = results[1].get('tempSensorTable', {}) return self.objectMap({ 'temp_sensor_count': len(temp_sensors.keys()), })Start by importing
SnmpPluginandGetTableMapfrom Virtana.SnmpPluginwill handle all of the SNMP requests for us and present the results in a format we can easily work with.GetTableMapwill be used here because we need to request an SNMP table rather than specific OIDs.Our
NetBotzclass extendsSnmpPlugin. Note that theNetBotzclass name must match the filename (module name) of the modeler plugin.By defining
snmpGetTableMapsas a tuple or list on our class we can add aGetTableMapobject that requests that 1.3.6.1.4.1.5528.100.4.1.1.1 row OID and specify that we only want to get the first (.1) column and name ittempSensorId.The
processmethod will receive a two-element tuple containing the SNMP request results in therequestparameter. The first elememt,results\[0\], of this tuple would be any direct OID gets of which we didn’t request any in this plugin. The second element,results\[1\]will contain a dictionary of the table results. In this caseresults\[1\]would look like the following.{ 'tempSensorTable': { '21604919': 'nbHawkEnc_1_TEMP', '1095346743': 'nbHawkEnc_0_TEMP', '1382714817': 'nbHawkEnc_2_TEMP1', '1382714818': 'nbHawkEnc_2_TEMP2', '1382714819': 'nbHawkEnc_2_TEMP3', '1382714820': 'nbHawkEnc_2_TEMP4', '1382714833': 'nbHawkEnc_3_TEMP1', '1382714834': 'nbHawkEnc_3_TEMP2', '1382714865': 'nbHawkEnc_1_TEMP1', '1382714866': 'nbHawkEnc_1_TEMP2', '1382714867': 'nbHawkEnc_1_TEMP3', '1382714868': 'nbHawkEnc_1_TEMP4', '2169088567': 'nbHawkEnc_3_TEMP', '3242830391': 'nbHawkEnc_2_TEMP', }, }We then extract just the
tempSensorTableresults intotemp_sensorsto make the nextreturnline a bit easier to understand.We then return a dictionary that sets the
temp_sensor_countkey’s value to the number of keys intemp_sensors. Actually we return a dictionary that’s been wrapped in an ObjectMap by the modeler plugin’sobjectMaputility method.The
processmethod within all modeler plugins must return one of the following types of data.None (makes no changes to the model).
ObjectMap (to apply directly to the device that’s being modeled).
RelationshipMap (to apply to a relationship within the device).
A list containing zero or more ObjectMap and/or RelationShipMap objects.
An
ObjectMapis simply adictwrapped with some meta-data. ARelationshipMapis alistwrapped with some meta-data and containing zero or moreObjectMapinstances.
Restart
Zopeandzenhubto load the new module.serviced service restart zope serviced service restart zenhub
Test the modeler plugin
Now that we’ve created and enabled a basic modeler plugin, we should test it.
Remodel the NetBotz device.
You can do this from the web interface, but I usually use the command line because it can be easier to work with if further debugging is necessary.
zenmodeler run --device=Netbotz01
Execute the following snippet in
zendmd.device = find("Netbotz01") print device.temp_sensor_countYou should see
14printed as the number of temperature sensors.
Change the device overview
The next step will be to show the number of temperature sensors to users of the web interface. We’ll replace the Memory/Swap field in the top-left box of the device overview page with the count of temperature sensors.
Follow these steps to customize the device Overview page.
Create a directory to store our ZenPack’s JavaScript.
mkdir -p $ZP_DIR/resources
Create
$ZP_DIR/resources/device.jswith the following contents.Ext.onReady(function() { var DEVICE_OVERVIEW_ID = 'deviceoverviewpanel_summary'; Ext.ComponentMgr.onAvailable(DEVICE_OVERVIEW_ID, function(){ var overview = Ext.getCmp(DEVICE_OVERVIEW_ID); overview.removeField('memory'); overview.addField({ name: 'temp_sensor_count', fieldLabel: _t('# Temperature Sensors') }); }); });Wait for
Extto be ready.Find the overview summary panel (top-left on Overview page)
Remove the
memoryfield.Add our
temp_sensor_countfield.
Virtana Collection Zones and Virtana Service Dynamics use ExtJS. You can find more about manipulating objects in this way in their documentation.
Test the device overview
That’s it. We can restart Zope and navigate to our NetBotz device’s overview page in the browser interface. You should see # Temperature Sensors label with a value of 14 at the bottom of the top-left panel.
Component modeling
This section will cover creation of a custom Component subclass, creation of a relationship to our NetBotDevice class, and modeling of the components to fill the relationship.
In Device modeling, we added a temp_sensor_count attribute to our NetBotz devices. This isn’t very useful. It would be more useful to monitor the temperature being reported by each of these sensors. So that’s what we’ll do. Modeling each sensor as a component allows Virtana to automatically discover and monitor sensors regardless of how many a particular device has.
Find temperature sensor attributes
In Device modeling, we used smidump to extract temperature sensor information from NETBOTZV2-MIB. This will be even more applicable as we decide what attributes and metrics are available on each sensor. Let’s use smidump and snmpwalk for a refresher on what’s available.
Find temperature information in NETBOTZV2-MIB using the following command.
smidump -f identifiers /usr/share/snmp/mibs/NETBOTZV2-MIB.mib | grep -Ei temp
You should see the following in the output:
NETBOTZV2-MIB tempSensorTable table 1.3.6.1.4.1.5528.100.4.1.1 NETBOTZV2-MIB tempSensorEntry row 1.3.6.1.4.1.5528.100.4.1.1.1 NETBOTZV2-MIB tempSensorId column 1.3.6.1.4.1.5528.100.4.1.1.1.1 NETBOTZV2-MIB tempSensorValue column 1.3.6.1.4.1.5528.100.4.1.1.1.2 NETBOTZV2-MIB tempSensorErrorStatus column 1.3.6.1.4.1.5528.100.4.1.1.1.3 NETBOTZV2-MIB tempSensorLabel column 1.3.6.1.4.1.5528.100.4.1.1.1.4 NETBOTZV2-MIB tempSensorEncId column 1.3.6.1.4.1.5528.100.4.1.1.1.5 NETBOTZV2-MIB tempSensorPortId column 1.3.6.1.4.1.5528.100.4.1.1.1.6 NETBOTZV2-MIB tempSensorValueStr column 1.3.6.1.4.1.5528.100.4.1.1.1.7 NETBOTZV2-MIB tempSensorValueInt column 1.3.6.1.4.1.5528.100.4.1.1.1.8 NETBOTZV2-MIB tempSensorValueIntF column 1.3.6.1.4.1.5528.100.4.1.1.1.9
Let’s now use snmpwalk to see what these values look like on our NetBotz device.
snmpwalk 172.17.0.1 1.3.6.1.4.1.5528.100.4.1.1.1
You should see a lot of output that begins with the following:
NETBOTZV2-MIB::tempSensorId.21604919 = STRING: nbHawkEnc_1_TEMP NETBOTZV2-MIB::tempSensorId.1095346743 = STRING: nbHawkEnc_0_TEMP NETBOTZV2-MIB::tempSensorId.1382714817 = STRING: nbHawkEnc_2_TEMP1 NETBOTZV2-MIB::tempSensorId.1382714818 = STRING: nbHawkEnc_2_TEMP2
Note the 21604919 in the first response. This is the SNMP index of the first temperature sensor, or the first row in the table. I like to then restrict my snmpwalk results to only show this row with a command like the following.
snmpwalk 172.17.0.1 1.3.6.1.4.1.5528.100.4.1.1.1 | grep "\.21604919 ="
Which will show us the value of each column for that one temperature sensor:
NETBOTZV2-MIB::tempSensorId.21604919 = STRING: nbHawkEnc_1_TEMP NETBOTZV2-MIB::tempSensorValue.21604919 = INTEGER: 265 NETBOTZV2-MIB::tempSensorErrorStatus.21604919 = INTEGER: normal(0) NETBOTZV2-MIB::tempSensorLabel.21604919 = STRING: Temperature NETBOTZV2-MIB::tempSensorEncId.21604919 = STRING: nbHawkEnc_1 NETBOTZV2-MIB::tempSensorPortId.21604919 = STRING: NETBOTZV2-MIB::tempSensorValueStr.21604919 = STRING: 26.500000 NETBOTZV2-MIB::tempSensorValueInt.21604919 = INTEGER: 26 NETBOTZV2-MIB::tempSensorValueIntF.21604919 = INTEGER: 79
Now we have everything we should need to make decisions about what attributes we should model for our sensors and which would better be collected as datasources to have thresholds applied and plotted over time on graphs.
My initial thoughts would be to model the following as attributes.
tempSensorIdtempSensorEncId(enclosure ID)tempSensorPortId
I would then want to collect tempSensorValueStr as a datasource because it offers the best precision. Virtana is capable of handling numeric strings so we don’t have to collect tempSensorValue and divide it by 10 like other systems might.
Create a component subclass
Use the following steps to create a NetBotzTemperatureSensor class with the attributes discovered above.
Update
zenpack.yamlto include the followingNetBotzTemperatureSensorentry in theclassessection, and the newclass_relationshipssection.zenpack.yaml
classes: NetBotzDevice: base: [zenpacklib.Device] label: NetBotz properties: temp_sensor_count: type: int NetBotzTemperatureSensor: base: [zenpacklib.Component] label: Temperature Sensor properties: enclosure: label: Enclosure port: label: Port class_relationships: - NetBotzDevice 1:MC NetBotzTemperatureSensorIt’s important to pick unique class names. The best practice is to use a short prefix based on the ZenPack’s name followed by the type of thing the class represents as is being done here.
Both of the new properties should be strings. Since string is the default type, we don’t need to specify it. This just leaves the label.
Despite noting above that we always wanted to model the
tempSensorIdattribute, we aren’t adding an attribute for it here. This is becauseComponentalready has both anidandtitleattribute that wherein we can store the value oftempSensorId.The
class_relationshipssection is very important. We could never have any temperature sensors in the system if we didn’t relate them to something else. The1:MCbetween the two class names describes the type of relationship. Specifically it says that oneNetBotzDevicecan contain manyNetBotzTemperatureSensorobjects. For more information, see Relationships.
Test TemperatureSensor class
With our component class defined and relationships setup we can use zendmd to make sure we didn’t make any mistakes. Execute the following snippet in zendmd.
from ZenPacks.training.NetBotz.NetBotzTemperatureSensor import NetBotzTemperatureSensor
sensor = NetBotzTemperatureSensor('test_sensor_01')
device = find("Netbotz01")
device.netBotzTemperatureSensors._setObject(sensor.id, sensor)
sensor = device.netBotzTemperatureSensors._getOb(sensor.id)
print sensor
print sensor.device()You’ll most likely get the following error when executing the above snippet:
Traceback (most recent call last): File "<console>", line 1, in <module> AttributeError: netBotzTemperatureSensors
This error is indicating that we have no netBotzTemperatureSensors relationship on the device object. This would seemingly make no sense because we just added it. The key here is that existing objects like the Netbotz01 device don’t automatically get new relationships. We have to either delete the device and add it again, or execute the following in zendmd to create the newly-defined relationship.
device.buildRelations() commit()
Now you can go back and run the original snippet again. You should see the name of the sensor and device objects printed if everything worked as planned.
Update the modeler plugin
As with the NetBotzDevice class, the next step after creating our model class is to populate it with a modeler plugin. We could create a new modeler plugin to only capture the temperature sensor components, but we’ll update the NetBotz modeler plugin we previously created to model the sensors instead.
Edit
$ZP_DIR/modeler/plugins/training/snmp/NetBotz.pyand replace its contents with the following.from Products.DataCollector.plugins.CollectorPlugin import ( SnmpPlugin, GetTableMap, ) class NetBotz(SnmpPlugin): relname = 'netBotzTemperatureSensors' modname = 'ZenPacks.training.NetBotz.NetBotzTemperatureSensor' snmpGetTableMaps = ( GetTableMap( 'tempSensorTable', '1.3.6.1.4.1.5528.100.4.1.1.1', { '.1': 'tempSensorId', '.5': 'tempSensorEncId', '.6': 'tempSensorPortId', } ), ) def process(self, device, results, log): temp_sensors = results[1].get('tempSensorTable', {}) rm = self.relMap() for snmpindex, row in temp_sensors.items(): name = row.get('tempSensorId') if not name: log.warn('Skipping temperature sensor with no name') continue rm.append(self.objectMap({ 'id': self.prepId(name), 'title': name, 'snmpindex': snmpindex.strip('.'), 'enclosure': row.get('tempSensorEncId'), 'port': row.get('tempSensorPortId'), })) return rmLet’s take a closer look at how we changed the modeler plugin.
We added
relnameandmodnameas class attributes.These two settings control the meta-data that will automatically be set when the
self.relMapandself.objectMapmethods are called in theprocessmethod.The target
relnamewe should use depends on a couple of things. First, all leading uppercase letters of the class name will be converted to lowercase; that is,NetBotzTemperatureSensorbecomesnetBotzTemperatureSensor. Second, the lettersis added to the end if it is a to-many relationship; that is,netBotzTemperatureSensorbecomesnetBotzTemperatureSensors.Setting
relnametonetBotzTemperatureSensorswill cause theself.relMapcall to create aRelationshipMapthat will be applied to thenetBotzTemperatureSensorsrelationship defined on theNetBotzDeviceobject.Setting
modnametoZenPacks.training.NetBotz.TemperatureSensorwill cause theself.objectMapcalls in theprocessmethod to createObjectMapinstances that will be turned into instances of ourTemperatureSensorclass.We’re now requesting the
tempSensorEncIdandtempSensorPortIdcolumns be returned in the SNMP table request results. We’ll use these to populate their corresponding fields on theTemperatureSensorclass.Most of the
procsesmethod has been changed.We’re now creating a
RelationshipMapand appending anObjectMapto it for each temperature sensor in the results. We use theself.relMapandself.objectMaputility methods to make this easier.
Restart
Zopeandzenhubto load the changed module.serviced service restart zope serviced service restart zenhub
Test the modeler plugin
We already added the training.snmp.NetBotz modeler plugin the the /NetBotz device class in an earlier exercise. So we only need to run zenmodeler to test the temperature sensor modeling updates.
Run
zenmodeler run --device=Netbotz01We should see
Changes in configuration appliednear the end of zenmodeler’s output. The changes referred to should be 14 temperature sensor objects being created and added to the device’snetBotzTemperatureSensorsrelationship.Check the
Netbotz01device in the web interface. The temperature sensors should now be visible.
Component monitoring
This section covers monitoring component metrics using SNMP. I assume that you’ve completed the steps in Component modeling and now have temperature sensor components modeled for the NetBotz device. Currently there will be no graphs for these temperature sensors.
We will add collection, thresholding and graphing for the temperature monitored by each sensor.
Find the SNMP OID
In Component modeling, we used smidump and snmpwalk to find which values would be useful to model, and which would be useful to monitor. We found tempSensorValueStr to be the best OID to use for monitoring a sensor’s current temperature.
Let’s use snmpwalk again to see what tempSensorValueStr looks like for all of the sensors on our NetBotz device.
snmpwalk 172.17.0.1 NETBOTZV2-MIB::tempSensorValueStr
This gives of the current temperature (in Celsius) for each sensor:
NETBOTZV2-MIB::tempSensorValueStr.21604919 = STRING: 26.500000 NETBOTZV2-MIB::tempSensorValueStr.1095346743 = STRING: 27.000000 NETBOTZV2-MIB::tempSensorValueStr.1382714817 = STRING: 22.100000 NETBOTZV2-MIB::tempSensorValueStr.1382714818 = STRING: 21.100000 NETBOTZV2-MIB::tempSensorValueStr.1382714819 = STRING: 19.600000 NETBOTZV2-MIB::tempSensorValueStr.1382714820 = STRING: 19.900000 NETBOTZV2-MIB::tempSensorValueStr.1382714833 = STRING: 20.500000 NETBOTZV2-MIB::tempSensorValueStr.1382714834 = STRING: 20.100000 NETBOTZV2-MIB::tempSensorValueStr.1382714865 = STRING: 19.700000 NETBOTZV2-MIB::tempSensorValueStr.1382714866 = STRING: 20.500000 NETBOTZV2-MIB::tempSensorValueStr.1382714867 = STRING: 20.100000 NETBOTZV2-MIB::tempSensorValueStr.1382714868 = STRING: 20.000000 NETBOTZV2-MIB::tempSensorValueStr.2169088567 = STRING: 26.600000 NETBOTZV2-MIB::tempSensorValueStr.3242830391 = STRING: 27.400000
As we go on to add a monitoring template below, we’ll need to know what OID to poll to collect this value. The key to determining this for components with an snmpindex attribute like TemperatureSensor has is to find the OID for the values above and remove the SNMP index from the end of it. Let’s use snmptranslate to do this.
snmptranslate -On NETBOTZV2-MIB::tempSensorValueStr
This results in the following output:
.1.3.6.1.4.1.5528.100.4.1.1.1.7
This OID (minus the leading .) is what we’ll need.
Add a monitoring template
It is important to get the monitoring template’s name correct when adding a monitoring template that will be used for components. A Virtana administrator has no control over which monitoring templates will be bound to a component like they do with monitoring templates that are bound to devices.
How do we know what to name a monitoring template that should be used to monitor our NetBotzTemperatureSensor components? By default the monitoring template should be named the same as the component class’ label property with all spaces removed. In Component modeling, we set the label for the NetBotzTemperatureSensor class to be Temperature Sensor. This means out monitoring template should be named TemperatureSensor.
If you’d rather specify the monitoring template’s name, or the names of multiple monitoring templates to use for your component class, you can do so by specifying an explicit monitoring_templates value for it in zenpack.yaml.
Perform the following steps to create our component’s monitoring template.
Navigate to Advanced > Monitoring Templates.
Add a template.
Click the + in the bottom-left of the template list.
Set Name to
TemperatureSensor.Set Template Path to
/NetBotz.Click SUBMIT.
Add a data source.
Click the + at the top of the Data Sources panel.
Set Name to
tempSensorValueStr.Set Type to
SNMP.Click SUBMIT.
Double-click to edit the tempSensorValueStr data source.
Set OID to
1.3.6.1.4.1.5528.100.4.1.1.1.7Click SAVE.
Add a threshold.
Click the + at the top of the Thresholds panel.
Set Name to
high temperature.Set Type to
MinMaxThreshold.Click ADD.
Double-click to edit the high temperature threshold.
Move the datapoint to the list on the right.
Set Maximum Value to
32.Set Event Class to
/Environ.Click SAVE.
Add a graph.
Click the + at the top of the Graph Definitions panel.
Set Name to
Temperature.Click SUBMIT.
Double-click to edit the Temperature graph.
Set Units to
degrees c.Click SUBMIT.
Add a graph point.
Click to select the Temperature graph.
Choose Manage Graph Points from the gear menu.
Choose Data Point from the + menu.
Choose tempSensorValueStr then click SUBMIT.
Double-click to edit the tempSensorValueStr graph point.
Set Name to
Temperature.Set Format to
%7.2lf.Click SAVE then SAVE again.
You can also define monitoring templates in zenpack.yaml instead of creating them through the web interface. For more information, see Monitoring templates.
Test monitoring template
Use zenperfsnmp to test the data point collection aspect of your monitoring template. For more information, see Test monitoring template.
You can verify that your monitoring template is getting bound to each temperature sensor properly by navigating to one of the temperature sensors in the web interface and choosing Templates from its Display drop-down box. Furthermore, you can verify that your Temperature graph is shown when choosing Graphs from the temperature sensor’s Display drop-down.
Traps
This section covers how to handle SNMP traps.
To accept SNMP traps from your devices, configure your devices
to send them to your deployment. The zentrap daemon will listen to the standard SNMP trap port of 162/udp and create an event for every trap that it receives.
However, without you giving Virtana more information about the contents of those traps, the events will contain numeric OIDs and be nearly impossible for a human to decipher.
Importing MIBs
Let’s import the NETBOTZV2-MIB that we’ve been working with through these examples.
Copy the MIB to
/zso containers can read it.cp /usr/share/snmp/mibs/NETBOTZV2-MIB.mib /z
2. Import the MIB file.
zenmib run --keepMiddleZeros NETBOTZV2-MIB.mib
From which we should get the following output:
Found 1 MIBs to import. Unable to find a file that defines SNMPv2-SMI Unable to find a file that defines SNMPv2-TC Parsed 214 nodes and 256 notifications from NETBOTZV2-MIB Loaded MIB NETBOTZV2-MIB into the DMD Loaded 1 MIB file(s)
Add the imported MIB to the NetBotz ZenPack.
In the browser interface, navigate to Advanced > MIBs.
Select NETBOTZV2-MIB.
From the gear menu at the bottom of the list, choose Add to ZenPack.
Choose the ZenPacks.training.NetBotz then click SUBMIT.
Simulating SNMP traps
To more easily configure and test trap handling, it’s useful to know how to simulate SNMP traps. The alternative is breaking your real devices in various ways and hoping to be able to get the device to send all of the traps you need. This isn’t always possible.
Let’s start by picking an SNMP trap to simulate.
In the browser interface, navigate to Advanced > MIBs.
Select NETBOTZV2-MIB.
From the drop-down box in the middle of the right panel, choose Traps.
In the list of traps, choose netBotzTempTooHigh.
We’ll now see information about this trap in the bottom-right panel. The first thing to note is the OID. This is all we need to get started.
Send a simple trap
Use the following steps to get your feet wet sending a basic trap.
Make sure the
zentrap* service is running.If you have stopped the
zentrapservice, or if you have it configured to manual launch mode, you will need to start it.serviced service start zentrap
Identify the IP address to which traps should be sent to get to
zentrap.Control Center performs port forwarding on its host to route received SNMP traps to the
zentrapcontainer. We’re going to be sending simulated SNMP traps from a Control Center host, and will need to know what address to send traps to so they’re received byzentrap.Run the following command to find the address.
sudo iptables -L FORWARD -n | grep 162
This will output something very close to the following:
ACCEPT udp -- 0.0.0.0/0 172.17.0.29 udp dpt:162
We’ll be sending traps to that 172.17.0.29 address. It may be different on your system.
Send an SNMP trap.
Run the following
snmptrapcommand on the Control Center host.sudo snmptrap 172.17.0.29 0 NETBOTZV2-MIB::netBotzTempTooHigh
Find this netBotzTempTooHigh event in web interface’s event console.
Double-click the snmp trap netBotzTempTooHigh event in the event console to see its details. Look for the following details.
eventClassKey: This should be netBotzTempTooHigh as decoded using the MIB.oid: This is the original undecoded OID.
Send a full trap
Now that we’ve proved out a simple trap, we should add variable bindings or varbinds to the trap. If you look at the netBotzTempTooHigh trap in the web interface’s MIB explorer again, you’ll see that there’s an extensive list of Objects associated with the trap definition. These are variable bindings.
A variable binding allows the device sending the SNMP trap to attach additional information to the trap. In this example, one of the variable bindings for the netBotzTempTooHigh trap is netBotzV2TrapSensorID. This will give us a way to know which one of the sensors has exceeded it’s high temperature threshold.
Run the following
snmptrapcommand.sudo snmptrap 172.17.0.29 0 NETBOTZV2-MIB::netBotzTempTooHigh \ NETBOTZV2-MIB::netBotzV2TrapSensorID s 'nbHawkEnc_1_TEMP1'As you can see, this
zentrapcommand starts exactly the same as in the example. We then add the following three fields.NETBOTZV2-MIB::netBotzV2TrapSensorID(OID)s(type)'nbHawkEnc_1_TEMP1'(value)
We can continue to add sets of these three parameters to add as many other variable bindings to the trap as we want.
Note that the only difference between this event and the simple event is the addition of the
netBotzV2TrapSensorIDfield. So now you see how Virtana takes the name/value pairs that are the SNMP trap’s variable bindings and turns them into name/value pairs within the resulting event.
Mapping SNMP trap events
Now that we’re able to create SNMP traps anytime we want, it’s time to use the event mapping system to make them more useful. The most important field on an incoming event when it comes to mapping is the eventClassKey field. Fortunately for us, SNMP traps get that great eventClassKey set that gives us a big head start.
Map the event.
In the browser interface, navigate to Events.
Select the netBotzTempTooHigh event you just created.
Click the toolbar button that looks like a hierarchy. If you hover over it, the tooltip will say Reclassify an event.
Choose the /Environ event class then click SUBMIT.
Now the next time a netBotzTempTooHigh trap is received it will be put into the /Environ event class instead of /Unknown.
Enrich the event.
Click the Go to new mapping link to navigate to the new mapping.
In the left navigation pane, click Edit.
Set Transform* to the following:
evt.component = getattr(evt, 'netBotzV2TrapSensorID', '')
This will use the name of the sensor as described by the netBotzV2TrapSensorID variable binding as the event’s component field.
There are endless possibilities of what you could do within the transform for this event and others. This is just one practical example.
HTTP
This tutorial will describe an efficient approach to monitoring data via a HTTP API. We’ll start by using zenpack.yaml to extend the Virtana object model. Then we’ll use a Python modeler plugin to fill out the object model. Then we’ll use PythonCollector to monitor for events, datapoints and even to update the model.
For purposes of this guide we’ll be building a ZenPack that monitors the weather using the National Weather Service's weather API.
This tutorial assumes your system is already setup as described in Development environment and Getting started.
NWS API
The National Weather Service (US) provides an API that can be used to get all sorts of data related to the weather. Best of all, no account or authentication is needed.
We'll be using the following API endpoints for this exercise:
Stations (list)
Station (detailed information about a single station)
Active Alerts
Observations
Documentation for the API can be found here: https://www.weather.gov/documentation/services-web-api. You can also try out all the API endpoints there, to see what data you can supply, and what the returned data looks like.
Stations and station API
Stations (list)
The Stations endpoint allows us to retrieve a list of weather observation stations. In our case, we will be querying by state.
Here's an example query for Oklahoma and Texas:
https://api.weather.gov/stations?state=OK,TX
Here's the response to that query (note: this has been truncated):
{
"@context": [
"https://raw.githubusercontent.com/geojson/geojson-ld/master/contexts/geojson-base.jsonld",
{
"wx": "https://api.weather.gov/ontology#",
"s": "https://schema.org/",
"geo": "http://www.opengis.net/ont/geosparql#",
"unit": "http://codes.wmo.int/common/unit/",
"@vocab": "https://api.weather.gov/ontology#",
"geometry": {
"@id": "s:GeoCoordinates",
"@type": "geo:wktLiteral"
},
"city": "s:addressLocality",
"state": "s:addressRegion",
"distance": {
"@id": "s:Distance",
"@type": "s:QuantitativeValue"
},
"bearing": {
"@type": "s:QuantitativeValue"
},
"value": {
"@id": "s:value"
},
"unitCode": {
"@id": "s:unitCode",
"@type": "@id"
},
"forecastOffice": {
"@type": "@id"
},
"forecastGridData": {
"@type": "@id"
},
"publicZone": {
"@type": "@id"
},
"county": {
"@type": "@id"
},
"observationStations": {
"@container": "@list",
"@type": "@id"
}
}
],
"type": "FeatureCollection",
"features": [
{
"id": "https://api.weather.gov/stations/KLBB",
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
-101.8213899,
33.6674999
]
},
"properties": {
"@id": "https://api.weather.gov/stations/KLBB",
"@type": "wx:ObservationStation",
"elevation": {
"value": 1000.0488,
"unitCode": "unit:m"
},
"stationIdentifier": "KLBB",
"name": "Lubbock, Lubbock International Airport",
"timeZone": "America/Chicago"
}
},
...The key things to note about this response are that the information we care about is in the features object; that contains the list of stations, and each station has a set of properties.
Station (detailed information)
The Station endpoint provides detailed information about each observation station, including county and NWS forecast and fire zones.
Here's an example query for Tulsa International Airport:
https://api.weather.gov/stations/KTUL
And here's the result of that query:
{
"@context": [
"https://raw.githubusercontent.com/geojson/geojson-ld/master/contexts/geojson-base.jsonld",
{
"wx": "https://api.weather.gov/ontology#",
"s": "https://schema.org/",
"geo": "http://www.opengis.net/ont/geosparql#",
"unit": "http://codes.wmo.int/common/unit/",
"@vocab": "https://api.weather.gov/ontology#",
"geometry": {
"@id": "s:GeoCoordinates",
"@type": "geo:wktLiteral"
},
"city": "s:addressLocality",
"state": "s:addressRegion",
"distance": {
"@id": "s:Distance",
"@type": "s:QuantitativeValue"
},
"bearing": {
"@type": "s:QuantitativeValue"
},
"value": {
"@id": "s:value"
},
"unitCode": {
"@id": "s:unitCode",
"@type": "@id"
},
"forecastOffice": {
"@type": "@id"
},
"forecastGridData": {
"@type": "@id"
},
"publicZone": {
"@type": "@id"
},
"county": {
"@type": "@id"
}
}
],
"id": "https://api.weather.gov/stations/KTUL",
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
-95.88639,
36.1975
]
},
"properties": {
"@id": "https://api.weather.gov/stations/KTUL",
"@type": "wx:ObservationStation",
"elevation": {
"value": 206.0448,
"unitCode": "unit:m"
},
"stationIdentifier": "KTUL",
"name": "Tulsa, Tulsa International Airport",
"timeZone": "America/Chicago",
"forecast": "https://api.weather.gov/zones/forecast/OKZ060",
"county": "https://api.weather.gov/zones/county/OKC143",
"fireWeatherZone": "https://api.weather.gov/zones/fire/OKZ060"
}
}Note again that we aren't interested in the context object. In this case, since we're just getting one station, instead of a features object with a list, we just have a set of attributes. In general, the attributes we care about will always be under the properties object.
Active alerts API
The Active Alerts endpoint provides information about severe weather alerts such as tornado warnings, flood warnings and other special weather statements. We’ll be collecting these alerts to create corresponding Virtana events. This way operators can know when severe weather may be impacting areas of concern. We'll be using the county of the weather station to collect alerts that might impact each station, since the alerts aren't directly issued by the observation station.
Here's an example of a query for alerts affecting the station at Tulsa International Airport:
https://api.weather.gov/alerts/active?zone=OKC143
And here's the response to that query:
{
"@context": [
"https://raw.githubusercontent.com/geojson/geojson-ld/master/contexts/geojson-base.jsonld",
{
"wx": "https://api.weather.gov/ontology#",
"@vocab": "https://api.weather.gov/ontology#"
}
],
"type": "FeatureCollection",
"features": [
{
"id": "https://api.weather.gov/alerts/NWS-IDP-PROD-3574196",
"type": "Feature",
"geometry": null,
"properties": {
"@id": "https://api.weather.gov/alerts/NWS-IDP-PROD-3574196",
"@type": "wx:Alert",
"id": "NWS-IDP-PROD-3574196",
"areaDesc": "Tulsa, OK",
"geocode": {
"UGC": [
"OKC143"
],
"SAME": [
"040143"
]
},
"affectedZones": [
"https://api.weather.gov/zones/county/OKC143"
],
"references": [],
"sent": "2019-05-23T12:44:00-05:00",
"effective": "2019-05-23T12:44:00-05:00",
"onset": "2019-05-23T12:44:00-05:00",
"expires": "2019-05-23T21:45:00-05:00",
"ends": null,
"status": "Actual",
"messageType": "Alert",
"category": "Met",
"severity": "Unknown",
"certainty": "Unknown",
"urgency": "Unknown",
"event": "Civil Emergency Message",
"sender": "w-nws.webmaster@noaa.gov",
"senderName": "NWS Tulsa OK",
"headline": "Civil Emergency Message issued May 23 at 12:44PM CDT by NWS Tulsa OK",
"description": "THE FOLLOWING MESSAGE IS TRANSMITTED AT THE REQUEST OF THE CITY\nOF TULSA.\n\nTHE KEYSTONE DAM IS INCREASING THE RELEASE OF WATER TO 250,000\nCUBIC FEET PER SECOND.\n\nBEGINNING AT 3 PM, THE CITY OF TULSA WILL SOUND THE FLOOD SIRENS\nINCREMENTALLY EVERY 30 MINUTES FOR 6 HOURS.\n\nTHE FLOOD SIRENS WILL BE LOCALIZED ALONG THE ARKANSAS RIVER AND\nWILL BE A WARNING TO RESIDENTS IN AFFECTED AREAS TO PLAN TO MOVE\nTO HIGHER GROUND.\n\nTHIS IS A DANGEROUS SITUATION. PLEASE FOLLOW THE INSTRUCTIONS OF\nYOUR LOCAL FIRST RESPONDERS FOR EVACUATION ROUTES AND SHELTERS FOR\nYOUR AFFECTED AREA.",
"instruction": "",
"response": "Monitor",
"parameters": {
"EAS-ORG": [
"WXR"
],
"PIL": [
"TSACEMTSA"
],
"BLOCKCHANNEL": [
"CMAS",
"EAS",
"NWEM"
]
}
}
},This was done during a time of severe weather, so we'd have something to look at. Note that the response has been truncated. It’s easy to imagine turning this alert into a Virtana event. We’ll see how to do this a bit later.
Observations API
The Observations API endpoint provides information about current weather conditions for a given weather station. The Observations API endpoint is accepts a station ID to specify the weather station. There’s a lot of numeric data that would be useful to graph and threshold as Virtana datapoints.
Here’s an example query for the observations for the weather station at Dallas/Fort Worth International Airport:
https://api.weather.gov/stations/KDFW/observations/latest
And here’s the result of that query:
{
"@context": [
"https://raw.githubusercontent.com/geojson/geojson-ld/master/contexts/geojson-base.jsonld",
{
"wx": "https://api.weather.gov/ontology#",
"s": "https://schema.org/",
"geo": "http://www.opengis.net/ont/geosparql#",
"unit": "http://codes.wmo.int/common/unit/",
"@vocab": "https://api.weather.gov/ontology#",
"geometry": {
"@id": "s:GeoCoordinates",
"@type": "geo:wktLiteral"
},
"city": "s:addressLocality",
"state": "s:addressRegion",
"distance": {
"@id": "s:Distance",
"@type": "s:QuantitativeValue"
},
"bearing": {
"@type": "s:QuantitativeValue"
},
"value": {
"@id": "s:value"
},
"unitCode": {
"@id": "s:unitCode",
"@type": "@id"
},
"forecastOffice": {
"@type": "@id"
},
"forecastGridData": {
"@type": "@id"
},
"publicZone": {
"@type": "@id"
},
"county": {
"@type": "@id"
}
}
],
"id": "https://api.weather.gov/stations/KDFW/observations/2019-05-28T17:53:00+00:00",
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
-97.03,
32.9
]
},
"properties": {
"@id": "https://api.weather.gov/stations/KDFW/observations/2019-05-28T17:53:00+00:00",
"@type": "wx:ObservationStation",
"elevation": {
"value": 182,
"unitCode": "unit:m"
},
"station": "https://api.weather.gov/stations/KDFW",
"timestamp": "2019-05-28T17:53:00+00:00",
"rawMessage": "KDFW 281753Z 18020KT 10SM BKN034 BKN042 OVC250 28/20 A2974 RMK AO2 PK WND 19030/1737 SLP062 T02830200 10294 20228 56010",
"textDescription": "Cloudy",
"icon": "https://api.weather.gov/icons/land/day/ovc?size=medium",
"presentWeather": [],
"temperature": {
"value": 28.30000000000001,
"unitCode": "unit:degC",
"qualityControl": "qc:V"
},
"dewpoint": {
"value": 20,
"unitCode": "unit:degC",
"qualityControl": "qc:V"
},
"windDirection": {
"value": null,
"unitCode": "unit:degree_(angle)",
"qualityControl": "qc:Z"
},
"windSpeed": {
"value": null,
"unitCode": "unit:m_s-1",
"qualityControl": "qc:Z"
},
"windGust": {
"value": null,
"unitCode": "unit:m_s-1",
"qualityControl": "qc:Z"
},
"barometricPressure": {
"value": 100710,
"unitCode": "unit:Pa",
"qualityControl": "qc:V"
},
"seaLevelPressure": {
"value": 100620,
"unitCode": "unit:Pa",
"qualityControl": "qc:V"
},
"visibility": {
"value": 16090,
"unitCode": "unit:m",
"qualityControl": "qc:C"
},
"maxTemperatureLast24Hours": {
"value": null,
"unitCode": "unit:degC",
"qualityControl": null
},
"minTemperatureLast24Hours": {
"value": null,
"unitCode": "unit:degC",
"qualityControl": null
},
"precipitationLastHour": {
"value": null,
"unitCode": "unit:m",
"qualityControl": "qc:Z"
},
"precipitationLast3Hours": {
"value": null,
"unitCode": "unit:m",
"qualityControl": "qc:Z"
},
"precipitationLast6Hours": {
"value": null,
"unitCode": "unit:m",
"qualityControl": "qc:Z"
},
"relativeHumidity": {
"value": 60.766129124366735,
"unitCode": "unit:percent",
"qualityControl": "qc:C"
},
"windChill": {
"value": null,
"unitCode": "unit:degC",
"qualityControl": "qc:V"
},
"heatIndex": {
"value": 29.99744621839261,
"unitCode": "unit:degC",
"qualityControl": "qc:V"
},
"cloudLayers": [
{
"base": {
"value": 1040,
"unitCode": "unit:m"
},
"amount": "BKN"
},
{
"base": {
"value": 1280,
"unitCode": "unit:m"
},
"amount": "BKN"
},
{
"base": {
"value": 7620,
"unitCode": "unit:m"
},
"amount": "OVC"
}
]
}
}Create ZenPack
The first thing we’ll need to do is create the NWS ZenPack. We’ll use the zenpacklib script to create this ZenPack from the command line using the following steps. These commands should be run as the zenoss user.
cd /z zenpacklib --create ZenPacks.training.NWS
You should see output similar to the following. Most importantly that zenpack.yaml file is being created.
Creating source directory for ZenPacks.training.NWS: - making directory: ZenPacks.training.NWS/ZenPacks/training/NWS - creating file: ZenPacks.training.NWS/setup.py - creating file: ZenPacks.training.NWS/MANIFEST.in - creating file: ZenPacks.training.NWS/ZenPacks/__init__.py - creating file: ZenPacks.training.NWS/ZenPacks/training/__init__.py - creating file: ZenPacks.training.NWS/ZenPacks/training/NWS/datasources/__init__.py - creating file: ZenPacks.training.NWS/ZenPacks/training/NWS/thresholds/__init__.py - creating file: ZenPacks.training.NWS/ZenPacks/training/NWS/parsers/__init__.py - creating file: ZenPacks.training.NWS/ZenPacks/training/NWS/migrate/__init__.py - creating file: ZenPacks.training.NWS/ZenPacks/training/NWS/resources/__init__.py - creating file: ZenPacks.training.NWS/ZenPacks/training/NWS/modeler/__init__.py - creating file: ZenPacks.training.NWS/ZenPacks/training/NWS/tests/__init__.py - creating file: ZenPacks.training.NWS/ZenPacks/training/NWS/libexec/__init__.py - creating file: ZenPacks.training.NWS/ZenPacks/training/NWS/modeler/plugins/__init__.py - creating file: ZenPacks.training.NWS/ZenPacks/training/NWS/lib/__init__.py - creating file: ZenPacks.training.NWS/ZenPacks/training/NWS/__init__.py - creating file: ZenPacks.training.NWS/ZenPacks/training/NWS/zenpack.yaml
Define zProperties and classes
The zenpack.yaml file that’s created within the ZenPack source directory above contains only the absolute minimum to be a valid YAML file. Let’s take a look at its current contents.
First let’s set a couple of environment variables to reduce some typing.
export ZP_TOP_DIR=/z/ZenPacks.training.NWS export ZP_DIR=$ZP_TOP_DIR/ZenPacks/training/NWS
Now let’s look at the contents of zenpack.yaml.
cd $ZP_DIR cat zenpack.yaml
You should only see the following line.
zenpack.yaml
name: ZenPacks.training.NWS
Replace the contents of zenpack.yaml with the following.
zenpack.yaml
name: ZenPacks.training.NWS
zProperties:
DEFAULTS:
category: National Weather Service
zNwsStates:
type: lines
default:
- TX
- OK
classes:
NwsDevice:
base: [zenpacklib.Device]
label: National Weather Service API
NwsStation:
base: [zenpacklib.Component]
label: Station
properties:
country_code:
label: Country Code
timezone:
label: Time Zone
nws_zone:
label: Zone
county:
label: County
latitude:
label: Latitude
grid_display: False
longitude:
label: Longitude
grid_display: False
class_relationships:
- NwsDevice 1:MC NwsStationYou can see this YAML defines the following important aspects of our ZenPack.
The
namefield is mandatory. It must match the name of the ZenPack’s source directory.The
zPropertiesfield contains configuration properties we want the ZenPack to add to the Virtana system when it is installed.Note that
DEFAULTSis not added as configuration property. It is a special value that will cause its properties to be added as the default for all of the other listed zProperties. Specifically in this case it will cause thecategoryofzNwsStatesto be set toNational Weather Service. This is a convenience to avoid having to repeatedly type the category for each added property. Since we're only adding one zProperty, it doesn't really save us anything in this case, but it is still a best practice. In the future, you may need to add additional zProperties, and you'd need to then refactor to set the default.The
zNwsStatesproperty uses thelinestype which allows the user to specify multiple lines of text. Each line will be turned into an element in a list which you can see is also how the default value is specified. The idea here is that unless the user configures otherwise, we will default to monitoring weather alerts and conditions for stations in Texas and Oklahoma.The
classesfield contains each of the object classes we want the ZenPack to add.In this case we’re adding
NwsDevicewhich, becausebaseis set toDevice,will be a subclass or specialization of the standard Virtana device type. We’re also addingNwsStationwhich, becausebaseis set toComponent,will be a subclass of the standard component type.The
labelfor each is simply the human-friendly name that will be used to refer to the resulting objects when they’re seen in the web interface.The
propertiesforNwsStationare extra bits of data we want to model from the API and show to the user in the web interface. Settinggrid_displayto false forlattitudeandlongitudewill allow them to be shown in the details panel of the component, but not in the component grid.class_relationshipsuses a simple syntax to define a relationship betweenNwsDeviceandNwsStation. Specifically it is saying that each (1)NwsDeviceobject can contain many (MC)NwsStationobjects.
Install the ZenPack
Creating the ZenPack with the zenpacklib script doesn’t install the ZenPack for you. So you must now install the ZenPack in developer (--link) mode.
Run the following command to install the ZenPack in developer mode.
zenpack --link --install $ZP_TOP_DIR
Create modeler plugin
Now that we’ve created a NwsStation component type, we need to create a modeler plugin to create locations in the database. We’re dealing with a custom HTTP API, so we’ll want to base our modeler plugin on the PythonPlugin class. This gives us full control of both the collection and processing of the modeling data.
The modeler plugin will pass each state the user has specified in the zNwsStates property to the National Weather Service's Stations API endpoint to retrieve the list of weather observation stations, and some basic information about each.
Use the following steps to create our modeler plugin.
Make the directory that will contain our modeler plugin.
mkdir -p $ZP_DIR/modeler/plugins/NWS
Create
__init__.pyordunder-initfiles.touch $ZP_DIR/modeler/__init__.py touch $ZP_DIR/modeler/plugins/__init__.py touch $ZP_DIR/modeler/plugins/NWS/__init__.py
These empty
__init__.pyfiles are mandatory if we ever expect Python to import modules from these directories.Create
$ZP_DIR/modeler/plugins/NWS/Stations.pywith the following contents."""Models locations using the National Weather Service API.""" # stdlib Imports import json import urllib # Twisted Imports from twisted.internet.defer import inlineCallbacks, returnValue, DeferredList from twisted.web.client import getPage # Zenoss Imports from Products.DataCollector.plugins.CollectorPlugin import PythonPlugin class Stations(PythonPlugin): """NWS Stations modeler plugin.""" relname = 'nwsStations' modname = 'ZenPacks.training.NWS.NwsStation' requiredProperties = ( 'zNwsStates', ) deviceProperties = PythonPlugin.deviceProperties + requiredProperties @inlineCallbacks def collect(self, device, log): """Asynchronously collect data from device. Return a deferred.""" log.info("%s: collecting data", device.id) NwsStates = getattr(device, 'zNwsStates', None) if not NwsStates: log.error( "%s: %s not set.", device.id, 'zNwsStates') returnValue(None) requests = [] responses = [] for NwsState in NwsStates: if NwsState: try: response = yield getPage( 'https://api.weather.gov/stations?state={query}' .format(query=urllib.quote(NwsState))) response = json.loads(response) responses.append(response) except Exception, e: log.error( "%s: %s", device.id, e) returnValue(None) requests.extend([ getPage( 'https://api.weather.gov/stations/{query}' .format(query=urllib.quote(result['properties']['stationIdentifier'])) ) for result in response.get('features') ]) results = yield DeferredList(requests, consumeErrors=True) returnValue((responses, results)) def process(self, device, results, log): """Process results. Return iterable of datamaps or None.""" rm = self.relMap() (generalResults, detailedRawResults) = results detailedResults = {} for result in detailedRawResults: result = json.loads(result[1]) id = self.prepId(result['properties']['stationIdentifier']) detailedResults[id] = result['properties'] for result in generalResults: for stationResult in result.get('features'): id = self.prepId(stationResult['properties']['stationIdentifier']) zoneLink = detailedResults.get(id, {}).get('forecast', '') countyLink = detailedResults.get(id, {}).get('county', '') rm.append(self.objectMap({ 'id': id, 'station_id': id, 'title': stationResult['properties']['name'], 'longitude': stationResult['geometry']['coordinates'][0], 'latitude': stationResult['geometry']['coordinates'][1], 'timezone': stationResult['properties']['timeZone'], 'county': countyLink.split('/')[-1], 'nws_zone': zoneLink.split('/')[-1], })) return rmWhile it looks like there’s quite a bit of code in this modeler plugin, a lot of that is the kind of error handling you’d want to do in a real modeler plugin. Let’s walk through some of the highlights.
Imports
We import the standard
jsonmodule because the Weather Underground API returns JSON-encoded responses that we’ll want to convert to Python data structures.We import
inlineCallbacks,returnValue, andDeferredListbecause thePythonPlugin.collectmethod should return aDeferredso that it can be executed asynchronously byzenmodeler. You don’t need to useinlineCallbacks, but I find it to be a nice way to make Twisted’s asynchronous callback-based code look more procedural and be easier to understand. I recommend Dave Peticolas’ excellent Twisted Introduction for learning more about Twisted.inlineCallbacksis covered in part 17. ImportingDeferredListis necessary because we're going to return a list, rather than a single value for our deferred.We also import Twisted’s
getPagefunction. This is an extremely easy to use function for asynchronously fetching a URL.We import
PythonPluginbecause it will be the base class for our modeler plugin class. It’s the best choice for modeling data from HTTP APIs.StationsclassRemember that your modeler plugin’s class name must match the filename or Virtana won’t be able to load it. So because we named the file
Stations.pywe must name the classStations.relnameandmodnamepropertiesThese should be defined in this way for modeler plugins that fill a single relationship like we’re doing in this case. It states that this modeler plugin creates objects in the device’s
nwsStationsrelationship, and that it creates objects of theZenPacks.training.NWS.NwsStationtype within this relationship.Where does
relnamecome from? It comes from theNwsDevice 1:MC NwsStationrelationship we defined inzenpack.yaml. Because it’s a to-many relationship to theNwsStationtype,zenpacklibwill name the relationship by lowercasing the first letter and adding ansto the end to make it plural.Where does
modnamecome from? It will be <name-of-zenpack>.<name-of-class>. So because we defined theNwsStationclass inzenpack.yaml, and the ZenPack’s name isZenPacks.training.NWS, themodnamewill beZenPacks.training.NWS.NwsStation.devicePropertiespropertiesThe class’
devicePropertiesproperty provides a way to get additional device properties available to your modeler plugin’scollectandprocessmethods. The default properties that will be available for aPythonPluginare:id,manageIp,snmpLastCollection,snmpStatus, andzCollectorClientTimeout. Our modeler plugin will also need to know what values the user has set forzNwsStates. So we add those to the defaults.collectMethodThe
collectmethod is somethingPythonPluginhas, but other base modeler plugin types likeSnmpPlugindon’t. This is because you must write the code to collect the data to be processed, and that’s exactly what you should do in thecollectmethod.While the
collectmethod can return either normal results or aDeferred, it is highly recommend to return aDeferredto keepzenmodelerfrom blocking while yourcollectmethod executes. In this example we’ve decorated the method with@inlineCallbacksand have returned our data at the end withreturnValue(rm). This causes it to return aDeferred. By decorating the method with@inlineCallbackswe’re able to make an asynchronous request to the NWS API withresponse = yield getPage(...).The first thing we do in the
collectmethod is log an informational message to let the user know what we’re doing. This log will appear inzenmodeler.log, or on the console if we runzenmodelerin the foreground, or in the web interface when the user manually remodels the device.Next we make sure that the user as configured at least one state in
zNwsStates. This is mandatory because this controls what stations we will be querying for. Then we iterate through the states listed inzNwsStates, and query for the weather observation stations in each of those states. We use list comprehension across those results to create a list of queries for the detailed data for each of those stations, and then create aDeferredListwith those queries, so Twisted can perform them asynchronously. We then return both the original results, and theDeferredListas a tuple.processmethodThe
processmethod is where you take the data in theresultsargument and process it into DataMaps to return.We create
rmwhich is a common convention we use in modeler plugins and stands forRelationshipMap. Because we set therelnameandmodnameclass properties this will create aRelationshipMapwith it’srelnameandmodnameset to the same.Now we iterate through each result in the
DeferredListwe created before. We're just creating a dictionary by parsing the JSON in each result so we can use this to supplement the information from the list of weather stations.Next we will append an
ObjectMaptormwith some key properties set.idis mandatory and should be set to a value unique to all components on the device. If you look back the exampleStationsresponse you’ll see that thestationIdentifierproperty is useful for this purpose. Note thatprepIdshould always be used forid. It will make any string safe to use as a Virtana ID.titlegets set to the name of the weather station. It’s usually a good idea to explicitly set it as we’re doing here. It should be a human-friendly label for the component. The location’snameis a good candidate for this. It will look something likeDallas/Fort Worth International Airport.timezoneis another property we defined just for informational purposes.station_idis another property we defined. It’s purely informational and will simply be shown to the user when they’re viewing the location in the web interface. It stores the same value asid, but makes it more convenient to see in the grid.longitudeis another property we defined just for informational purposes.latitudeis another property we defined just for informational purposes.countyis another property we defined just for informational purposes. Note that we had to get this from the detailed results list by parsing a string to remove everything up to the last/.country_codeis another property we defined just for informational purposes. Note that we had to get this from the detailed results list by parsing a string to remove everything up to the last/.
Restart Virtana.
After adding a new modeler plugin you must restart Virtana. During development like this, it would be enough to just restart Zope and zenhub with the following commands.
serviced service restart zope serviced service restart zenhub
That’s it. The modeler plugin has been created. Now we just need to do some Virtana configuration to allow us to use it.
Add device class
To support adding our special NwsDevice devices that we defined in zenpack.yaml to Virtana we must create a new device class. This will give us control of the zPythonClass configuration property that defines what type of devices will be created. It will also allow us to control what modeler plugins and monitoring templates will be used.
Use the following steps to add the device class.
Add the following content to the end of
$ZP_DIR/zenpack.yaml.device_classes: /NWS: zProperties: zPythonClass: ZenPacks.training.NWS.NwsDevice zPingMonitorIgnore: true zSnmpMonitorIgnore: true zCollectorPlugins: - NWS.StationsLet’s take a look at what we’re doing here.
First we’re saying the device class is going to be
/NWS. We add it at the top level because it doesn’t fall into one of the existing categories like/Serveror/Network.Next we set
zPythonClasstoZenPacks.training.NWS.NwsDevice. The zPythonClass property controls what type of device will be created in this device class. Note that the value for this is the name of the ZenPack followed by the name of the class we created in the aboveclassessection.We then set both
zPingMonitorIgnoreandzSnmpMonitorIgnoreto true to prevent any ping or SNMP monitoring Virtana would perform on the device by default. Neither of these make sense since we’re dealing with an HTTP API, not a traditional device.Finally we set
zCollectorPluginsto contain the name of the modeler plugin we created in the previous section. Note thatzCollectorPluginsis alinesproperty, meaning it accepts multiple values in a list format.
Reinstall the ZenPack to create the device class.
zenpack --link --install $ZP_TOP_DIR
Add a device
Now would be a good time to add a device to the new device class. There are many ways to add a device to Virtana. Either of the following approaches can be easily done from the command line.
Using zendisc
Using zendisc is the easiest way to add device from the command line. However, it only lets you specify the device class and the device’s address.
Run the following command to add api.weather.gov.
zendisc run --deviceclass=/NWS --device=api.weather.gov
You should see output similar to the following.
INFO zen.ZenDisc: Connecting to localhost:8789 INFO zen.ZenDisc: Connected to the zenhub/0 instance INFO zen.ZenDisc: Getting configuration from ZenHub... INFO zen.ZenDisc: Looking for api.weather.gov INFO zen.ZenDisc: Found IP 184.27.220.20 for device api.weather.gov INFO zen.ZenDisc: Finished scanning device with address 184.27.220.20 INFO zen.ZenDisc: Discovered device api.weather.gov. INFO zen.ZenDisc: Result: api.weather.gov INFO zen.ZenDisc: Starting collector loop #001... INFO zen.ZenDisc: Got 1 devices to be scanned during collector loop #001 INFO zen.ZenDisc: Counter eventCount, value 2 INFO zen.ZenDisc: Filled collection slots for 1 of 1 devices during collector loop #001 INFO zen.ZenDisc: skipping WMI-based collection, PySamba zenpack not installed INFO zen.ZenDisc: Collect on device api.weather.gov for collector loop #001 INFO zen.ZenDisc: Python collection device api.weather.gov INFO zen.ZenDisc: plugins: NWS.Stations INFO zen.PythonClient: api.weather.gov: collecting data INFO zen.ZenDisc: No command plugins found for api.weather.gov INFO zen.ZenDisc: SNMP monitoring off for api.weather.gov INFO zen.ZenDisc: No portscan plugins found for api.weather.gov INFO zen.PythonClient: Python client finished collection for api.weather.gov INFO zen.ZenDisc: Counter eventCount, value 2 INFO zen.ZenDisc: Changes in configuration applied INFO zen.ZenDisc: Finished processing client within collector loop #001 INFO zen.ZenDisc: Scan time: 37.21 seconds for collector loop #001 INFO zen.ZenDisc: Scanned 1 of 1 devices during collector loop #001 INFO zen.ZenDisc: Daemon ZenDisc shutting down
Datasource (events)
Now that we have one or more locations modeled on our api.weather.gov device, we’ll want to start monitoring each location. Using PythonCollector we have the ability to create events, record datapoints and even update the model. We’ll start with an example that creates events from weather alert data.
The idea will be that we’ll create events for locations that have outstanding weather alerts such as tornado warnings. We’ll try to capture severity data so tornado warnings are higher severity events than something like a frost advisory.
Using PythonCollector
Before using a Python plugin in our ZenPack, we must make sure we install the PythonCollector ZenPack, and make it a requirement for our ZenPack.
The PythonCollector ZenPack adds the capability to write high performance datasources in Python. They will be collected by the zenpython service that comes with the PythonCollector ZenPack. I’d recommend reading the PythonCollector documentation for more information. Note that commercial versions of Zenoss include PythonCollector.
Installing PythonCollector
The first thing we’ll need to do is to make sure the PythonCollector ZenPack is installed on our system. If it isn’t, follow these instructions to install it.
Download the latest release from the PythonCollector page.
Run the following command to install the ZenPack:
zenpack --install ZenPacks.zenoss.PythonCollector-<version>.egg
Restart Virtana.
Add PythonCollector dependency
Since we’re going to be using PythonCollector capabilities in our ZenPack we must now update our ZenPack to define the dependency.
Follow these instructions to define the dependency.
Navigate to Advanced > Settings > ZenPacks.
Click into the ZenPacks.training.NWS ZenPack.
Check ZenPacks.zenoss.PythonCollector in the list of dependencies.
Click Save.
Export the ZenPack.
Create the alerts plugin
Follow these steps to create the Alerts data source plugin:
Create
$ZP_DIR/dsplugins.pywith the following contents."""Monitors current conditions using the NWS API.""" # Logging import logging LOG = logging.getLogger('zen.NWS') # stdlib Imports import json import time from datetime import datetime from dateutil import parser # Twisted Imports from twisted.internet.defer import inlineCallbacks, returnValue from twisted.web.client import getPage # PythonCollector Imports from ZenPacks.zenoss.PythonCollector.datasources.PythonDataSource import ( PythonDataSourcePlugin, ) class Alerts(PythonDataSourcePlugin): """NWS alerts data source plugin.""" @classmethod def config_key(cls, datasource, context): return ( context.device().id, datasource.getCycleTime(context), context.id, 'nws-alerts', ) @classmethod def params(cls, datasource, context): return { 'county': context.county, 'station_name': context.title, } @inlineCallbacks def collect(self, config): data = self.new_data() for datasource in config.datasources: try: response = yield getPage( 'https://api.weather.gov/alerts/active?zone={query}' .format( query=datasource.params['county'])) response = json.loads(response) except Exception: LOG.exception( "%s: failed to get alerts data for %s", config.id, datasource.params['station_name']) continue for rawAlert in response.get('features'): alert = rawAlert['properties'] severity = None expires = parser.parse(alert['expires']) if datetime.timetuple(expires) <= time.gmtime(): severity = 0 elif alert['certainty'] == 'Likely': severity = 4 else: severity = 3 data['events'].append({ 'device': config.id, 'component': datasource.component, 'severity': severity, 'eventKey': 'nws-alert-{}'.format(alert['event'].replace(' ', '')), 'eventClassKey': 'nws-alert', 'summary': alert['headline'], 'message': alert['description'], 'nws-sender': alert['senderName'], 'nws-date': alert['effective'], 'nws-expires': alert['expires'], 'nws-category': alert['category'], 'nws-instruction': alert['instruction'], 'nws-type': alert['event'], }) returnValue(data)Let’s walk through this code to explain what is being done.
Logging
The first thing we do is import
loggingand createLOGas our logger. It’s important that the name of the logger in thelogging.getLogger()begins withzen.. You will not see your logs otherwise.The stdlib and Twisted imports are almost identical to what we used in the modeler plugin, and they’re used for the same purposes.
Finally we import
PythonDataSourcePluginfrom the PythonCollector ZenPack. This is the class our data source plugin will extend, and basically allows us to write code that will be executed by thezenpythoncollector service.AlertsclassUnlike our modeler plugin, there’s no need to make the plugin class’ name the same as the filename. As we’ll see later when we’re setting up the monitoring template that will use this plugin, there’s no specific name for the file or the class required because we configure where to find the plugin in the datasource configuration within the monitoring template.
config_keyClass MethodThe
config_keymethod must have the@classmethoddecorator. It is passeddatsource, andcontext. Thedatasourceargument will be the actual datasource that the user configures in the monitoring templates section of the web interface. It has properties such aseventClass,severity, and as you can see agetCycleTime()method that returns the interval at which it should be polled. Thecontextargument will be the object to which the monitoring template and datasource is bound. In our case this will be a station object such as Dallas Fort Worth International Airport.The purpose of the
config_keymethod is to split monitoring configuration into tasks that will be executed by thezenpythonservice. Thezenpythonservice will create one task for each unique value returned fromconfig_key. It should be used to optimize the way data is collected. In some cases it is possible to make a single query to an API to get back data for many components. In these cases it would be wise to removecontext.idfrom the config_key so we get one task for all components.In our case, the NWS API must be queried once per location so it makes more sense to put
context.idinconfig_keyso we get one task per station.The value returned by
config_keywill be used whenzenpythonlogs. So adding something likenws-alertsto the end makes it easy to see logs related to collecting alerts in the log file.The
config_keymethod will only be executed byzenhub. So you must restartzenhubif you make changes to theconfig_keymethod. This also means that if there’s an exception in theconfig_keymethod it will appear in thezenhublog, notzenpython.paramsclass methodThe
paramsmethod must have the@classmethoddecorator. It is passed the samedatasourceandcontextarguments asconfig_key.The purpose of the
paramsmethod is to copy information from the Virtana database into theconfig.datasources[*]that will be passed as an argument to thecollectmethod. Since thecollectmethod is run byzenpythonit won’t have direct access to the database, so it relies on theparamsmethod to provide it with any information it will need to collect.In our case you can see that we’re copying the context’s
county, andstation_idproperties. These will be used in thecollectmethod.Just like the
config_keymethod,paramswill only be executed byzenhub. So be sure to restartzenhubif you make changes, and look in thezenhublog for errors.collectmethodThe
collectmethod does all of the real work. It will be called once per cycletime. It gets passed aconfigargument which for the most part has two useful properties:config.idandconfig.datasources.config.idwill be the device’s id, andconfig.datasourcesis a list of the datasources that need to be collected.You’ll see in the
collectmethod that each datasource inconfig.datasourceshas some useful properties.datasource.componentwill be the id of the component against which the datasource is run, or blank in the case of a device-level monitoring template.datasource.paramscontains whatever theparamsmethod returned.Within the body of the collect method we see that we create a new
datavariable usingdata = self.new_data().datais a place where we stick all of the collected events, values and maps.datalooks like the following:data = { 'events': [], 'values': defaultdict(<type 'dict'>, {}), 'maps': [], }Next we iterate over every configured datasource. For each one we make a call to the NWS’s Alerts API, then iterate over each alert in the response creating an event for each.
The following standard fields are being set for every event. You should read Virtana’ event management documentation if the purpose of any of these fields is not clear. I highly recommend setting all of these fields to an appropriate value for any event you send into Virtana to improve the ability of Virtana and Virtana’ operators to manage the events.
device: Mandatory. The device id related to the event.component: Optional. The component id related to the event.severity: Mandatory. The severity for the event.eventKey: Optional. A further uniqueness key for the event. Used for de-duplication and clearing.eventClassKey: Optional. An identifier for thetypeof event. Used during event class mapping.summary: Mandatory: A (hopefully) short summary of the event. Truncated to 128 characters.message: Optional: A longer text description of the event. Not truncated.
You will also see many
nws-*fields being added to the event. Virtana allows arbitrary fields on events so it can be a good practice to add any further information you get about the event in this way. It can make understanding and troubleshooting the resulting event easier.Finally we return data with all of events we appended to it.
zenpythonwill take care of getting the events sent from this point.
Restart Virtana.
After adding a new datasource plugin you must restart Virtana. While developing it’s enough to just restart
zenhubwith the following command.serviced service restart zenhub
That’s it. The datasource plugin has been created. Now we just need to do some Virtana configuration to allow us to use it.
Configure monitoring templates
Rather than use the web interface to manually create a monitoring template, we’ll specify it in our zenpack.yaml instead.
Edit
$ZP_DIR/zenpack.yamland add thetemplatessection below to the existing/NWSdevice class.device_classes: /NWS: templates: Station: description: Weather monitoring using the NWS API. targetPythonClass: ZenPacks.training.NWS.NwsStation datasources: alerts: type: Python plugin_classname: ZenPacks.training.NWS.dsplugins.Alerts cycletime: "600"At least some of this should be self-explanatory. The YAML vocabulary has been designed to be as intuitive and concise as possible. Let’s walk through it.
The highest-level element (based on indentation) is
/NWS/templates/Station. This means to create aStationmonitoring template in the/NWSdevice class.The monitoring template must be called
Stationbecause that is thelabelfor theNwsStationclass to which we want the template bound.The
descriptionis for documentation purposes and should describe the purpose of the monitoring template.The
targetPythonClassis a hint to what type of object the template is meant to be bound to. Currently this is only used to determine if users should be allowed to manually bind the template to device classes or devices. Providing a valid component type like we’ve done prevents users from making this mistake.Next we have
datasourceswith a singlealertsdatasource defined.The
alertsdatasource only has three properties:type: This is what makeszenpythoncollect the dataplugin_classname: This is the fully-qualified class name for thePythonDataSourceplugin we created that will be responsible for collecting the datasource.cycletime: The interval in seconds at which this datasource should be collected.
Reinstall the ZenPack to add the monitoring templates.
Some sections of
zenpack.yamlsuch as zProperties and templates only get created when the ZenPack is installed.Run the usual command to reinstall the ZenPack in development mode.
zenpack --link --install $ZP_TOP_DIR
Navigate to Advanced > Monitoring Templates in the web interface to verify that the Station monitoring template has been created as defined.
Test monitoring weather alerts
Go to the following URL for the current severe weather map of the United States: https://www.weather.gov
Click on one of the colored areas. Orange and red are more exciting. This will take you to the text of the warning. It should reference city or county names.
Update
zNwsStateson theapi.weather.govdevice to add one of the states that has an active weather alert. For example, “ND”, for North Dakota.Remodel the
api.weather.govdevice then verify that the new location is modeled.Run the following command to collect from
api.weather.gov.zenpython run -v10 --device=api.weather.gov
There will be a lot of output from this command, but we’re mainly looking for an event to be sent for the weather alert. It will look similar to the following output:
2019-05-29 16:19:04,832 DEBUG zen.zenpython: Queued event (total of 93) {'nws-type': u'Flash Flood Watch', 'nws-expires': u'2019-05-29T17:00:00-05:00', 'severity': 3, 'nws-category': u'Met', 'eventClassKey': 'nws-alert', 'component': 'KBVO', 'monitor': 'localhost', 'agent': 'zenpython', 'summary': u'Flash Flood Watch issued May 29 at 4:28AM CDT until May 30 at 7:00AM CDT by NWS Tulsa OK', 'nws-sender': u'NWS Tulsa OK', 'manager': '6328c71e5335', 'nws-date': u'2019-05-29T04:28:00-05:00', 'rcvtime': 1559146744.832561, 'device_guid': '021a3692-2a94-412d-a221-aa579ec2fecf', 'device': 'api.weather.gov', 'message': u'The Flash Flood Watch continues for\n\n* Portions of Arkansas and Oklahoma...including the following\ncounties...in Arkansas...Benton...Carroll...Crawford...\nFranklin...Madison...Sebastian and Washington AR. in\nOklahoma...Adair...Cherokee...Choctaw...Craig...Creek...\nDelaware...Haskell...Latimer...Le Flore...Mayes...McIntosh...\nMuskogee...Nowata...Okfuskee...Okmulgee...Osage...Ottawa...\nPawnee...Pittsburg...Pushmataha...Rogers...Sequoyah...Tulsa...\nWagoner and Washington OK.\n\n* Through Thursday morning\n\n* Widespread showers and thunderstorms will expand across the\nregion on today and continue into tonight. The heaviest rainfall\nis expected to be southeast of Interstate 44 with the heaviest\ntotals from southeast Oklahoma into northwest Arkansas.\nWidespread 1 to 2 inch rain amounts with local amounts over 3\ninches appear likely within the heaviest rainfall band. The\nArkansas River remaining in historic flood category will inhibit\nsmall creeks and tributaries from draining as they normally\nwould. Despite the lack of preceding rainfall, rapid onset flash\nflooding will be possible given this condition. Cities through\nwest central Arkansas near the Arkansas river may experience\nflooding in areas that typically remain dry and there is\npotential for catastrophic flooding should the heavier totals be\nrealized near the larger Arkansas river channel. Flooding should\nbe considered a high risk weather impact today through tonight.', 'nws-instruction': u'If you are in the watch area, keep informed, and be ready for\nquick action if flash flooding is observed or if a warning is\nissued.\n\nA flash flood watch means rapidly rising water or flooding is\npossible within the watch area.', 'eventKey': 'nws-alert-FlashFloodWatch'}You can use a commmand like the following to see just these log lines:
zenpython run -v10 --device=api.weather.gov | grep 'Queued' | grep 'nws'
You should now be able to confirm that this event was created in the Virtana event console.
Datasource (data points)
We’ve already created a data source plugin that creates Virtana events for weather alerts. Now we want to use the Weather Underground Conditions API to monitor current weather observations for each station. The purpose of this is to illustrate that these Python data source plugins can also be used to collect datapoints.
Create conditions datasource plugin
Follow these steps to create the Conditions data source plugin:
Add the following contents to the end of
$ZP_DIR/dsplugins.py.class Conditions(PythonDataSourcePlugin): """National Weather Service conditions data source plugin.""" @classmethod def config_key(cls, datasource, context): return ( context.device().id, datasource.getCycleTime(context), context.id, 'nws-conditions', ) @classmethod def params(cls, datasource, context): return { 'station_id': context.id, 'station_name': context.title, } @inlineCallbacks def collect(self, config): data = self.new_data() for datasource in config.datasources: try: response = yield getPage( 'https://api.weather.gov/stations/{station_id}/observations/latest' .format( station_id=datasource.params['station_id'])) response = json.loads(response) except Exception: LOG.exception( "%s: failed to get conditions data for %s", config.id, datasource.params.get('station_name')) continue current_observation = response.get('properties') for datapoint_id in (x.id for x in datasource.points): if datapoint_id not in current_observation: continue try: value = current_observation[datapoint_id]['value'] if isinstance(value, basestring): value = value.strip(' %') value = float(value) except (TypeError, ValueError): # Sometimes values are NA or not available. continue dpname = '_'.join((datasource.datasource, datapoint_id)) data['values'][datasource.component][dpname] = (value, 'N') returnValue(data)Most of the
Conditionsplugin is almost identical to theAlertsplugin so I won’t repeat what can be read back in that section. The main difference starts at the following line of thecollectmethod:current_observation = response.get('properties')It grabs the
propertiesdata from the response then iterates over every datapoint configured on the datasource. This is a nice approach because it allows for some user-flexibility in what datapoints are captured from the Observations API. If the API madetemp_candtemp_favailable, we could choose to collecttemp_cjust by adding a datapoint by that name.The following line is the most important in terms of explaining how to have your plugin return datapoint values.
data['values'][datasource.component][dpname] = (value, 'N')
We just stick
(value, 'N')into the component’s datapoint dictionary. The'N'is the timestamp at which the value occurred. If you know the time it should be specified as the integer UNIX timestamp. Use'N'if you don’t know. This will use the current time.Restart Virtana.
After adding a new datasource plugin you must restart Virtana. While developing it’s enough to just restart
zenhubwith the following command.serviced service restart zenhub
That’s it. The datasource plugin has been created. Now we just need to do some Virtana configuration to allow us to use it.
Add conditions to monitoring template
To use this new plugin we’ll add a new datasource and corresponding graphs to the existing Station monitoring template defined in zenpack.yaml.
Follow these steps to update the monitoring template:
Update
$ZP_DIR/zenpack.yamlto add theconditionsentry within the existingdatasourcessection.zenpack.yaml
device_classes: /NWS: templates: Station: description: Weather monitoring using the NWS API. targetPythonClass: ZenPacks.training.NWS.NwsStation datasources: alerts: type: Python plugin_classname: ZenPacks.training.NWS.dsplugins.Alerts cycletime: "600" conditions: type: Python plugin_classname: ZenPacks.training.NWS.dsplugins.Conditions cycletime: "600" datapoints: temperature: GAUGE dewpoint: GAUGE windSpeed: GAUGE windGust: GAUGE barometricPressure: GAUGE visibility: GAUGE relativeHumidity: GAUGE heatIndex: GAUGE windChill: GAUGE barometricPressure: GAUGE precipitationLastHour: GAUGE graphs: Temperatures: units: "degrees C." graphpoints: Temperature: dpName: conditions_temperature format: "%7.2lf" Heat Index: dpName: conditions_heatIndex format: "%7.2lf" Wind Chill: dpName: conditions_windChill format: "%7.2lf" Dewpoint: dpName: conditions_dewpoint format: "%7.2lf" Relative Humidity: units: percent miny: 0 maxy: 100 graphpoints: Relative Humidity: dpName: conditions_relativeHumidity format: "%7.2lf%%" Pressure: units: pascals miny: 0 graphpoints: Pressure: dpName: conditions_barometricPressure format: "%7.0lf" Precipitation: units: meters miny: 0 graphpoints: 1 Hour: dpName: conditions_precipitationLastHour format: "%7.2lf" Wind Speed: units: mps miny: 0 graphpoints: Sustained: dpName: conditions_windSpeed format: "%7.2lf" Gust: dpName: conditions_windGust format: "%7.2lf" Visibility: units: meters miny: 0 graphpoints: Visibility: dpName: conditions_visibility format: "%7.2lf"You can refer to Monitoring templates for more information on creating monitoring templates in YAML.
Reinstall the ZenPack to update the monitoring template.
zenpack --link --install $ZP_TOP_DIR
Navigate to Advanced > Monitoring Templates in the web interface to verify that the Station monitoring template has been updated with the conditions datasource and corresponding graphs.
Test monitoring weather conditions
Run the following command to collect from api.weather.gov and test weather condition monitoring:
zenpython run -v10 --device=api.weather.gov
There will be a lot of output from this command, but we’re mainly looking for at least one datapoint being written. If one works, it’s likely that they all work. Look for a line similar to the following:
2019-05-29 21:36:42,734 DEBUG zen.MetricWriter: publishing metric api.weather.gov/conditions_barometricPressure 100710.0 1559165802 {'device': 'api.weather.gov', 'contextUUID': 'd2fd005c-b9d7-4ab8-a02b-5e3fc4b2ecba', 'key': 'Devices/api.weather.gov/nwsStations/KY63'}You can use a commmand like the following to see just these log lines:
zenpython run -v10 --device=api.weather.gov | grep "MetricWriter" | grep "conditions"
Datasource (modeling)
The final capability of Python data source plugins is to make changes to the Virtana model. This allows a data source to make changes to the model in the same way that zenmodeler does. Having this capability in a data source allows modeling more frequently than the normal 12 hour zenmodeler interval.
To demonstrate this through an exercise, we’ll extend the existing Conditions plugin to capture the what the Observations API calls textDescription which is some text that looks like “Scattered Clouds” or “Sunny”. We’ll then show this value for each location in the web interface.
Model updates are much more expensive operations than creating events or collecting datapoints. It is better to perform as much modeling as possible using modeler plugins on their typical 12 hour interval, and perform only the absolutely necessary smaller model updates more frequently using a PythonDataSourcePlugin. Too much modeling activity can result in the degradation of a Virtana’ systems overall performance.
Add modeling to conditions datasource plugin
Edit
$ZP_DIR/zenpack.yaml.Add the following
weatherproperty to theNwsStationclass between the existingtimezoneandnws_zoneproperties.weather: label: Current Conditions
Edit
$ZP_DIR/dsplugins.py.Add the following needed import to the top of
dsplugins.py.from Products.DataCollector.plugins.DataMaps import ObjectMap
Add the following code to the
Conditionsclass’collectmethod right above thereturnValue(data)line indented one level further. ThereturnValue(data)line is included in the following update to show where the new code should be placed.data['maps'].append( ObjectMap({ 'relname': 'nwsStations', 'modname': 'ZenPacks.training.NWS.NwsStation', 'id': datasource.component, 'weather': current_observation['textDescription'], })) returnValue(data) # existing lineThe
mapsconcept here is exactly the same as it is in modeler plugins.data['maps']can contain anything that a modeler plugin’sprocessmethod can return.Don’t update the
Stationmonitoring template.We’re adding capability to a datasource that’s already configured. No updates are required to the monitoring template.
Restart Virtana.
If we had only updated the
collectmethod of theConditionsplugin we would only need to restartzenpython. However, because we added the newweatherproperty to theNwsStationclass, we must restart nearly everything, so it’s simpler to restart everything.
Test modeling current conditions
Run the following command to collect from
api.weather.gov.zenpython run -v10 --device=api.weather.gov
There will be a lot of output from this command, but we’re looking for the following line which indicates that our maps were applied:
2019-05-30 14:28:12,050 DEBUG zen.python: api.weather.gov 600 KUNU nws-conditions sending 1 datamaps
You can use a commmand like the following to see just these log lines:
zenpython run -v10 --device=api.weather.gov | grep "sending" | grep "datamaps"
Navigate to the Stations on the api.weather.gov device and verify that each location shows something in its Weather column.