doc/rrdgraph_libdbi.1

   1 .\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.08)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 'br\}
  42 .\"
  43 .\" Escape single quotes in literal strings from groff's Unicode transform.
  44 .ie \n(.g .ds Aq \(aq
  45 .el       .ds Aq '
  46 .\"
  47 .\" If the F register is turned on, we'll generate index entries on stderr for
  48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  50 .\" output yourself in some meaningful fashion.
  51 .ie \nF \{\
  52 .    de IX
  53 .    tm Index:\\$1\t\\n%\t"\\$2"
  54 ..
  55 .    nr % 0
  56 .    rr F
  57 .\}
  58 .el \{\
  59 .    de IX
  60 ..
  61 .\}
  62 .\"
  63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  65 .    \" fudge factors for nroff and troff
  66 .if n \{\
  67 .    ds #H 0
  68 .    ds #V .8m
  69 .    ds #F .3m
  70 .    ds #[ \f1
  71 .    ds #] \fP
  72 .\}
  73 .if t \{\
  74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  75 .    ds #V .6m
  76 .    ds #F 0
  77 .    ds #[ \&
  78 .    ds #] \&
  79 .\}
  80 .    \" simple accents for nroff and troff
  81 .if n \{\
  82 .    ds ' \&
  83 .    ds ` \&
  84 .    ds ^ \&
  85 .    ds , \&
  86 .    ds ~ ~
  87 .    ds /
  88 .\}
  89 .if t \{\
  90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 105 .ds ae a\h'-(\w'a'u*4/10)'e
 106 .ds Ae A\h'-(\w'A'u*4/10)'E
 107 .    \" corrections for vroff
 108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 110 .    \" for low resolution devices (crt and lpr)
 111 .if \n(.H>23 .if \n(.V>19 \
 112 \{\
 113 .    ds : e
 114 .    ds 8 ss
 115 .    ds o a
 116 .    ds d- d\h'-1'\(ga
 117 .    ds D- D\h'-1'\(hy
 118 .    ds th \o'bp'
 119 .    ds Th \o'LP'
 120 .    ds ae ae
 121 .    ds Ae AE
 122 .\}
 123 .rm #[ #] #H #V #F C
 124 .\" ========================================================================
 125 .\"
 126 .IX Title "RRDGRAPH_LIBDBI 1"
 127 .TH RRDGRAPH_LIBDBI 1 "2009-06-09" "1.3.999" "rrdtool"
 128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 129 .\" way too many mistakes in technical documents.
 130 .if n .ad l
 131 .nh
 132 .SH "NAME"
 133 rrdgraph_libdbi \- fetching data for graphing in rrdtool graph via libdbi
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 <rrdfile> = \fBsql//<libdbi driver>/<driver\-option\-name>=<driver\-option\-value>/...[/rrdminstepsize=<stepsize>][/rrdfillmissing=<fill missing n samples>]//<table>/<unixtimestamp column>/<data value column>[/derive]/<where clause 1>/.../<where clause n>\fR
 137 .SH "DESCRIPTION"
 138 .IX Header "DESCRIPTION"
 139 This pseudo-rrd-filename defines a sql datasource:
 140 .IP "\fBsql//\fR" 8
 141 .IX Item "sql//"
 142 .Vb 1
 143 \&  magic cookie\-prefix for a libdbi type datasource
 144 .Ve
 145 .IP "\fB<libdbi driver>\fR" 8
 146 .IX Item "<libdbi driver>"
 147 .Vb 1
 148 \&  which libdbi driver to use (e.g: mysql)
 149 .Ve
 150 .IP "\fB<driver\-option\-name>\fR=\fB<driver\-option\-value>\fR" 8
 151 .IX Item "<driver-option-name>=<driver-option-value>"
 152 .Vb 2
 153 \&  defines the parameters that are required to connect to the database with the given libdbi driver
 154 \&  (These drivers are libdbi dependent \- for details please look at the driver documentation of libdbi!)
 155 .Ve
 156 .IP "\fB/rrdminstepsize\fR=\fB<minimum step size>\fR" 8
 157 .IX Item "/rrdminstepsize=<minimum step size>"
 158 .Vb 1
 159 \&  defines the minimum number of the step\-length used for graphing (default: 300 seconds)
 160 .Ve
 161 .IP "\fB/rrdfillmissing\fR=\fB<fill missing steps>\fR" 8
 162 .IX Item "/rrdfillmissing=<fill missing steps>"
 163 .Vb 1
 164 \&  defines the number of steps to fill with the last value to avoid NaN boxes due to data\-insertation jitter (default: 0 steps)
 165 .Ve
 166 .IP "\fB<table>\fR" 8
 167 .IX Item "<table>"
 168 .Vb 1
 169 \&  defines the table from which to fetch the resultset.
 170 \&
 171 \&  If there is a need to fetch data from several tables, these tables can be defined by separating the tablenames with a "+"
 172 \&
 173 \&  hex\-type\-encoding via %xx are translated to the actual value, use %% to use %
 174 .Ve
 175 .IP "\fB<[*]unixtimestamp column>\fR" 8
 176 .IX Item "<[*]unixtimestamp column>"
 177 .Vb 2
 178 \&  defines the column of E<lt>tableE<gt> which contains the unix\-timestamp
 179 \&  \- if this is a DATETIME field in the database, then prefix with leading \*(Aq*\*(Aq
 180 \&
 181 \&  hex\-type\-encoding via %xx are translated to the actual value, use %% to use %
 182 .Ve
 183 .IP "\fB<data value column>\fR" 8
 184 .IX Item "<data value column>"
 185 .Vb 1
 186 \&  defines the column of E<lt>tableE<gt> which contains the value column, which should be graphed
 187 \&
 188 \&  hex\-type\-encoding via %xx are translated to the actual value, use %% to use %
 189 .Ve
 190 .IP "\fB/derive\fR" 8
 191 .IX Item "/derive"
 192 .Vb 1
 193 \&  defines that the data value used should be the delta of the 2 consecutive values (to simulate COUNTER or DERIVE type datasources)
 194 .Ve
 195 .IP "\fB/<where clause(s)>\fR" 8
 196 .IX Item "/<where clause(s)>"
 197 .Vb 1
 198 \&  defines one (ore more) where clauses that are joined with AND to filter the entries in the <lt>table<gt>
 199 \&
 200 \&  hex\-type\-encoding via %xx are translated to the actual value, use %% to use %
 201 .Ve
 202 .PP
 203 the returned value column-names, which can be used as ds-names, are:
 204 .IP "\fBmin\fR, \fBavg\fR, \fBmax\fR, \fBcount\fR and \fBsigma\fR" 8
 205 .IX Item "min, avg, max, count and sigma"
 206 .Vb 3
 207 \&  are returned to be used as ds\-names in your DS definition.
 208 \&  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.
 209 \&  And this results in the same SQL Statements used several times
 210 .Ve
 211 .SH "EXAMPLES"
 212 .IX Header "EXAMPLES"
 213 Here an example of a table in a MySQL database:
 214 .PP
 215 .Vb 5
 216 \&  DB connect information
 217 \&    dbhost=127.0.0.1
 218 \&    user=rrd
 219 \&    password=secret
 220 \&    database=rrd
 221 \&
 222 \&  here the table:
 223 \&    CREATE TABLE RRDValue (
 224 \&      RRDKeyID      bigint(20) NOT NULL,
 225 \&      UnixTimeStamp int(11) NOT NULL,
 226 \&      value         double default NOT NULL,
 227 \&      PRIMARY KEY  (RRDKeyID,UnixTimeStamp)
 228 \&    );
 229 .Ve
 230 .PP
 231 and the RRDKeyID we want to graph for is: 1141942900757789274
 232 .PP
 233 The pseudo rrd-filename to access this is:
 234 \&\*(L"sql//mysql/host=127.0.0.1/dbname=rrd/username=rrd/password=secret//RRDValue/UnixTimeStamp/value/RRDKeyID=1141464142203608274\*(R"
 235 .PP
 236 To illustrate this here a command to create a graph that contains the actual values.
 237 .PP
 238 .Vb 10
 239 \&  DS_BASE="sql//mysql/host=127.0.0.1/dbname=rrd/username=rrd/password=passwd//RRDValue/UnixTimeStamp/value/RRDKeyID=1141942900757789274"
 240 \&  rrdtool graph test.png \-\-imgformat=PNG \-\-start=\-1day \-\-end=+3hours \-\-width=1000 \-\-height=600 \e
 241 \&    "DEF:min=$DS_BASE:min:AVERAGE" \e
 242 \&    "LINE1:min#FF0000:value" \e
 243 \&    "DEF:avg=$DS_BASE:avg:AVERAGE" \e
 244 \&    "LINE1:avg#00FF00:average" \e
 245 \&    "DEF:max=$DS_BASE:max:AVERAGE" \e
 246 \&    "LINE1:max#FF0000:max" \e
 247 \&    "DEF:sigma=$DS_BASE:sigma:AVERAGE" \e
 248 \&    "CDEF:upper=avg,4,sigma,*,+" \e
 249 \&    "LINE1:upper#0000FF:+4 sigma" \e
 250 \&    "CDEF:lower=avg,4,sigma,*,\-" \e
 251 \&    "LINE1:lower#0000FF:\-4 sigma"
 252 .Ve
 253 .SH "NOTES"
 254 .IX Header "NOTES"
 255 * Naturally you can also use any other kind of driver that libdbi supports \- e.g postgres, ...
 256 .PP
 257 * From the way the datasource is joined, it should also be possible to do joins over different tables
 258   (separate tables with \*(L",\*(R" in table and add in the \s-1WHERE\s0 Clauses the table equal joins.
 259   This has not been tested!!!)
 260 .PP
 261 * It should also be relatively simple to add to the database using the same datasource string.
 262   This has not been implemented...
 263 .PP
 264 * The aggregation functions are ignored and several data columns are used instead
 265   to avoid querying the same \s-1SQL\s0 several times when minimum, average and maximum are needed for graphing...
 266 .PP
 267 * for \s-1DB\s0 efficiency you should think of having 2 tables, one containing historic values and the other containing the latest data.
 268   This second table should be kept small to allow for the least ammount of blocking \s-1SQL\s0 statements.
 269   Whith mysql you can even use myisam table-type for the first and InnoDB for the second.
 270   This is especially interresting as with tables with +100M rows myisam is much smaller then InnoDB.
 271 .PP
 272 * To debug the \s-1SQL\s0 statements set the environment variable \s-1RRDDEBUGSQL\s0 and the actual \s-1SQL\s0 statements and the timing is printed to stderr.
 273 .SH "BUGS"
 274 .IX Header "BUGS"
 275 * at least on Linux please make sure that the libdbi driver is explicitly linked against libdbi.so.0
 276   check via ldd /usr/lib/dbd/libmysql.so, that there is a line with libdbi.so.0.
 277   otherwise at least the perl module RRDs will fail because the dynamic linker can not find some symbols from libdbi.so.
 278   (this only happens when the libdbi driver is actually used the first time!)
 279   This is \s-1KNOWN\s0 to be the case with \s-1RHEL4\s0 and \s-1FC4\s0 and \s-1FC5\s0! (But actually this is a bug with libdbi make files!)
 280 .PP
 281 * at least version 0.8.1 of libdbiexhibits a bug with \s-1BINARY\s0 fields
 282   (shorttext,text,mediumtext,longtext and possibly also \s-1BINARY\s0 and \s-1BLOB\s0 fields),
 283   that can result in coredumps of rrdtool.
 284   The tool will tell you on stderr if this occures, so that you know what may be the reason.
 285   If you are not experiencing these coredumps, then set the environment variable \s-1RRD_NO_LIBDBI_BUG_WARNING\s0,
 286   and then the message will not get shown.
 287 .SH "AUTHOR"
 288 .IX Header "AUTHOR"
 289 Martin Sperl <rrdtool@martin.sperl.org>