3eeb4f2803fd36f7a03ea9f2d369c4fcb2fe9ece
1 RRDGRAPH_LIBDBI(1) rrdtool RRDGRAPH_LIBDBI(1)
6 rrdgraph_libdbi - fetching data for graphing in rrdtool graph via
7 libdbi
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>
16 This pseudo-rrd-filename defines a sql datasource:
19 magic cookie-prefix for a libdbi type datasource
22 which libdbi driver to use (e.g: mysql)
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!)
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)
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)
35 defines the table from which to fetch the resultset.
37 If there is a need to fetch data from several tables, these tables can be defined by separating the tablenames with a "+"
39 hex-type-encoding via %xx are translated to the actual value, use %% to use %
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 '*'
45 hex-type-encoding via %xx are translated to the actual value, use %% to use %
48 defines the column of E<lt>tableE<gt> which contains the value column, which should be graphed
50 hex-type-encoding via %xx are translated to the actual value, use %% to use %
53 defines that the data value used should be the delta of the 2 consecutive values (to simulate COUNTER or DERIVE type datasources)
56 defines one (ore more) where clauses that are joined with AND to filter the entries in the <lt>table<gt>
58 hex-type-encoding via %xx are translated to the actual value, use %% to use %
60 the returned value column-names, which can be used as ds-names, are:
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
68 Here an example of a table in a MySQL database:
70 DB connect information
71 dbhost=127.0.0.1
72 user=rrd
73 password=secret
74 database=rrd
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 );
84 and the RRDKeyID we want to graph for is: 1141942900757789274
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"
89 To illustrate this here a command to create a graph that contains the
90 actual values.
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"
107 * Naturally you can also use any other kind of driver that libdbi
108 supports - e.g postgres, ...
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!!!)
116 * It should also be relatively simple to add to the database using the
117 same datasource string.
118 This has not been implemented...
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...
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.
134 * To debug the SQL statements set the environment variable RRDDEBUGSQL
135 and the actual SQL statements and the timing is printed to stderr.
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!)
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.
160 Martin Sperl <rrdtool@martin.sperl.org>
164 1.3.999 2009-06-09 RRDGRAPH_LIBDBI(1)