Advanced Topics

This page contains information for the more advanced corners of Weathermap usage. I assume that you are more familiar with the basics of map design here - there is less explanation of the simple stuff.

Special String Processing Tokens

Most places where you can specify a string in Weathermap config files, you can now include data from within the Weathermap data model. Useful examples of this would be:

Finally, plugins can add internal 'notes' to objects in the map, which you can then use in the same way as the normal Weathermap data. For example, you could have a plugin that looks at the load-average on a server, categorises it as light, medium or heavy and saves that to a note, which can then be used to select an appropriate icon.

The format for the tokens is simple:

Where nodename and linkname are the names of nodes or links defined in the map. There is a special link/node name, 'this', which always signifies the node or link that the string belongs to. For example:
NODE test 
 LABEL {node:this:name} 
will set the label for the node to be 'test', since that is the node's name. Using 'this' in the DEFAULT node can save you some typing:
 LABEL {node:this:name} 
 OVERLIBCAPTION History for {node:this:name} 

NODE test1 
 POSITION 100 100 

NODE test2 
 POSITION 150 100 
Each node will take it's name as the label, and a useful caption for it's Overlib pop-up graph.

For nodes specifically, there is one other special 'nodename' - 'parent'. If a node is positioned relative to another one, then this refers to that other node. The idea is to allow a node to be used as an additional data label for another one.

Here is the list of valid variablenames and their meaning.

Variable NameMeaning
bandwidth_in The raw 'bandwidth' figure for the input side of the item. This isn't always an actual bandwidth figure, especially for NODEs. For bandwidth, you probably want to use the formatting modifiers listed below.
bandwidth_out The raw 'bandwidth' figure for the output side of the item. As above, but for output.
max_bandwidth_in The maximum input bandwidth, as defined by MAXVALUE or BANDWIDTH.
max_bandwidth_out The maximum output bandwidth, as defined by MAXVALUE or BANDWIDTH.
inpercent The percentage usage for the input side of the item, calculated using the previous two figures.
outpercent The percentage usage for the output side of the item, calculated using the previous two figures.
name The name of the NODE or LINK.

In addition to the variables defined by Weathermap itself, there are two additional sources for variables, that greatly extend the usefulness of these string tokens: You, and Data Source Plugins.

Firstly, you can define addition variables for any NODE, LINK or for the map in general, using the SET command. This serves two purposes. One is to allow you to give parameters to some datasource plugins (like a database password for some external database), but the other is just so you can use those values elsewhere in the map. Say you have a data-collection system where each router has an ID, but the URL is otherwise the same from one NODE to the next. You can define a new variable with the router ID, and then use a string token to insert that ID into the INFOURL or TARGET strings. This makes it easier to edit the configuration, and easier to make global changes if you move the server than runs the other system, for example.

NODE router_a 
 LABEL Router A 
 POSITION 100 200 
 SET router_id 33 
 INFOURL http://my.monitoring.system/view.php?id={node:this:router_id} 
 TARGET somemonitoringplugin:{node:this:router_id} 

Since information from these variables can also appear in the NOTES popup for a NODE or LINK, then you can also use this as a more structured way to have that information in your config file, and still presented in the map.

The second additional source is Data Source Plugins. Some plugins may define additional variables, above and beyond the normal 'in bandwidth' and 'out bandwidth' that they normally would. For example, the Cacti Host data source plugin returns a "bandwidth" that is actually a number representing the state of the device, according to Cacti - up, down, disabled, recovering. Since you might want to show this as text somewhere, or use it to change the icon for a device, it also defines an additional variable called 'state' that contains a string - 'up','down','recovering', or 'disabled'.

Here is one more example, showing the use of relative node positions, node targets and tokens working together:


NODE fw_a 
 POSITION 100 100 
 LABEL Firewall A 
 TARGET fw_a_cpu.rrd:cpu:- fw_a_sessions.rrd:-:sess 

NODE fw_a_sessions 
 POSITION fw_a -30 0 
 LABEL {node:fw_a:outvalue} Sessions 
The first node uses two targets to populate the 'in' and 'out' slots from different RRD files. It uses the 'in' slot to change it's own color. The second node is positioned relative to the first, and uses tokens to show the number of sessions used (the 'out' slot) on the other node as it's label. In combination with the 'notes' available to plugins, you can display nearly anything in your weathermap.

Writing Plugins

Version 0.9 of Weathermap introduces a plugin system for extending it's capabilities. This makes it possible for third parties to add new possible data sources and other functions to Weathermap without needing to alter the main code of the program.

Currently, there are two basic types of plugin - datasources and pre/post-processing. Datasource plugins allow you to add new TARGET data sources. Pre-processing plugins are called once per map, before datasources are read, but after the map configuration is loaded. Post-processing plugins are called once per map, after all the data sources have been read. The processing plugins are intended to allow you to add additional information into the Map Notes data structure so that it can be accessed by the special string tokens in NODE labels, for example.

Datasource Plugins

Datasource plugins are the main plugin type in Weathermap. They allow the user to pull in data from almost any source, and incorporate it into the final Weathermap image. The best way to get started with writing a new DS plugin is probably to take an existing one apart.

Each plugin is defined as a PHP class in the lib/datasources directory. The filename of the plugin must match the classname used inside the file. It's important to know that Weathermap doesn't instantiate the class - all the methods are just static methods in a convenient container.

Each plugin has three methods: Init, Recognise and ReadData.

At startup, Weathermap calls the Init method of each plugin to see if it can run at all. The Init method should check for the availability of appropriate config, or PHP functions or files. It should then return TRUE or FALSE, to indicate if it can run or not. For example, the SNMP DS plugin returns FALSE if it can't find the snmp_get PHP function, which is normally due to the SNMP module not being configured with PHP.

For each map, after the configuration file has been read, the ReadData function inside Weathermap process TARGET lines to get data, before starting to draw the map. To do this, it loops though all the objects in the map, taking each TARGET of each object in turn (objects can have multiple aggregated targets), and for each of the TARGETs, it calls all of the DS plugins' Recgonise method. The Recognise method should return TRUE or FALSE, depending on if it thinks that the supplied TARGET string is intended for it. This is normally decided by using preg_match to match a regular expression. It should not try and read any data source, or database, or file to validate the actual TARGET. It should only decide if the TARGET is the right 'shape' or not.

Recognise is called even for plugins that have previously returned FALSE for Init. This is so that Weathermap can tell the user that their TARGET would have worked, if only the plugin was working OK, rather than mysteriously ignoring them.

Finally, once it has established which of the plugins should deal with the TARGET string, it calls the ReadData method of that plugin, which should return a list() of three items - input value, output value and valid_time.

The valid_time is a Unix time_t (as returned by time()), to indicate when the data was measured. This is mainly intended for things like RRDs where there may be a delay between the RRD being written and us reading the value, or for cached results. The input and output values are numeric, and are used as part of the final bandwidth values for the map object. If there is no valid result (e.g. the device id passed in the TARGET string doesn't exist) then the plugin should return -1,-1 for those two values.

The ReadData function can also set addtional variables for the map object, which can then be used in strings in the map config file. It can do this by calling the $map->add_note() function.

It can also receive addtional parameters that the user has defined with SET commands in the map config file. This is mainly intended for things like hostnames for the remote system that data is being read from, so that they don't have to be hardcoded, or appear in every TARGET string.

Pre- & Post-Processing Plugins

Post-processing plugins can be used to calculate additional global statistics for a map, which can then be used in elements on the map. For example, you could calculate an average latency across all links in the network, or a total network uptime based on the uptimes of all nodes. Currently, there aren't any of these plugins, but the hooks are available.