RRD graph generation plugin for DokuWiki.
The original documentation is/was available on DokuWiki wiki page.
To preserve it in case it gets lost a markdown conversion of the documentation can be found here:
Search and install the plugin using the Extension Manager. Refer to PHP with GD on how to install plugins manually.
To use this plugin your PHP installation must have been compiled with GD support and the rrd extension must be installed and activated. Regarding GD support also see [[tips:phpwithgd) for more information.
If one of these prerequisites is not met the RRDgraph plugin will display an error message at the top of each wiki page.
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
</rrd>
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:
aimgformatlazyz
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:
| Operator | Description |
|---|---|
| ` | ` |
& |
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:
| Variable | Content |
|---|---|
true |
Always contains a true value. |
false |
Always contains a false value. |
fullscreen |
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. |
range |
Contains the nummeric index of the tab that was clicked. Counting starts with the left tab at 0. |
page |
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 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
Sometimes you want a more prominent appearance of your RRD data than just lines on a graph. Maybe the current network utilization should be shown on a real network map or the current temperature outside the building should be displayed in big letters. This can be achieved via the SVG binding mode. It takes a SVG image from the media library and processes it to insert values from the RRD.
SVG files are XML documents. They contain XML tags specifying what the web-browser should draw on the screen. One tool to easily create SVG files is inkscape.
To allow SVG binding the XML syntax of an SVG file is extended with the non standard bind tag. This tag can be used to specify what values from the RRDgraph recipe should be inserted into the SVG file. Look at the following example:
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<svg xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:cc="http://creativecommons.org/ns#" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:svg="http://www.w3.org/2000/svg" xmlns="http://www.w3.org/2000/svg" version="1.1" id="svg2" viewBox="0 0 160 160" height="45mm" width="45mm">
<g id="layer1">
<circle r="75" cy="80" cx="80"
style="color:#000000;clip-rule:nonzero;display:inline;overflow:visible;visibility:visible;opacity:1;isolation:auto;mix-blend-mode:normal;color-interpolation:sRGB;color-interpolation-filters:linearRGB;solid-color:#000000;solid-opacity:1;fill:#4a4a4a;fill-opacity:1;fill-rule:nonzero;stroke:#646464;stroke-width:4;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;color-rendering:auto;image-rendering:auto;shape-rendering:auto;text-rendering:auto;enable-background:accumulate" />
<text y="95" x="80"
style="font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;font-size:40px;line-height:125%;font-family:Arial;-inkscape-font-specification:Arial;letter-spacing:0px;word-spacing:0px;fill:#ffffff;fill-opacity:1;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" xml:space="preserve">
<tspan style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-family:Arial;-inkscape-font-specification:'Arial Bold';text-align:center;text-anchor:middle"
y="95" x="80">Dummy</tspan></text>
</g>
</svg>
This SVG file shows the white Text Dummy within a Gray circle. Not very useful at the moment. To prepare the SVG file to do work with SVG binding we've to extend it a little. You can use a text editor to do that. Replace the Word Dummy with <bind var="value" format="%d"/>. Before the SVG file is delivered to the web-browser RRDgraph will remove the bind-tag and replace it with the value of the variable named "value".
The format attribute defines the format of the inserted data. It uses the same format specification as the php sprintf function. There is one floating point value passed to sprintf. Having more than one format specifier is not allowed.
The next section shows how these variables are defined.
Recipes for binding RRD data look almost the same as normal recipes for RRD graphs. The SVG binding mode is enabled by specifying the bind attribute on the rrd tag within the dokuwiki file. The bind attribute must be the wiki path to an SVG file stored by the media manager. The file must be accessible by the user viewing the wiki page. The recipe can use includes, specify options, DEFs and CDEFs. But there are a few major differences:
- They can only have one range. This is the default range and it is used to select the data that should be processed.
- The created command line (see chapter OPT) is not passed to RRDgraph but to RRDxport. The limitations of this command are described on the RRDtool page.
- There is the new
BDEFkeyword that is processed by RRDgraph.
:!: Important: The XPORT keyword described on the manual page of RRDtool must not be used. Use the BDEF keyword as described below. Using XPORT will generate an error message.
As the XPORT statement described on RRDtools manual page the BDEF keyword exports the data for binding with the SVG file. The syntax is BDEF:variable=source:AGGREGATE. The variable value specifies the name specified on the var attribute on the bind tag within the SVG file. The source value is the name of a DEF or CDEF. The AGGREAGGTE value is the name of an aggregate function that is used to condense the values created by the DEF or CDEF statement into a single value to insert into the SVG file. The following aggregate functions are provided by RRDgraph:
MIN: The minimum of all values returned by RRDxport is used.MAX: The maximum of all values returned by RRDxport is used.AVERAGE: The average of all values returned by RRDxport is used.SUM: The sum of all values returned by RRDxport is used. This can be very misleading because RRDtool stores most of its data as rates. This aggregate function just sums up the value ignoring the time interval. Normally theTOTALaggregate function will better suite your needs.TOTAL: This sums up the real values for the RRD data. Every value returned by RRDxport will be converted to a absolute value by multiplying them with the time that has passed since the last measurement. If the data is stored as kByte/s this function will convert the value to kBytes and then sum them up. It computestotal = total + ( delta_t * value )for the complete dataset.FIRST: Uses the first (oldest) value returned by RRDxport.LAST: Uses the last (newest) value returned by RRDxport.
<rrd bind="weather:rain.svg">
RANGE:1 Tag:now - 1day:now
DEF:Rain=/var/lib/rrd/rain.rrd:rain:AVERAGE
BDEF:rainSum=Rain:TOTAL
</rrd>
This example will read the last 24 hours of data for the RRA called rain from the RRD file /var/lib/rrd/rain.rrd and generate a total value of the amount of rain within the last 24 hours. This value will then be supplied to a binding within an SVG file that may look like this: <bind var="rainSum" format="%.2f">.
Sometimes it's necessary to not just replace the bind tag with the formatted value but to set an attribute to a specific value based on the binding value. This can be achieved by using the attr attribute of the bind tag.
<bind var="position" format="%d" attr="cx">
<circle r="75" cy="80" style="color:#000000;" />
</bind>
This example will set the cx attribute of the circle enclosed within the bind tag to the value of the binding definition named position. Via the format attribute even more complex things like rotations (translate SVG attribute) can be achieved. If there is more than one tag enclosed by the bind tag all tags get the cx attribute added. It is even possible to nest multiple bind tags to set more than one attribute on the SVG tag.
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.
This sets up the virtual namespace that is used for the generated graphs. This media namespace is not visible within the media manager.
:!: Important Warning: Please make sure this namespace does not collide with an already existing namespace within the media manager. If a collision occurs the existing namespace will be inaccessible until you change this setting.
The default setting is rrdrender. With this setting all generated graphs are put below /_media/rrdrender:....
- 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.
- 2015-10-10 Release 3
- Minor update for compatibility with DokuWiki release "Detritus".
- 2016-01-23 Release 4
- Compatibility with PHP7 (thanks to splitbrain).
- Implemented RRD binding mode to create SVG files showing values from the RRD database.
- 2016-08-28 Release 5
- Update for DokuWiki release "Elenor of Tsort"
- Using a configurable media namespace for image rendering. This solves problems with initializing DokuWiki from within graph.php on some installations.
- Show a nice error message if GD or rrdgraph are missing.
- 2017-06-21 Release 6
- Litte bug-fix to make rrdgraph compatible with PHP 7 (again).
- 2017-06-21 Release 7
- Minor bug-fix: If the drop down menu is used for range switching instead of the tabs (on small screens) this only works one time and then goes completely haywire.
- 2019-01-12 Release 8
- Minor bug-fix: Missing quotes on string constant.
- Converted all line endings to LF.
No FAQ yet.