big spell checking patch -- slif@bellsouth.net

[rrdtool.git] / doc / rrdfetch.pod

diff --git a/doc/rrdfetch.pod b/doc/rrdfetch.pod
index c938bb5..a4e87c5 100644 (file)
--- a/doc/rrdfetch.pod
+++ b/doc/rrdfetch.pod
@@ -1,6 +1,6 @@
 =head1 NAME
 
-rrdtool fetch - fetch data from an rrd.
+rrdtool fetch - fetch data from an RRD.
 
 =for html <div align="right"><a href="rrdfetch.pdf">PDF</a> version.</div>
 
@@ -17,7 +17,7 @@ The B<fetch> function is normally used internally by the graph function,
 to get data from B<RRD>s. B<fetch> will analyze the B<RRD> and
 will try to retrieve the data in the resolution requested.
 The data fetched is printed to stdout. I<*UNKNOWN*> data is often
-represented by the string "NaN" depending on your OSs printf
+represented by the string "NaN" depending on your OS's printf
 function.
 
 =over 8
@@ -35,7 +35,7 @@ want to fetch? (AVERAGE,MIN,MAX,LAST)
 
 what interval should the values have (seconds per value). B<rrdfetch> will try
 to match your request, but it will return data even if no absolute
-match is possible.
+match is possible. B<NB.> See note below.
 
 =item B<--start>|B<-s> I<start> (default end-1day)
 
@@ -52,9 +52,65 @@ end time.
 
 =back
 
+=head2 RESOLUTION INTERVAL
+
+In order to get RRDtool to fetch anything other than the finest resolution RRA 
+B<both> the start and end time must be specified on boundaries that are 
+multiples of the wanted resolution. Consider the following example:
+
+ rrdtool create subdata.rrd -s 10 DS:ds0:GAUGE:300:0:U \
+  RRA:AVERAGE:0.5:30:3600 \
+  RRA:AVERAGE:0.5:90:1200 \
+  RRA:AVERAGE:0.5:360:1200 \
+  RRA:MAX:0.5:360:1200 \
+  RRA:AVERAGE:0.5:8640:600 \
+  RRA:MAX:0.5:8640:600
+
+This RRD collects data every 10 seconds and stores its averages over 5 minutes, 
+15 minutes, 1 hour and 1 day as well as the maxima for 1 hour and 1 day.
+
+Consider now that you want too fetch the 15 minute average data for last hour. 
+So you might try
+
+ rrdtool fetch subdata.rrd AVERAGE -r 900 -s -1h
+
+However, this will almost always result in a time series that is B<NOT> in the 15 
+minute RRA. Therefore the highest resolution RRA, i.e. 5 minute averages, will 
+be chosen which, in this case, is not what you want.
+
+Hence, make sure that
+
+=over 3
+
+=item 1.
+
+both start and end time are a multiple of 900
+
+=item 2.
+
+both start and end time are within the wanted RRA
+
+=back
+
+So, if time now is called "t",
+
+ do end time == int(t/900)*900,
+ start time == end time -1hour, resolution == 900.
+
+In e.g. bash this could look as:
+
+ TIME=$(date +%s); RRDRES=900; rrdtool fetch subdata.rrd AVERAGE -r $RRDRES \
+ -e $(echo $(($TIME/$RRDRES*$RRDRES))) -s e-1h
+
+Or in Perl:
+
+ perl -e '$ctime = time; $rrdres = 900; system "rrdtool fetch subdata.rrd AVERAGE \
+ -r $rrdres -e @{[int($ctime/$rrdres)*$rrdres]} -s e-1h"'
+
+
 =head2 AT-STYLE TIME SPECIFICATION
 
-Apart from the traditional I<Seconds since epoch>, rrdtool does also
+Apart from the traditional I<Seconds since epoch>, RRDtool does also
 understand at-style time specification.  The specification is called
 "at-style" after Unix command at(1) that has moderately complex ways
 to specify time to run your job at.  The at-style specification
@@ -92,7 +148,7 @@ Finally, you can use words B<now>, B<start>, or B<end> as your time
 reference. B<Now> refers to the current moment (and is also a default
 time reference). B<Start> (B<end>) can be used to specify time
 relative to the start (end) time for those tools that use these
-categories (rrdfetch, rrdgraph).
+categories (B<rrdfetch>, L<rrdgraph>).
 
 Month and weekday names can be used in their naturally abbreviated form
 (e.g., Dec for December, Sun for Sunday, etc.). The words B<now>,
@@ -192,8 +248,7 @@ I<931225537> -- 18:45  July 5th, 1999
 (yes, seconds since 1970 are valid as well)
 
 I<19970703 12:45> -- 12:45  July 3th, 1997
-(not quote standard, but I love this ...)
-
+(my favorite, and its even got an ISO number (8601))
 
 =head1 AUTHOR