X-Git-Url: https://git.octo.it/?a=blobdiff_plain;f=doc%2Frrdfetch.pod;h=49b8fc2f066180430303db826f951e144fe4bf59;hb=fac8e2f98375e415e6ca946e213cf849c7f9ffb5;hp=a4e87c54d10bc15bfa53440464c8a49d70cc0d88;hpb=d828f3eccac8dbad7bfc14812e406377669baaa4;p=rrdtool.git
diff --git a/doc/rrdfetch.pod b/doc/rrdfetch.pod
index a4e87c5..49b8fc2 100644
--- a/doc/rrdfetch.pod
+++ b/doc/rrdfetch.pod
@@ -1,62 +1,77 @@
=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]>
+S<[B<--daemon> 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 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.
+
+=item B<--daemon> I
+
+Address of the L daemon. If specified, a C command is sent
+to the server before reading the RRD files. This allows B to return
+fresh data even if the daemon is configured to cache values for a long time.
+For a list of accepted formats, see the B<-l> option in the L manual.
+
+ rrdtool fetch --daemon unix:/var/run/rrdcached.sock /var/lib/rrd/foo.rrd AVERAGE
+
+Please note that due to thread-safety reasons, the time specified with B<-s>
+and B<-e> cannot use the complex forms described in
+L<"AT-STYLE TIME SPECIFICATION">. The only accepted arguments are "simple
+integers". Positive values are interpreted as seconds since epoch, negative
+values (and zero) are interpreted as relative to I. So "1272535035" refers
+to "09:57:15 (UCT), April 29th 2010" and "-3600" means "one hour ago".
=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 +81,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 +105,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:
- 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