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

[Bernhard Fischer]

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.

-------------- next part --------------
A non-text attachment was scrubbed...
Name: rrd_reader.h
Type: text/x-chdr
Size: 4592 bytes
Desc: not available
Url : http://lists.oetiker.ch/pipermail/rrd-developers/attachments/20080609/e4b437c0/attachment-0002.bin 
-------------- next part --------------
A non-text attachment was scrubbed...
Name: rrd_reader.c
Type: text/x-csrc
Size: 24746 bytes
Desc: not available
Url : http://lists.oetiker.ch/pipermail/rrd-developers/attachments/20080609/e4b437c0/attachment-0003.bin