[rrd-developers] [rrd-users] [PATCH + RFC] Cleanup the symbols exported by librrd.

[Tobias Oetiker]

Bernhard,

in the light of the pending 1.3.0 release I will keep further
changes apart from exposing the extra functions for the next
release cycle.

cheers
tobi
Today Bernhard Fischer wrote:

> On Mon, Jun 09, 2008 at 10:46:40AM +0200, Sebastian Harl wrote:
> >Hi,
> >
> >On Sun, Jun 08, 2008 at 11:15:16PM +0200, Tobias Oetiker wrote:
> >> Today Bernhard Fischer wrote:
> >> > > * I did not include rrd_open(), rrd_close(), rrd_write() and similar
> >> > >   functions in the public interface so far as they look like pretty
> >> > >   low-level functions which usually are not needed outside of rrdtool.
> >> >
> >> > These functions should be exported since any librrdtool is pretty
> >> > useless without them.
> >> >
> >> > Suppose i want to write a program that opens an rrd and reads one or
> >> > more DS and a varying number of entries from some CF, calculates
> >> > something and returns a result. Currently i would have to do alot of
> >> > what fetch does to achieve this, which doesn't make sense in the light
> >> > of a librrdtool.
> >> > See
> >> > http://www.mail-archive.com/rrd-developers@lists.oetiker.ch/msg01866.html
> >>
> >> so would
> >>
> >> rrd_open
> >> rrd_read
> >> rrd_close
> >> rrd_tell
> >> rrd_write
> >>
> >> be enough, or should there be more ?
> >
> >Imho, rrd_flush, rrd_seek and rrd_lock would make sense as well. Also,
> >as those functions use parameters of type rrd_t, I would add rrd_init
> >and rrd_free as well. I'm not quite sure about the purpose of
> >rrd_dontneed but I'd tend to rather include all of those functions or
> >none at all. I think, the interfaces should be fairly stable so we
> >should not run into much problems caused by API/ABI changes.
>
> fetch_fn() too, but it needs fixes. See below.
>
> I'm attaching a small application that is based off rrdtool that i use
> to provide nagios-checks.
>
> E.g.:
> ----- 8< -----
> # 'check_rrd_value' checks data from rrd file
> # .../rrd_reader /a/file.rrd discards_out LAST -n3 -w0.2 -c1.0 -ge -o'mystring'
> define command{
>   command_name  check_rrd_traffic_discards
>   command_line  $USER1$/rrd_reader $ARG1$ $ARG2$ $ARG3$ -n$ARG4$ -w$ARG5$ -c$ARG6$ $ARG7$ -o'$ARG8$'
> }
>
> # Check for e.g. CPU utilization
> define command{
>   command_name  check_rrd_cpu_util
>   command_line  $USER1$/rrd_reader $ARG1$ $ARG2$ $ARG3$ -n$ARG4$ -w$ARG5$ -c$ARG6$ $ARG7$
> }
> ----- 8< -----
>
> The applet itself has to do something like:
> ----- 8< -----
> # /opt/nagios_snmp/bin/rrd_reader
> rrd_reader 0.7.5  20080527 13:23:22 +0200
> Usage: rrd_reader
> 	file.rrd	rrd file to read
> 	DS		ds_def[].ds_nam, name of the DataSource
> 	CF		rra[].cf, e.g. "LAST" or "AVERAGE"
> 	-n<count>	number of data-points (default 1, i.e. most recent)
> 	-w<val,percent>	Warning threshold
> 	-c<val,percent>	Critical threshold
> 	-z<arith>	[min|avg|max] applied to counter
> 	-M<multiplier>	multiply value from rrd by this (default 1.0)
> 	-o<string>	append string to output
> 	[-le|-ge]	Warning/Critical if less or greater equal, respectively
>
> If no arith was given, all <num> recent values are used.
> If arith was given, the result of <arith> applied to num is used.
> Arguments have to be specified without an intermittent space.
>
> The -M<multiplier> is useful of you recorded data with one
> metric but want to use warning/critical thresholds in a different
> metric (e.g. bytes vs. bits).
> ----- 8< -----
>
> You can see how i had to:
> a) duplicate basically all of rrd_format.h
> b) had to duplicate those parts of fetching values that deal with the
> calculation of the locus of the data we need.
>
>
> The applet should basically do this instead:
> 0) [APP] option handling
> 1) call rrd_open()
> 2) [APP] eventually inspect the header.
> 3) [APP] setup desired start, end, step.
> 4) call rrd_find_rra() or rrd_find_best_rra() /* or however it would be
>    called */
> 5) [APP] adjust start, end, step to legit values.
> 6) call rrd_fetch_fn()
> 7) [APP] rrd_close(); rrd_free()
> 8) [APP] do something with the results and exit.
>
> Where stuff marked with [APP] is ok to be done by the application, but
> the rest (points 1, 4, 6) should be just simple calls into librrd.
>
>

-- 
Tobi Oetiker, OETIKER+PARTNER AG, Aarweg 15 CH-4600 Olten
http://it.oetiker.ch tobi at oetiker.ch ++41 62 213 9902