X-Git-Url: https://git.octo.it/?a=blobdiff_plain;f=doc%2Frrdfetch.pod;h=51b5ccd99c8441f8f7f12021836ba22a902ccc56;hb=e9886414f2f1906716f183cc4dedcfe01ec2c0de;hp=0b57340ca0c0721c3b76fda6784ac08c70b2c8ab;hpb=d53241d45f61489bd1bd2fb1aab5e6183db6009d;p=rrdtool.git
diff --git a/doc/rrdfetch.pod b/doc/rrdfetch.pod
index 0b57340..51b5ccd 100644
--- a/doc/rrdfetch.pod
+++ b/doc/rrdfetch.pod
@@ -1,62 +1,60 @@
=head1 NAME
-rrdtool fetch - fetch data from an rrd.
-
-=for html
+rrdfetch - Fetch data from an RRD.
=head1 SYNOPSIS
-B B I I
-S<[B<--resolution>|B<-r> I]>
-S<[B<--start>|B<-s> I]>
-S<[B<--end>|B<-e> I]>
+B B I I
+S<[B<--resolution>|B<-r> I]>
+S<[B<--start>|B<-s> I]>
+S<[B<--end>|B<-e> I]>
=head1 DESCRIPTION
-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 B function is normally used internally by the graph
+function to get data from Bs. B will analyze the B
+and 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
-=item I
+=item I
the name of the B you want to fetch the data from.
-=item I
+=item I
-which consolidation function should have been applied to the data you
-want to fetch? (AVERAGE,MIN,MAX,LAST)
+the consolidation function that is applied to the data you
+want to fetch (AVERAGE,MIN,MAX,LAST)
=item B<--resolution>|B<-r> I (default is the highest resolution)
-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. B See note below.
+the interval you want the values to have (seconds per
+value). B will try to match your request, but it will return
+data even if no absolute match is possible. B See note below.
=item B<--start>|B<-s> I (default end-1day)
-when should the data begin. A time in seconds since epoch (1970-01-01)
-is required. Negative numbers are relative to the current time. By default
+start of the time series. A time in seconds since epoch (1970-01-01)
+is required. Negative numbers are relative to the current time. By default,
one day worth of data will be fetched. See also AT-STYLE TIME SPECIFICATION
-section for a detailed explanation on ways to specify start time.
+section for a detailed explanation on ways to specify the start time.
=item B<--end>|B<-e> I (default now)
-when should the data end. Time in seconds since epoch. See also
-AT-STYLE TIME SPECIFICATION section for a detailed explanation of how to specify
-end time.
+the end of the time series in seconds since epoch. See also AT-STYLE
+TIME SPECIFICATION section for a detailed explanation of how to
+specify the 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:
+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 desired resolution. Consider the following example:
rrdtool create subdata.rrd -s 10 DS:ds0:GAUGE:300:0:U \
RRA:AVERAGE:0.5:30:3600 \
@@ -66,17 +64,19 @@ multiples of the wanted resolution. Consider the following example:
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.
+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
+Consider now that you want to fetch the 15 minute average data for the
+last hour. 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.
+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
@@ -88,110 +88,116 @@ both start and end time are a multiple of 900
=item 2.
-both start and end time are within the wanted RRA
+both start and end time are within the desired RRA
=back
-So, if time now is called "t",
+So, if time now is called "t", do
- do end time == int(t/900)*900,
- start time == end time -1hour, resolution == 900.
+ end time == int(t/900)*900,
+ start time == end time - 1hour,
+ resolution == 900.
-In e.g. bash this could look as:
+Using the bash shell, this could look be:
- TIME=$(date +%s); RRDRES=900; rrdtool fetch subdata.rrd AVERAGE -r $RRDRES \
- -e $(echo $(($TIME/$RRDRES*$RRDRES))) -s e-1h
+ TIME=$(date +%s)
+ RRDRES=900
+ rrdtool fetch subdata.rrd AVERAGE -r $RRDRES \
+ -e $(($TIME/$RRDRES*$RRDRES)) -s e-1h
-Or in perl:
+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"'
+ 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
-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
-consists of two parts: B