Learn about DokuWiki
Learn about DokuWiki
This is an old revision of the document!
Important Warning: The RRDgraph plugin uses the cache to store the generated images and the recipes. Please make sure you have a maintenance task in place to avoid filling your DokuWiki cache directory with useless junk!
The RRDtool website says “RRDtool is the OpenSource industry standard, high performance data logging and graphing system for time series data.”. From temperatures to cpu untilization everything can be graphed with RRDtool. There are two ways to integrate RRDtool graphs into DokuWiki documents:
This is the classical way to embed RRD graphs into DokuWiki pages. The graphs are generated by a cron job and stored as image files. These images are embedded into wiki pages.
This method has the following advantages:
But there are also some disadvantages:
The instructions and options for generating the RRD graphs are stored withing the DokuWiki documents. The graphs are generated on the fly by a plugin.
This method has the following advantages:
This method also has some disadvantages:
The RRDgraph DokuWiki plugin supplies the necessary infrastructure to implement just in time generation of RRD graphs on DokuWiki pages.
rrdtool graph|graphv filename [option …] [data definition …] [data calculation …] [variable definition …] [graph element …] [print element …]
This leads to very long and complex command lines that are horrible to diff and manage. To make this easier, RRDgraph uses a different approach. Every command line option and instruction is specified on its own line in an unified syntax. While rendering the wiki page containing the graph, the commands are interpreted and a correct RRDtool command line is build. This command line is passed to the RRDtool API present within PHP to generate the graphs. This way not only the standard RRDtool options and instructions are available. RRDgraph is adding some additional elements to make graph generation and management easier.
The RRDgraph plugin provides the
<rrd> tag for inserting a graph into a DokuWiki page. Everything between the
<rrd> and the
</rrd> tag is called a recipe and is processed by the plugin. Recipes contain options and commands passed to the RRD library.
<rrd> RANGE:1 day:now - 1day:now OPT:w=300 OPT:h=100 LINE:1#FF0000 </ttd>
This code block shows the most simple RRD graph. It creates a red horizontal line.
A recipe line contains an optional condition, a command and the parameters for this command:
The condition is optional and is described later. Let's stick with the commands and parameters for now. The only RRDtool instruction is
LINE:1#FF0000. This instruction is described within the RRDtool manual. But the other two commands
OPT can not be found within the RRDtool manual. These commands are additions that are provided by the RRDgraph plugin.
RRDgraph extends the RRDtool command set to allow for a consistent syntax.
This command defines a command line option. There are two flavours of the
OPT command. The switch and the option flavour. If you look at the RRDtool command line description there are command line options that can be passed to RRDtool to alter its behaviour. When using the RRDgraph plugin these options can be set by using the OPT command.
If you want to pass the
-g option to disable the legend just add
OPT:g to the recipe. Even the long option name
-no-legend can be used:
OPT:no-legend. There must be no leading dashes in front of the option. RRDgraph automatically prepends one dash for single letter and two dashes for multi letter options.
Some of the command line options take additional values. These values can be appended after an equals sign. If you want to set the width of the graph to 200 pixels just add
OPT:w=200. The options are automatically converted and escaped.
There are some command line options that can not be passed to RRDtool when used within the RRDgraph plugin. They would interfere with the operation of the plugin and are automatically ignored:
Some RRDtool options can be specified multiple times. The
color command line option is one of them. Normally the last set option is used. If you specify multiple
OPT:color= lines within your recipe only the last one will be passed to RRDtool. To pass an option multiple times prefix it with a number:
<rrd> OPT:1color=SHADEA#C0C0C0 OPT:2color=SHADEB#C0C0C0 </rrd>
This way the
–color option is passed two times with different values.
RRDtool needs a time range to draw graphs for. You can define one or more time ranges via the
RANGE command. This command takes three parameters separated by colons:
RANGE:1 day:now - 1day:now
The first parameter is the name of the time range. It is shown as a description of the tab above the graph. The second parameter is the start of the time range. All options described in the section “Time ranges” on the RRDtool documentation page are supported. The third parameter is the end of the range. Mostly this will be now. But all other documented options are possible, too.
You can define multiple ranges. If a graph has more than one time range defined you can switch between them by tabs displayed above the rrd graph.
INCLUDE command allows the inclusion of templates into the graph. This can be used to share the time range definition between multiple graphs or to define some standard display for different data. The included recipe is inserted at the exact position of the
INCLUDE command. This way you can assign different data sources with the
CDEF command and later add a generic graph.
The include command takes one argument after a colon:
INCLUDE:rrdgraph:templates>defaults. Even if it looks like multiple arguments it is only one. It's the path of a DokuWiki page containing the template. See the chapter about using templates for information on how to define templates.
INCLUDE command allows the inclusion of a template into a recipe. A template is declared like any other RRDgraph graph:
<rrd template="defaults"> OPT:w=700 OPT:h=400 </rrd>
The main difference between a graph and a template is the template attribute on the
<rrd> tag. The value of the attribute is the template name. It is specified separated by a greater than character after the DokuWiki page where the template is on:
INCLUDE:rrdgraph:templates>defaults includes the template named “defaults” from the DokuWiki page “rrdgraph:templates”.
Normally the templates are shown as code sections. If you want to declare a template on the same page as the graphs this can be annoying. To hide the template add
show=“false” to the
A user can not access templates on pages he has no read access. This is the default configuration. If you want to hide the content of the template from the user you can disable the option “Check ACL for included RRD templates” within the plugins settings. This way a user can use includes on pages where the ACL is not allowing him access.
Sometimes you have to RRD graphs that show different aspects of a data set. Like CPU load and clock frequency. Wouldn't it be great to switch the time ranges on all graphs simultaneously. This can be accomplished by the ganging checkbox on the right of the tab bar. Just tick all graphs that you want to change and click one of the tabs. All graphs that have the checkbox ticked will automatically switch to that tab.
This only works if all graphs have the same time ranges. If this is not the case the graphs will just switch to the same tab. If they don't have enough tabs the last tab will be selected.
This feature is especially useful if you include the same range definition into all graphs.
If you want to enable ganging by default you can add the
ganged=“true” option to the
<rrd> tag. This way the ganged switching checkbox is initially ticked on this graph.
Sometimes you want to hide some lines in longer time ranges because they clutter up the graph. Or you want to show additional information if the graph is clicked and displayed full screen. Conditions can be used to accomplish this. You can prefix any command with a question mark and add a condition. The commands are automatically ignored if the condition is false. A simple RPN parser is available for more complex setups.
<rrd> RANGE:1 day:now - 1day:now RANGE:2 day:now - 2days:now RANGE:3 day:now - 3days:now OPT:w=300 OPT:h=100 fullscreen?OPT:w=500 LINE:1#FF0000 range,2,<?LINE:0.5#00FF00 </rrd>
This recipe is showing an additional green line for the first two time ranges. And if the graph is clicked and is shown full screen the width is changed to 500. This is done by two different conditions. The first one is simple. If the variable
fullscreen is true the width is overwritten by the value 500. The second example uses the RPN syntax. This syntax is described within the RRDtool documentation. RRDgraphs parser is much simpler than the RRDtool parser it only understands this operators:
| ||Pop two elements from the stack. Perform a logical or operation and push the result onto the stack.|
| ||Pop two elements from the stack. Perform a logical and operation and push the result onto the stack.|
| ||Pop two elements from the stack and compare them. If the second element is greater than the first push back true else push back false.|
| ||Pop two elements from the stack and compare them. If the first element is greater than the second push back true else push back false.|
| ||Pop two elements from the stack and compare them. If they are equal push back true else push back false.|
The RRDgraph RPN engine has some variables that contain the current state of the graph and can be used to enable or disable parts of the recipe:
| ||Always contains a true value.|
| ||Always contains a false value.|
| ||Contains true if the graph was clicked and is shown full screen. If the graph is shown embedded within a DokuWiki page this value contains false.|
| ||Contains the nummeric index of the tab that was clicked. Conting starts with the left tab at 0.|
| ||Contains the DokuWiki page id of the current wiki page.|
RRDgraph sets the color of the graph border to a nice shade of gray. If you want to override this you have to override the options
998color. These default to the following values:
To put a red border around a graph add the following lines to your recipe:
This plugin has two configuration options.
The timeout of the internal cache. As long as this time has not elapsed the graph is not generated again and the image from the cache is used. This value is set in seconds.
If a template is included by using the
INCLUDE command the ACL of the included DokuWiki page is checked. If the user is not allowed to access the wiki page the graph will not be rendered. If this option is unchecked there is no ACL check for includes.
If the graph is cached it will be displayed even if this option is on and the user can not access the included page. This option is meant for DokuWiki installations where users can create their own graphs. This options prevents them from using circumventing the ACL via the
INCLUDE command. It is not designed to prevent the display of a graph.
The graphs do ACL checking by themselves. If the user can not access the DokuWiki page the graph is on it will not display.
No FAQ yet.