doc/rrdgraph_libdbi.txt

   1 RRDGRAPH_LIBDBI(1)                  rrdtool                 RRDGRAPH_LIBDBI(1)
   2
   3
   4
   5 N\bNA\bAM\bME\bE
   6        rrdgraph_libdbi - fetching data for graphing in rrdtool graph via
   7        libdbi
   8
   9 S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS
  10        <rrdfile> = s\bsq\bql\bl/\b//\b/<\b<l\bli\bib\bbd\bdb\bbi\bi
  11        d\bdr\bri\biv\bve\ber\br>\b>/\b/<\b<d\bdr\bri\biv\bve\ber\br-\b-o\bop\bpt\bti\bio\bon\bn-\b-n\bna\bam\bme\be>\b>=\b=<\b<d\bdr\bri\biv\bve\ber\br-\b-o\bop\bpt\bti\bio\bon\bn-\b-v\bva\bal\blu\bue\be>\b>/\b/.\b..\b..\b.[\b[/\b/r\brr\brd\bdm\bmi\bin\bns\bst\bte\bep\bps\bsi\biz\bze\be=\b=<\b<s\bst\bte\bep\bps\bsi\biz\bze\be>\b>]\b][\b[/\b/r\brr\brd\bdf\bfi\bil\bll\blm\bmi\bis\bss\bsi\bin\bng\bg=\b=<\b<f\bfi\bil\bll\bl
  12        m\bmi\bis\bss\bsi\bin\bng\bg n\bn s\bsa\bam\bmp\bpl\ble\bes\bs>\b>]\b]/\b//\b/<\b<t\bta\bab\bbl\ble\be>\b>/\b/<\b<u\bun\bni\bix\bxt\bti\bim\bme\bes\bst\bta\bam\bmp\bp c\bco\bol\blu\bum\bmn\bn>\b>/\b/<\b<d\bda\bat\bta\ba v\bva\bal\blu\bue\be
  13        c\bco\bol\blu\bum\bmn\bn>\b>[\b[/\b/d\bde\ber\bri\biv\bve\be]\b]/\b/<\b<w\bwh\bhe\ber\bre\be c\bcl\bla\bau\bus\bse\be 1\b1>\b>/\b/.\b..\b..\b./\b/<\b<w\bwh\bhe\ber\bre\be c\bcl\bla\bau\bus\bse\be n\bn>\b>
  14
  15 D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN
  16        This pseudo-rrd-filename defines a sql datasource:
  17
  18        s\bsq\bql\bl/\b//\b/
  19                  magic cookie-prefix for a libdbi type datasource
  20
  21        <\b<l\bli\bib\bbd\bdb\bbi\bi d\bdr\bri\biv\bve\ber\br>\b>
  22                  which libdbi driver to use (e.g: mysql)
  23
  24        <\b<d\bdr\bri\biv\bve\ber\br-\b-o\bop\bpt\bti\bio\bon\bn-\b-n\bna\bam\bme\be>\b>=<\b<d\bdr\bri\biv\bve\ber\br-\b-o\bop\bpt\bti\bio\bon\bn-\b-v\bva\bal\blu\bue\be>\b>
  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        /\b/r\brr\brd\bdm\bmi\bin\bns\bst\bte\bep\bps\bsi\biz\bze\be=<\b<m\bmi\bin\bni\bim\bmu\bum\bm s\bst\bte\bep\bp s\bsi\biz\bze\be>\b>
  29                  defines the minimum number of the step-length used for graphing (default: 300 seconds)
  30
  31        /\b/r\brr\brd\bdf\bfi\bil\bll\blm\bmi\bis\bss\bsi\bin\bng\bg=<\b<f\bfi\bil\bll\bl m\bmi\bis\bss\bsi\bin\bng\bg s\bst\bte\bep\bps\bs>\b>
  32                  defines the number of steps to fill with the last value to avoid NaN boxes due to data-insertation jitter (default: 0 steps)
  33
  34        <\b<t\bta\bab\bbl\ble\be>\b>
  35                  defines the table from which to fetch the resultset.
  36
  37                  If there is a need to fetch data from several tables, these tables can be defined by separating the tablenames with a "+"
  38
  39                  hex-type-encoding via %xx are translated to the actual value, use %% to use %
  40
  41        <\b<[\b[*\b*]\b]u\bun\bni\bix\bxt\bti\bim\bme\bes\bst\bta\bam\bmp\bp c\bco\bol\blu\bum\bmn\bn>\b>
  42                  defines the column of E<lt>tableE<gt> which contains the unix-timestamp
  43                  - if this is a DATETIME field in the database, then prefix with leading '*'
  44
  45                  hex-type-encoding via %xx are translated to the actual value, use %% to use %
  46
  47        <\b<d\bda\bat\bta\ba v\bva\bal\blu\bue\be c\bco\bol\blu\bum\bmn\bn>\b>
  48                  defines the column of E<lt>tableE<gt> which contains the value column, which should be graphed
  49
  50                  hex-type-encoding via %xx are translated to the actual value, use %% to use %
  51
  52        /\b/d\bde\ber\bri\biv\bve\be
  53                  defines that the data value used should be the delta of the 2 consecutive values (to simulate COUNTER or DERIVE type datasources)
  54
  55        /\b/<\b<w\bwh\bhe\ber\bre\be c\bcl\bla\bau\bus\bse\be(\b(s\bs)\b)>\b>
  56                  defines one (ore more) where clauses that are joined with AND to filter the entries in the <lt>table<gt>
  57
  58                  hex-type-encoding via %xx are translated to the actual value, use %% to use %
  59
  60        the returned value column-names, which can be used as ds-names, are:
  61
  62        m\bmi\bin\bn, a\bav\bvg\bg, m\bma\bax\bx, c\bco\bou\bun\bnt\bt and s\bsi\big\bgm\bma\ba
  63                  are returned to be used as ds-names in your DS definition.
  64                  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.
  65                  And this results in the same SQL Statements used several times
  66
  67 E\bEX\bXA\bAM\bMP\bPL\bLE\bES\bS
  68        Here an example of a table in a MySQL database:
  69
  70          DB connect information
  71            dbhost=127.0.0.1
  72            user=rrd
  73            password=secret
  74            database=rrd
  75
  76          here the table:
  77            CREATE TABLE RRDValue (
  78              RRDKeyID      bigint(20) NOT NULL,
  79              UnixTimeStamp int(11) NOT NULL,
  80              value         double default NOT NULL,
  81              PRIMARY KEY  (RRDKeyID,UnixTimeStamp)
  82            );
  83
  84        and the RRDKeyID we want to graph for is: 1141942900757789274
  85
  86        The pseudo rrd-filename to access this is:
  87        "sql//mysql/host=127.0.0.1/dbname=rrd/username=rrd/password=secret//RRDValue/UnixTimeStamp/value/RRDKeyID=1141464142203608274"
  88
  89        To illustrate this here a command to create a graph that contains the
  90        actual values.
  91
  92          DS_BASE="sql//mysql/host=127.0.0.1/dbname=rrd/username=rrd/password=passwd//RRDValue/UnixTimeStamp/value/RRDKeyID=1141942900757789274"
  93          rrdtool graph test.png --imgformat=PNG --start=-1day --end=+3hours --width=1000 --height=600 \
  94            "DEF:min=$DS_BASE:min:AVERAGE" \
  95            "LINE1:min#FF0000:value" \
  96            "DEF:avg=$DS_BASE:avg:AVERAGE" \
  97            "LINE1:avg#00FF00:average" \
  98            "DEF:max=$DS_BASE:max:AVERAGE" \
  99            "LINE1:max#FF0000:max" \
 100            "DEF:sigma=$DS_BASE:sigma:AVERAGE" \
 101            "CDEF:upper=avg,4,sigma,*,+" \
 102            "LINE1:upper#0000FF:+4 sigma" \
 103            "CDEF:lower=avg,4,sigma,*,-" \
 104            "LINE1:lower#0000FF:-4 sigma"
 105
 106 N\bNO\bOT\bTE\bES\bS
 107        * Naturally you can also use any other kind of driver that libdbi
 108        supports - e.g postgres, ...
 109
 110        * From the way the datasource is joined, it should also be possible to
 111        do joins over different tables
 112          (separate tables with "," in table and add in the WHERE Clauses the
 113        table equal joins.
 114          This has not been tested!!!)
 115
 116        * It should also be relatively simple to add to the database using the
 117        same datasource string.
 118          This has not been implemented...
 119
 120        * The aggregation functions are ignored and several data columns are
 121        used instead
 122          to avoid querying the same SQL several times when minimum, average
 123        and maximum are needed for graphing...
 124
 125        * for DB efficiency you should think of having 2 tables, one containing
 126        historic values and the other containing the latest data.
 127          This second table should be kept small to allow for the least ammount
 128        of blocking SQL statements.
 129          Whith mysql you can even use myisam table-type for the first and
 130        InnoDB for the second.
 131          This is especially interresting as with tables with +100M rows myisam
 132        is much smaller then InnoDB.
 133
 134        * To debug the SQL statements set the environment variable RRDDEBUGSQL
 135        and the actual SQL statements and the timing is printed to stderr.
 136
 137 B\bBU\bUG\bGS\bS
 138        * at least on Linux please make sure that the libdbi driver is
 139        explicitly linked against libdbi.so.0
 140          check via ldd /usr/lib/dbd/libmysql.so, that there is a line with
 141        libdbi.so.0.
 142          otherwise at least the perl module RRDs will fail because the dynamic
 143        linker can not find some symbols from libdbi.so.
 144          (this only happens when the libdbi driver is actually used the first
 145        time!)
 146          This is KNOWN to be the case with RHEL4 and FC4 and FC5! (But
 147        actually this is a bug with libdbi make files!)
 148
 149        * at least version 0.8.1 of libdbiexhibits a bug with BINARY fields
 150          (shorttext,text,mediumtext,longtext and possibly also BINARY and BLOB
 151        fields),
 152          that can result in coredumps of rrdtool.
 153          The tool will tell you on stderr if this occures, so that you know
 154        what may be the reason.
 155          If you are not experiencing these coredumps, then set the environment
 156        variable RRD_NO_LIBDBI_BUG_WARNING,
 157          and then the message will not get shown.
 158
 159 A\bAU\bUT\bTH\bHO\bOR\bR
 160        Martin Sperl <rrdtool@martin.sperl.org>
 161
 162
 163
 164 1.3.999                           2009-06-09                RRDGRAPH_LIBDBI(1)