README for stats module for rrd
-------------------------------

	usage: (4 function are implemented, perl-type call is described)

	----------------------------------------------------------------
	mean/max/min: computes the average / minimum / maxmimum / integration value for a rrd database, for each ds
	my ($step, $start, $end, $res, $names) = 
		RRDs::stats $rrd, "func:pstep:cf","--start=stime","--end=etime";
	parameters:
	 func : mean/max/min/int
	 pstep : proposed step (function funds the best based on time-range and rra/step availability)
	 cf : consolidation function
	 stime-etime : measure time
	results: 
	 $step : the step that was found and choosen
	 $start, $end : the really start and end
	 $res : list of result
	 $names : list of corresponding ds names
	examples: 
	 my ($step, $start, $end, $avg, $names) = RRDs::stats $rrd, "mean:300:AVERAGE","--start=-1m";
	 my ($step, $start, $end, $avg, $names) = RRDs::stats $rrd, "min:300:AVERAGE","--start=-1d";
	 my ($step, $start, $end, $avg, $names) = RRDs::stats $rrd, "max:300:AVERAGE","--start=-1w";
	 my ($step, $start, $end, $avg, $names) = RRDs::stats $rrd, "int:300:AVERAGE","--start=-1w";

	----------------------------------------------------------------
	dist: computes the distribution of values for a given ds in an rrd
	my ($step, $start, $end, $before, $after, $res) = 
		RRDs::stats $rrd, "dist:minval:maxval:ds:nbdist:pstep:cf","--start=stime","--end=$etime";
	parameters:
	 pstep : proposed step (function funds the best based on time-range and rra/step availability)
	 ds : name of ds
	 nbdist : number of interval to compute dist (between minval and maxval)
	 cf : consolidation function
	 stime-etime : measure time
	 maxval, minval : minimum and maximum value to compute the distribution
	results: 
	 $step : the step that was found and choosen
	 $start, $end : the really start and end
	 $res : list of results
	 $before, $after : results that are <minval(before) of > maxval(after)
	example: 
	my ($step, $sta, $en, $before, $after, $res) = RRDs::stats $rrd, "dist:0:100:ds1:10:300:AVERAGE","--start=-1d";

	----------------------------------------------------------------
	rrd_stats choose the rra with the following rules : (not same as fetch or graph)
	- for each rra it computes an overlap factor that is the factor between the requested 
	  range (end-start) and the available range of this rra
	- for overlap factor that are not 'very' different (90%), it take the step that is 
	  closest from the proposed step );



2005, philippe.simonet at swisscom.com