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
plugin:rrdgraph [2015-10-18 21:04] 93.104.60.140plugin:rrdgraph [2023-04-26 20:07] (current) – screenshot Aleksandr
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 +tags       : images, graph
-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 :  
-sourcerepo http://github.com/FlashSystems/rrdgraph+sourcerepo : https://github.com/FlashSystems/rrdgraph 
 + 
 +screenshot_img https://trello.com/1/cards/64496805e09cd15dd92ec094/attachments/644968367c629bac84d5fc15/download/dokuwiki-plugin-rrdgraph.png
 ---- ----
 +
 +:!: **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! 
  
-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.+:!: **Important Warning:** The RRDgraph plugin uses the cache to store the generated images and the recipes. Please make sure you have a [[tips:maintenance|maintenance task]] in place to avoid filling your DokuWiki cache directory with useless junk! 
 + 
 +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 =====
 +
 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: 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:
  
 ==== Ahead of time generation ==== ==== Ahead of time generation ====
 +
 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 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.
  
Line 40: Line 52:
  
 ==== Just in time generation ==== ==== Just in time generation ====
 +
 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. 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.
  
Line 54: Line 67:
  
 ===== Examples/Usage ===== ===== Examples/Usage =====
 +
 The RRDgraph DokuWiki plugin supplies the necessary infrastructure to implement just in time generation of RRD graphs on DokuWiki pages. The RRDgraph DokuWiki plugin supplies the necessary infrastructure to implement just in time generation of RRD graphs on DokuWiki pages.
  
 ==== Generating graphs ==== ==== Generating graphs ====
 +
 RRDtool gets its drawing instructions via the command line. There are [[http://oss.oetiker.ch/rrdtool/doc/rrdgraph.en.html|command line options]] and [[http://oss.oetiker.ch/rrdtool/doc/rrdgraph_data.en.html|data]] and [[http://oss.oetiker.ch/rrdtool/doc/rrdgraph_graph.en.html|graph]] commands. RRDtool gets its drawing instructions via the command line. There are [[http://oss.oetiker.ch/rrdtool/doc/rrdgraph.en.html|command line options]] and [[http://oss.oetiker.ch/rrdtool/doc/rrdgraph_data.en.html|data]] and [[http://oss.oetiker.ch/rrdtool/doc/rrdgraph_graph.en.html|graph]] commands.
  
Line 64: Line 79:
  
 ==== Syntax ==== ==== Syntax ====
 +
 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. 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.
  
Line 74: Line 90:
 OPT:h=100 OPT:h=100
 LINE:1#FF0000 LINE:1#FF0000
-</ttd>+</rrd>
 </code> </code>
  
Line 86: Line 102:
  
 === RRDgraph commands === === RRDgraph commands ===
 +
 RRDgraph extends the RRDtool command set to allow for a consistent syntax. RRDgraph extends the RRDtool command set to allow for a consistent syntax.
  
 == OPT == == OPT ==
 +
 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 [[http://oss.oetiker.ch/rrdtool/doc/rrdgraph.en.html|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. 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 [[http://oss.oetiker.ch/rrdtool/doc/rrdgraph.en.html|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.
  
Line 113: Line 131:
      
 == RANGE == == RANGE ==
 +
 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: 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:
  
Line 124: Line 143:
  
 == INCLUDE == == INCLUDE ==
 +
 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 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.
  
Line 130: Line 150:
  
 === Using templates === === Using templates ===
 +
 The RRDgraph ''INCLUDE'' command allows the inclusion of a template into a recipe. A template is declared like any other RRDgraph graph: The RRDgraph ''INCLUDE'' command allows the inclusion of a template into a recipe. A template is declared like any other RRDgraph graph:
  
Line 146: Line 167:
  
 === Ganging === === Ganging ===
 +
 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. 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.
  
Line 155: Line 177:
  
 === Conditions === === Conditions ===
 +
 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. 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.
  
Line 185: Line 208:
 | ''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. |
  
 === Changing the border color === === Changing the border color ===
 +
 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: 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:
 <code> <code>
Line 200: Line 224:
 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 ====
 +
 This plugin has two configuration options. This plugin has two configuration options.
  
 === RRD image cache timeout === === RRD image cache timeout ===
 +
 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. 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.
  
 === Check ACL for included RRD templates === === Check ACL for included RRD templates ===
 +
 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 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.
  
Line 213: Line 310:
  
 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 =====
 +
   * **2014-12-10** Release 1   * **2014-12-10** Release 1
     * Initial Release     * Initial Release
Line 220: Line 326:
     * 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

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki