X-Git-Url: https://git.octo.it/?a=blobdiff_plain;f=doc%2Frrdfetch.pod;h=a4e87c54d10bc15bfa53440464c8a49d70cc0d88;hb=85531c9fe3758d08f782503f888fff12b7c002f5;hp=c938bb545ebf08042265251b376babcd3e38f7f0;hpb=5837606887a6d81e8b1f7588525cb1c8783fb62b;p=rrdtool.git
diff --git a/doc/rrdfetch.pod b/doc/rrdfetch.pod
index c938bb5..a4e87c5 100644
--- 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
@@ -17,7 +17,7 @@ The B function is normally used internally by the graph function,
to get data from Bs. B will analyze the B 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 will try
to match your request, but it will return data even if no absolute
-match is possible.
+match is possible. B See note below.
=item B<--start>|B<-s> I (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 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 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, rrdtool does also
+Apart from the traditional I, 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, B, or B as your time
reference. B refers to the current moment (and is also a default
time reference). B (B) can be used to specify time
relative to the start (end) time for those tools that use these
-categories (rrdfetch, rrdgraph).
+categories (B, L).
Month and weekday names can be used in their naturally abbreviated form
(e.g., Dec for December, Sun for Sunday, etc.). The words B,
@@ -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