doc/rrdgraph_libdbi.html

   1 <?xml version="1.0" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4 <head>
   5 <title>rrdgraph_libdbi</title>
   6 <meta http-equiv="content-type" content="text/html; charset=utf-8" />
   7 <link rev="made" href="mailto:root@localhost" />
   8 </head>
   9
  10 <body style="background-color: white">
  11
  12
  13 <!-- INDEX BEGIN -->
  14 <div name="index">
  15 <p><a name="__index__"></a></p>
  16 <!--
  17
  18 <ul>
  19
  20         <li><a href="#name">NAME</a></li>
  21         <li><a href="#synopsis">SYNOPSIS</a></li>
  22         <li><a href="#description">DESCRIPTION</a></li>
  23         <li><a href="#examples">EXAMPLES</a></li>
  24         <li><a href="#notes">NOTES</a></li>
  25         <li><a href="#bugs">BUGS</a></li>
  26         <li><a href="#author">AUTHOR</a></li>
  27 </ul>
  28
  29 -->
  30
  31
  32 </div>
  33 <!-- INDEX END -->
  34
  35 <p>
  36 </p>
  37 <h1><a name="name">NAME</a></h1>
  38 <p>rrdgraph_libdbi - fetching data for graphing in rrdtool graph via libdbi</p>
  39 <p>
  40 </p>
  41 <hr />
  42 <h1><a name="synopsis">SYNOPSIS</a></h1>
  43 <p>&lt;rrdfile&gt; = <strong>sql//&lt;libdbi driver&gt;/&lt;driver-option-name&gt;=&lt;driver-option-value&gt;/...[/rrdminstepsize=&lt;stepsize&gt;][/rrdfillmissing=&lt;fill missing n samples&gt;]//&lt;table&gt;/&lt;unixtimestamp column&gt;/&lt;data value column&gt;[/derive]/&lt;where clause 1&gt;/.../&lt;where clause n&gt;</strong></p>
  44 <p>
  45 </p>
  46 <hr />
  47 <h1><a name="description">DESCRIPTION</a></h1>
  48 <p>This pseudo-rrd-filename defines a sql datasource:</p>
  49 <dl>
  50 <dt><strong><a name="sql_" class="item"><strong>sql//</strong></a></strong></dt>
  51
  52 <dd>
  53 <pre>
  54   magic cookie-prefix for a libdbi type datasource</pre>
  55 </dd>
  56 <dt><strong><a name="libdbi_driver" class="item"><strong>&lt;libdbi driver&gt;</strong></a></strong></dt>
  57
  58 <dd>
  59 <pre>
  60   which libdbi driver to use (e.g: mysql)</pre>
  61 </dd>
  62 <dt><strong><a name="driver_option_name_driver_option_value" class="item"><strong>&lt;driver-option-name&gt;</strong>=<strong>&lt;driver-option-value&gt;</strong></a></strong></dt>
  63
  64 <dd>
  65 <pre>
  66   defines the parameters that are required to connect to the database with the given libdbi driver
  67   (These drivers are libdbi dependent - for details please look at the driver documentation of libdbi!)</pre>
  68 </dd>
  69 <dt><strong><a name="rrdminstepsize_minimum_step_size" class="item"><strong>/rrdminstepsize</strong>=<strong>&lt;minimum step size&gt;</strong></a></strong></dt>
  70
  71 <dd>
  72 <pre>
  73   defines the minimum number of the step-length used for graphing (default: 300 seconds)</pre>
  74 </dd>
  75 <dt><strong><a name="rrdfillmissing_fill_missing_steps" class="item"><strong>/rrdfillmissing</strong>=<strong>&lt;fill missing steps&gt;</strong></a></strong></dt>
  76
  77 <dd>
  78 <pre>
  79   defines the number of steps to fill with the last value to avoid NaN boxes due to data-insertation jitter (default: 0 steps)</pre>
  80 </dd>
  81 <dt><strong><a name="table" class="item"><strong>&lt;table&gt;</strong></a></strong></dt>
  82
  83 <dd>
  84 <pre>
  85   defines the table from which to fetch the resultset.</pre>
  86 <pre>
  87   If there is a need to fetch data from several tables, these tables can be defined by separating the tablenames with a &quot;+&quot;</pre>
  88 <pre>
  89   hex-type-encoding via %xx are translated to the actual value, use %% to use %</pre>
  90 </dd>
  91 <dt><strong><a name="unixtimestamp_column" class="item"><strong>&lt;[*]unixtimestamp column&gt;</strong></a></strong></dt>
  92
  93 <dd>
  94 <pre>
  95   defines the column of E&lt;lt&gt;tableE&lt;gt&gt; which contains the unix-timestamp
  96   - if this is a DATETIME field in the database, then prefix with leading '*'</pre>
  97 <pre>
  98   hex-type-encoding via %xx are translated to the actual value, use %% to use %</pre>
  99 </dd>
 100 <dt><strong><a name="data_value_column" class="item"><strong>&lt;data value column&gt;</strong></a></strong></dt>
 101
 102 <dd>
 103 <pre>
 104   defines the column of E&lt;lt&gt;tableE&lt;gt&gt; which contains the value column, which should be graphed</pre>
 105 <pre>
 106   hex-type-encoding via %xx are translated to the actual value, use %% to use %</pre>
 107 </dd>
 108 <dt><strong><a name="derive" class="item"><strong>/derive</strong></a></strong></dt>
 109
 110 <dd>
 111 <pre>
 112   defines that the data value used should be the delta of the 2 consecutive values (to simulate COUNTER or DERIVE type datasources)</pre>
 113 </dd>
 114 <dt><strong><a name="clause" class="item"><strong>/&lt;where clause(s)&gt;</strong></a></strong></dt>
 115
 116 <dd>
 117 <pre>
 118   defines one (ore more) where clauses that are joined with AND to filter the entries in the &lt;lt&gt;table&lt;gt&gt;</pre>
 119 <pre>
 120   hex-type-encoding via %xx are translated to the actual value, use %% to use %</pre>
 121 </dd>
 122 </dl>
 123 <p>the returned value column-names, which can be used as ds-names, are:</p>
 124 <dl>
 125 <dt><strong><a name="min_avg_max_count_and_sigma" class="item"><strong>min</strong>, <strong>avg</strong>, <strong>max</strong>, <strong>count</strong> and <strong>sigma</strong></a></strong></dt>
 126
 127 <dd>
 128 <pre>
 129   are returned to be used as ds-names in your DS definition.
 130   The reason for using this is that if the consolidation function is used for min/avg and max, then the engine is used several times.
 131   And this results in the same SQL Statements used several times</pre>
 132 </dd>
 133 </dl>
 134 <p>
 135 </p>
 136 <hr />
 137 <h1><a name="examples">EXAMPLES</a></h1>
 138 <p>Here an example of a table in a MySQL database:</p>
 139 <pre>
 140   DB connect information
 141     dbhost=127.0.0.1
 142     user=rrd
 143     password=secret
 144     database=rrd</pre>
 145 <pre>
 146   here the table:
 147     CREATE TABLE RRDValue (
 148       RRDKeyID      bigint(20) NOT NULL,
 149       UnixTimeStamp int(11) NOT NULL,
 150       value         double default NOT NULL,
 151       PRIMARY KEY  (RRDKeyID,UnixTimeStamp)
 152     );</pre>
 153 <p>and the RRDKeyID we want to graph for is: 1141942900757789274</p>
 154 <p>The pseudo rrd-filename to access this is:
 155 &quot;sql//mysql/host=127.0.0.1/dbname=rrd/username=rrd/password=secret//RRDValue/UnixTimeStamp/value/RRDKeyID=1141464142203608274&quot;</p>
 156 <p>To illustrate this here a command to create a graph that contains the actual values.</p>
 157 <pre>
 158   DS_BASE=&quot;sql//mysql/host=127.0.0.1/dbname=rrd/username=rrd/password=passwd//RRDValue/UnixTimeStamp/value/RRDKeyID=1141942900757789274&quot;
 159   rrdtool graph test.png --imgformat=PNG --start=-1day --end=+3hours --width=1000 --height=600 \
 160     &quot;DEF:min=$DS_BASE:min:AVERAGE&quot; \
 161     &quot;LINE1:min#FF0000:value&quot; \
 162     &quot;DEF:avg=$DS_BASE:avg:AVERAGE&quot; \
 163     &quot;LINE1:avg#00FF00:average&quot; \
 164     &quot;DEF:max=$DS_BASE:max:AVERAGE&quot; \
 165     &quot;LINE1:max#FF0000:max&quot; \
 166     &quot;DEF:sigma=$DS_BASE:sigma:AVERAGE&quot; \
 167     &quot;CDEF:upper=avg,4,sigma,*,+&quot; \
 168     &quot;LINE1:upper#0000FF:+4 sigma&quot; \
 169     &quot;CDEF:lower=avg,4,sigma,*,-&quot; \
 170     &quot;LINE1:lower#0000FF:-4 sigma&quot;</pre>
 171 <p>
 172 </p>
 173 <hr />
 174 <h1><a name="notes">NOTES</a></h1>
 175 <p>* Naturally you can also use any other kind of driver that libdbi supports - e.g postgres, ...</p>
 176 <p>* From the way the datasource is joined, it should also be possible to do joins over different tables
 177   (separate tables with &quot;,&quot; in table and add in the WHERE Clauses the table equal joins.
 178   This has not been tested!!!)</p>
 179 <p>* It should also be relatively simple to add to the database using the same datasource string.
 180   This has not been implemented...</p>
 181 <p>* The aggregation functions are ignored and several data columns are used instead
 182   to avoid querying the same SQL several times when minimum, average and maximum are needed for graphing...</p>
 183 <p>* for DB efficiency you should think of having 2 tables, one containing historic values and the other containing the latest data.
 184   This second table should be kept small to allow for the least ammount of blocking SQL statements.
 185   Whith mysql you can even use myisam table-type for the first and InnoDB for the second.
 186   This is especially interresting as with tables with +100M rows myisam is much smaller then InnoDB.</p>
 187 <p>* To debug the SQL statements set the environment variable RRDDEBUGSQL and the actual SQL statements and the timing is printed to stderr.</p>
 188 <p>
 189 </p>
 190 <hr />
 191 <h1><a name="bugs">BUGS</a></h1>
 192 <p>* at least on Linux please make sure that the libdbi driver is explicitly linked against libdbi.so.0
 193   check via ldd /usr/lib/dbd/libmysql.so, that there is a line with libdbi.so.0.
 194   otherwise at least the perl module RRDs will fail because the dynamic linker can not find some symbols from libdbi.so.
 195   (this only happens when the libdbi driver is actually used the first time!)
 196   This is KNOWN to be the case with RHEL4 and FC4 and FC5! (But actually this is a bug with libdbi make files!)</p>
 197 <p>* at least version 0.8.1 of libdbiexhibits a bug with BINARY fields
 198   (shorttext,text,mediumtext,longtext and possibly also BINARY and BLOB fields),
 199   that can result in coredumps of rrdtool.
 200   The tool will tell you on stderr if this occures, so that you know what may be the reason.
 201   If you are not experiencing these coredumps, then set the environment variable RRD_NO_LIBDBI_BUG_WARNING,
 202   and then the message will not get shown.</p>
 203 <p>
 204 </p>
 205 <hr />
 206 <h1><a name="author">AUTHOR</a></h1>
 207 <p>Martin Sperl &lt;<a href="mailto:rrdtool@martin.sperl.org">rrdtool@martin.sperl.org</a>&gt;</p>
 208
 209 </body>
 210
 211 </html>