DokuWiki

It's better when it's simple

User Tools

Site Tools


plugin:rrdgraph

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
Both sides next revision
plugin:rrdgraph [2015-10-18 21:04]
93.104.60.140
plugin:rrdgraph [2021-01-23 14:24] (current)
Flash-Systems
Line 5: Line 5:
 author     : Daniel Goß author     : Daniel Goß
 email      : developer@flashsystems.de email      : developer@flashsystems.de
-type       : syntax, action, admin, helper, render +type       : syntax, action, helper, render 
-lastupdate : 2015-10-10 +lastupdate : 2019-01-12 
-compatible : Ponder StibbonsHrunDetritus++compatible : DetritusElenor Of TsortFrusterick Manners, Greebo+
 screenshot_img : http://www.flashsystems.de/wp-content/uploads/rrdgraph.png screenshot_img : http://www.flashsystems.de/wp-content/uploads/rrdgraph.png
 tags       : rrd, rrdtool, images, graphs tags       : rrd, rrdtool, images, graphs
  
-downloadurl: https://github.com/FlashSystems/rrdgraph/archive/r3.zip +downloadurl: https://github.com/FlashSystems/rrdgraph/archive/r7.zip 
-bugtracker : http://github.com/FlashSystems/rrdgraph/issues +bugtracker : https://github.com/FlashSystems/rrdgraph/issues 
-sourcerepo : http://github.com/FlashSystems/rrdgraph+sourcerepo : https://github.com/FlashSystems/rrdgraph
 ---- ----
 +
 +
 +:!: **This Plugin is no longer maintained. If you want to take over maintaining it go ahead and contact me. ** :!:
  
 ===== Installation ===== ===== Installation =====
 :!: **Important Warning:** The RRDgraph plugin uses the cache to store the generated images and the recipes. Please make sure you have a [[https://www.dokuwiki.org/tips:maintenance|maintenance task]] in place to avoid filling your DokuWiki cache directory with useless junk! :!: **Important Warning:** The RRDgraph plugin uses the cache to store the generated images and the recipes. Please make sure you have a [[https://www.dokuwiki.org/tips:maintenance|maintenance task]] in place to avoid filling your DokuWiki cache directory with useless junk!
  
-Install the plugin using the [[plugin:plugin|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.+Search and install the plugin using the [[plugin:extension|Extension Manager]]. Refer to [[:Plugins]] on how to install plugins manually
 + 
 +==== Prerequisites ==== 
 +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|PHP with GD]] 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.
  
 ===== Introduction ===== ===== Introduction =====
Line 74: Line 82:
 OPT:h=100 OPT:h=100
 LINE:1#FF0000 LINE:1#FF0000
-</ttd>+</rrd>
 </code> </code>
  
Line 185: Line 193:
 | ''false'' | Always contains a false 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. | | ''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. Conting starts with the left tab at 0. |+| ''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. | | ''page'' | Contains the DokuWiki page id of the current wiki page. |
  
Line 200: Line 208:
 OPT:998color=SHADEB#FF0000 OPT:998color=SHADEB#FF0000
 </code> </code>
 +
 +==== SVG binding mode ====
 +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.
 +
 +=== Preparing the SVG file ===
 +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 [[https://inkscape.org/de/|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:
 +
 +<code>
 +<?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>
 +</code>
 +
 +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 [[http://php.net/manual/en/function.sprintf.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.
 +
 +=== Binding the data ===
 +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 [[http://oss.oetiker.ch/rrdtool/doc/rrdxport.en.html|RRDxport]]. The limitations of this command are described on the RRDtool page.
 +  * There is the new ''BDEF'' keyword 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 the ''TOTAL'' aggregate 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 computes ''total = 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.
 +
 +<code>
 +<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>
 +</code>
 +
 +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">''.
 +
 +=== Binding attributes ===
 +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.
 +
 +<code>
 +<bind var="position" format="%d" attr="cx">
 +  <circle r="75" cy="80" style="color:#000000;" />
 +</bind>
 +</code>
 +
 +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.
  
 ==== Configuration options ==== ==== Configuration options ====
Line 213: Line 288:
  
 The graphs do ACL checking by themselves. If the user can not access the DokuWiki page the graph is on it will not display. The graphs do ACL checking by themselves. If the user can not access the DokuWiki page the graph is on it will not display.
 +
 +=== Virtual namespace for RRD graphs ===
 +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:...''.
  
 ===== Change Log ===== ===== Change Log =====
Line 220: Line 302:
     * Better locking (readers-writer-lock) while updating the rrd images within the cache. This should prevent incomplete images on well frequented graphs.     * 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   * **2015-10-10** Release 3
-    * Minor update for compatibility DokuWiki release "Detritus".+    * 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. 
        
 ===== FAQ ===== ===== FAQ =====
 No FAQ yet. No FAQ yet.
plugin/rrdgraph.1445195077.txt.gz · Last modified: 2015-10-18 21:04 by 93.104.60.140