doc/rrdgraph_libdbi.pod

   1 =head1 NAME
   2
   3 rrdgraph_libdbi - fetching data for graphing in rrdtool graph via libdbi
   4
   5 =head1 SYNOPSIS
   6
   7 E<lt>rrdfileE<gt> = B<sql//E<lt>libdbi driverE<gt>/E<lt>driver-option-nameE<gt>=E<lt>driver-option-valueE<gt>/...[/rrdminstepsize=E<lt>stepsizeE<gt>][/rrdfillmissing=E<lt>fill missing n samplesE<gt>]//E<lt>tableE<gt>/E<lt>unixtimestamp columnE<gt>/E<lt>data value columnE<gt>[/derive]/E<lt>where clause 1E<gt>/.../E<lt>where clause nE<gt>>
   8
   9 =head1 DESCRIPTION
  10
  11 This pseudo-rrd-filename defines a sql datasource:
  12
  13 =over 8
  14
  15 =item B<sql//>
  16
  17   magic cookie-prefix for a libdbi type datasource
  18
  19 =item B<E<lt>libdbi driverE<gt>>
  20
  21   which libdbi driver to use (e.g: mysql)
  22
  23 =item B<E<lt>driver-option-nameE<gt>>=B<E<lt>driver-option-valueE<gt>>
  24
  25   defines the parameters that are required to connect to the database with the given libdbi driver
  26   (These drivers are libdbi dependent - for details please look at the driver documentation of libdbi!)
  27
  28 =item B</rrdminstepsize>=B<E<lt>minimum step sizeE<gt>>
  29
  30   defines the minimum number of the step-length used for graphing (default: 300 seconds)
  31
  32 =item B</rrdfillmissing>=B<E<lt>fill missing stepsE<gt>>
  33
  34   defines the number of steps to fill with the last value to avoid NaN boxes due to data-insertation jitter (default: 0 steps)
  35
  36 =item B<E<lt>tableE<gt>>
  37
  38   defines the table from which to fetch the resultset.
  39
  40   If there is a need to fetch data from several tables, these tables can be defined by separating the tablenames with a "+"
  41
  42   hex-type-encoding via %xx are translated to the actual value, use %% to use %
  43
  44 =item B<E<lt>[*]unixtimestamp columnE<gt>>
  45
  46   defines the column of E<lt>tableE<gt> which contains the unix-timestamp
  47   - if this is a DATETIME field in the database, then prefix with leading '*'
  48
  49   hex-type-encoding via %xx are translated to the actual value, use %% to use %
  50
  51 =item B<E<lt>data value columnE<gt>>
  52
  53   defines the column of E<lt>tableE<gt> which contains the value column, which should be graphed
  54
  55   hex-type-encoding via %xx are translated to the actual value, use %% to use %
  56
  57 =item B</derive>
  58
  59   defines that the data value used should be the delta of the 2 consecutive values (to simulate COUNTER or DERIVE type datasources)
  60
  61 =item B</E<lt>where clause(s)E<gt>>
  62
  63   defines one (ore more) where clauses that are joined with AND to filter the entries in the <lt>table<gt>
  64
  65   hex-type-encoding via %xx are translated to the actual value, use %% to use %
  66
  67 =back
  68
  69 the returned value column-names, which can be used as ds-names, are:
  70
  71 =over 8
  72
  73 =item B<min>, B<avg>, B<max>, B<count> and B<sigma>
  74
  75   are returned to be used as ds-names in your DS definition.
  76   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.
  77   And this results in the same SQL Statements used several times
  78
  79 =back
  80
  81 =head1 EXAMPLES
  82
  83 Here an example of a table in a MySQL database:
  84
  85   DB connect information
  86     dbhost=127.0.0.1
  87     user=rrd
  88     password=secret
  89     database=rrd
  90
  91   here the table:
  92     CREATE TABLE RRDValue (
  93       RRDKeyID      bigint(20) NOT NULL,
  94       UnixTimeStamp int(11) NOT NULL,
  95       value         double default NOT NULL,
  96       PRIMARY KEY  (RRDKeyID,UnixTimeStamp)
  97     );
  98
  99 and the RRDKeyID we want to graph for is: 1141942900757789274
 100
 101 The pseudo rrd-filename to access this is:
 102 "sql//mysql/host=127.0.0.1/dbname=rrd/username=rrd/password=secret//RRDValue/UnixTimeStamp/value/RRDKeyID=1141464142203608274"
 103
 104 To illustrate this here a command to create a graph that contains the actual values.
 105
 106   DS_BASE="sql//mysql/host=127.0.0.1/dbname=rrd/username=rrd/password=passwd//RRDValue/UnixTimeStamp/value/RRDKeyID=1141942900757789274"
 107   rrdtool graph test.png --imgformat=PNG --start=-1day --end=+3hours --width=1000 --height=600 \
 108     "DEF:min=$DS_BASE:min:AVERAGE" \
 109     "LINE1:min#FF0000:value" \
 110     "DEF:avg=$DS_BASE:avg:AVERAGE" \
 111     "LINE1:avg#00FF00:average" \
 112     "DEF:max=$DS_BASE:max:AVERAGE" \
 113     "LINE1:max#FF0000:max" \
 114     "DEF:sigma=$DS_BASE:sigma:AVERAGE" \
 115     "CDEF:upper=avg,4,sigma,*,+" \
 116     "LINE1:upper#0000FF:+4 sigma" \
 117     "CDEF:lower=avg,4,sigma,*,-" \
 118     "LINE1:lower#0000FF:-4 sigma"
 119
 120 =head1 NOTES
 121
 122 * Naturally you can also use any other kind of driver that libdbi supports - e.g postgres, ...
 123
 124 * From the way the data source is joined, it should also be possible to do joins over different tables
 125   (separate tables with "," in table and add in the WHERE Clauses the table equal joins.
 126   This has not been tested!!!)
 127
 128 * It should also be relatively simple to add to the database using the same data source string.
 129   This has not been implemented...
 130
 131 * The aggregation functions are ignored and several data columns are used instead
 132   to avoid querying the same SQL several times when minimum, average and maximum are needed for graphing...
 133
 134 * for DB efficiency you should think of having 2 tables, one containing historic values and the other containing the latest data.
 135   This second table should be kept small to allow for the least ammount of blocking SQL statements.
 136   Whith mysql you can even use myisam table-type for the first and InnoDB for the second.
 137   This is especially interresting as with tables with +100M rows myisam is much smaller then InnoDB.
 138
 139 * To debug the SQL statements set the environment variable RRDDEBUGSQL and the actual SQL statements and the timing is printed to stderr.
 140
 141
 142
 143 =head1 Performance issues with MySQL backend
 144
 145 LibDBI has a big performance issue when you retrieve data from a MySQL server. Performance impact is exponentially based on the number of
 146 values you retrieve from the database.
 147 For example, it would take more than 2 seconds to graph 5DS on 150 hours of data with a precision of 5 minutes
 148 (against 100ms when data comes from a RRD file). This bug has been fixed on latest version of LibDBI (not release yet).
 149 At that time, you would need to compile libdbi and libdbi-drivers from CVS repository to fix it.
 150 You can find more informations on this libdbi-users mailing list thread : http://sourceforge.net/mailarchive/message.php?msg_id=30320894
 151
 152
 153 =head1 BUGS
 154
 155 * at least on Linux please make sure that the libdbi driver is explicitly linked against libdbi.so.0
 156   check via ldd /usr/lib/dbd/libmysql.so, that there is a line with libdbi.so.0.
 157   otherwise at least the perl module RRDs will fail because the dynamic linker can not find some symbols from libdbi.so.
 158   (this only happens when the libdbi driver is actually used the first time!)
 159   This is KNOWN to be the case with RHEL4 and FC4 and FC5! (But actually this is a bug with libdbi make files!)
 160
 161 * at least version 0.8.1 of libdbiexhibits a bug with BINARY fields
 162   (shorttext,text,mediumtext,longtext and possibly also BINARY and BLOB fields),
 163   that can result in coredumps of rrdtool.
 164   The tool will tell you on stderr if this occures, so that you know what may be the reason.
 165   If you are not experiencing these coredumps, then set the environment variable RRD_NO_LIBDBI_BUG_WARNING,
 166   and then the message will not get shown.
 167
 168 =head1 AUTHOR
 169
 170 Martin Sperl <rrdtool@martin.sperl.org>