From aba8467a2e53519ec836e778c08f04a79caaf035 Mon Sep 17 00:00:00 2001 From: oetiker Date: Sun, 16 Nov 2008 22:24:44 +0000 Subject: [PATCH] missing pod files git-svn-id: svn://svn.oetiker.ch/rrdtool/trunk/program@1670 a5681a0c-68f1-0310-ab6d-d61299d08faa --- doc/RRDp.pod | 1 + doc/RRDs.pod | 1 + doc/rrdgraph_libdbi.pod | 150 ++++++++++++++++++++++++++++++++++++++++ 3 files changed, 152 insertions(+) create mode 120000 doc/RRDp.pod create mode 120000 doc/RRDs.pod create mode 100644 doc/rrdgraph_libdbi.pod diff --git a/doc/RRDp.pod b/doc/RRDp.pod new file mode 120000 index 0000000..11703f7 --- /dev/null +++ b/doc/RRDp.pod @@ -0,0 +1 @@ +../bindings/perl-piped/RRDp.pm \ No newline at end of file diff --git a/doc/RRDs.pod b/doc/RRDs.pod new file mode 120000 index 0000000..30a99d2 --- /dev/null +++ b/doc/RRDs.pod @@ -0,0 +1 @@ +../bindings/perl-shared/RRDs.pm \ No newline at end of file diff --git a/doc/rrdgraph_libdbi.pod b/doc/rrdgraph_libdbi.pod new file mode 100644 index 0000000..6ff8728 --- /dev/null +++ b/doc/rrdgraph_libdbi.pod @@ -0,0 +1,150 @@ +=head1 NAME + +rrdgraph_libdbi - fetching data for graphing in rrdtool graph via libdbi + +=head1 SYNOPSIS + +ErrdfileE = Blibdbi driverE/Edriver-option-nameE=Edriver-option-valueE/...[/rrdminstepsize=EstepsizeE][/rrdfillmissing=Efill missing n samplesE]//EtableE/Eunixtimestamp columnE/Edata value columnE[/derive]/Ewhere clause 1E/.../Ewhere clause nE> + +=head1 DESCRIPTION + +This pseudo-rrd-filename defines a sql datasource: + +=over 8 + +=item B + + magic cookie-prefix for a libdbi type datasource + +=item Blibdbi driverE> + + which libdbi driver to use (e.g: mysql) + +=item Bdriver-option-nameE>=Bdriver-option-valueE> + + defines the parameters that are required to connect to the database with the given libdbi driver + (These drivers are libdbi dependent - for details please look at the driver documentation of libdbi!) + +=item B=Bminimum step sizeE> + + defines the minimum number of the step-length used for graphing (default: 300 seconds) + +=item B=Bfill missing stepsE> + + defines the number of steps to fill with the last value to avoid NaN boxes due to data-insertation jitter (default: 0 steps) + +=item BtableE> + + defines the table from which to fetch the resultset. + + If there is a need to fetch data from several tables, these tables can be defined by separating the tablenames with a "+" + + hex-type-encoding via %xx are translated to the actual value, use %% to use % + +=item Bunixtimestamp columnE> + + defines the column of EtableE which contains the unix timestamp + + hex-type-encoding via %xx are translated to the actual value, use %% to use % + +=item Bdata value columnE> + + defines the column of EtableE which contains the value column, which should be graphed + + hex-type-encoding via %xx are translated to the actual value, use %% to use % + +=item B + + defines that the data value used should be the delta of the 2 consecutive values (to simulate COUNTER or DERIVE type datasources) + +=item Bwhere clause(s)E> + + defines one (ore more) where clauses that are joined with AND to filter the entries in the table + + hex-type-encoding via %xx are translated to the actual value, use %% to use % + +=back + +the returned value column-names, which can be used as ds-names, are: + +=over 8 + +=item B, B, B, B and B + + are returned to be used as ds-names in your DS definition. + 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. + And this results in the same SQL Statements used several times + +=back + +=head1 EXAMPLES + +Here an example of a table in a mysql database: + + DB connect information + dbhost=127.0.0.1 + user=rrd + password=secret + database=rrd + + here the table: + CREATE TABLE RRDValue ( + RRDKeyID bigint(20) NOT NULL, + UnixTimeStamp int(11) NOT NULL, + value double default NOT NULL, + PRIMARY KEY (RRDKeyID,UnixTimeStamp) + ); + +and the RRDKeyID we want to graph for is: 1141942900757789274 + +The pseudo rrd-filename to access this is: +"sql//mysql/host=127.0.0.1/dbname=rrd/username=rrd/password=secret//RRDValue/UnixTimeStamp/value/RRDKeyID=1141464142203608274" + +To illustrate this here a command to create a graph that contains the actual values. + + DS_BASE="sql//mysql/host=127.0.0.1/dbname=rrd/username=rrd/password=passwd//RRDValue/UnixTimeStamp/value/RRDKeyID=1141942900757789274" + rrdtool graph test.png --imgformat=PNG --start=-1day --end=+3hours --width=1000 --height=600 \ + "DEF:min=$DS_BASE:min:AVERAGE" \ + "LINE1:min#FF0000:value" \ + "DEF:avg=$DS_BASE:avg:AVERAGE" \ + "LINE1:avg#00FF00:average" \ + "DEF:max=$DS_BASE:max:AVERAGE" \ + "LINE1:max#FF0000:max" \ + "DEF:sigma=$DS_BASE:sigma:AVERAGE" \ + "CDEF:upper=avg,4,sigma,*,+" \ + "LINE1:upper#0000FF:+4 sigma" \ + "CDEF:lower=avg,4,sigma,*,-" \ + "LINE1:lower#0000FF:-4 sigma" + +=head1 NOTES + +* Naturally you can also use any other kind of driver that libdbi supports - e.g postgress,... + +* From the way the datasource is joined, it should also be possible to do joins over different tables + (separate tables with "," in table and add in the WHERE Clauses the table equal joins. + This has not been tested!!!) + +* It should also be relatively simple to add to the database using the same datasource string. + This has not been implemented... + +* The aggregation functions are ignored and several data columns are used instead + to avoid querying the same SQL several times when minimum, average and maximum are needed for graphing... + +* for DB efficiency you should think of having 2 tables, one containing historic values and the other containing the latest data. + This second table should be kept small to allow for the least ammount of blocking SQL statements. + Whith mysql you can even use myisam table-type for the first and InnoDB for the second. + This is especially interresting as with tables with +100M rows myisam is much smaller then InnoDB. + +* To debug the SQL statements set the environment variable RRDDEBUGSQL and the actual SQL statements and the timing is printed to stderr. + +=head1 BUGS + +* at least on Linux please make sure that the libdbi driver is explicitly linked against libdbi.so.0 + check via ldd /usr/lib/dbd/libmysql.so, that there is a line with libdbi.so.0. + otherwise at least the perl module RRDs will fail because the dynamic linker can not find some symbols from libdbi.so. + (this only happens when the libdbi driver is actually used the first time!) + This is KNOWN to be the case with RHEL4 and FC4 and FC5! (But actually this is a bug with libdbi make files!) + +=head1 AUTHOR + +Martin Sperl -- 2.30.2