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!

Install the plugin using the Plugin Manager and the download URL above, which points to latest release version of the plugin. Refer to Plugins on how to install plugins manually.

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:

• Easy to implement if you only have a few graphs.
• The web-server does not have to access the RRD database files. This way sensitive data within the RRD database can be better protected.
• No DokuWiki plugins or extensions needed.

But there are also some disadvantages:

• The graphs are regularly generated even if nobody is looking at them.
• If multiple time ranges per graph should be generated the number of image files rapidly increases.
• The instructions and options for generating the graph are stored outside DokukWiki and have to be migrated and backuped separately.
• Reuse of parts of the drawing instructions is complicated and has to be implemented separately.
• For nice navigation between different graphs and time ranges many wiki pages have to be created.

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:

• All information for graph generation is included within DokuWiki.
• The information for creating the graph can be versioned and compared like any other wiki text.
• Multiple graphs and time ranges can be automatically generated and embedded on the same wiki page.
• Only the requested graphs are generated.

This method also has some disadvantages:

• The web-server needs read access to the RRD database files. Sensitive data has to be put in separate RRD files to prevent the web-server from reading it.
• For very complex graphs there may be a delay until until the graph is generated. This can be mitigated by caching the graphs.
• A DokuWiki plugin is needed.

The RRDgraph DokuWiki plugin supplies the necessary infrastructure to implement just in time generation of RRD graphs on DokuWiki pages.

RRDtool gets its drawing instructions via the command line. There are command line options and data and graph commands.

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:

[condition?]command:parameters

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 RANGE and 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:

• a
• imgformat
• lazy
• z

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.

The 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 DEF and 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.

The RRDgraph 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 <rrd> tag.

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:

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:

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 999color and 998color. These default to the following values:

OPT:999color=SHADEA#C0C0C0
OPT:998color=SHADEB#C0C0C0

To put a red border around a graph add the following lines to your recipe:

OPT:999color=SHADEA#FF0000
OPT:998color=SHADEB#FF0000

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.

• 2014-12-10 Release 1
  • Initial Release
• 2015-04-04 Release 2
  • Better locking (readers-writer-lock) while updating the rrd images within the cache. This should prevent incomplete images on well frequented graphs.

No FAQ yet.