make --disable-perl work
[rrdtool.git] / doc / rrdfetch.pod
1 =head1 NAME
2
3 rrdtool fetch - fetch data from an RRD.
4
5 =for html <div align="right"><a href="rrdfetch.pdf">PDF</a> version.</div>
6
7 =head1 SYNOPSIS
8
9 B<rrdtool> B<fetch> I<filename> I<CF> 
10 S<[B<--resolution>|B<-r> I<resolution>]> 
11 S<[B<--start>|B<-s> I<start>]> 
12 S<[B<--end>|B<-e> I<end>]> 
13
14 =head1 DESCRIPTION
15
16 The B<fetch> function is normally used internally by the graph function,
17 to get data from B<RRD>s. B<fetch> will analyze the B<RRD> and
18 will try to retrieve the data in the resolution requested.
19 The data fetched is printed to stdout. I<*UNKNOWN*> data is often
20 represented by the string "NaN" depending on your OS's printf
21 function.
22
23 =over 8
24
25 =item I<filename> 
26
27 the name of the B<RRD> you want to fetch the data from.
28
29 =item I<CF> 
30
31 which consolidation function should have been applied to the data you
32 want to fetch? (AVERAGE,MIN,MAX,LAST)
33
34 =item B<--resolution>|B<-r> I<resolution> (default is the highest resolution)
35
36 what interval should the values have (seconds per value). B<rrdfetch> will try
37 to match your request, but it will return data even if no absolute
38 match is possible. B<NB.> See note below.
39
40 =item B<--start>|B<-s> I<start> (default end-1day)
41
42 when should the data begin. A time in seconds since epoch (1970-01-01)
43 is required. Negative numbers are relative to the current time. By default
44 one day worth of data will be fetched. See also AT-STYLE TIME SPECIFICATION
45 section for a detailed explanation on  ways to specify start time.
46
47 =item B<--end>|B<-e> I<end> (default now)
48
49 when should the data end. Time in seconds since epoch. See also
50 AT-STYLE TIME SPECIFICATION section for a detailed explanation of how to specify
51 end time.
52
53 =back
54
55 =head2 RESOLUTION INTERVAL
56
57 In order to get RRDtool to fetch anything other than the finest resolution RRA 
58 B<both> the start and end time must be specified on boundaries that are 
59 multiples of the wanted resolution. Consider the following example:
60
61  rrdtool create subdata.rrd -s 10 DS:ds0:GAUGE:300:0:U \
62   RRA:AVERAGE:0.5:30:3600 \
63   RRA:AVERAGE:0.5:90:1200 \
64   RRA:AVERAGE:0.5:360:1200 \
65   RRA:MAX:0.5:360:1200 \
66   RRA:AVERAGE:0.5:8640:600 \
67   RRA:MAX:0.5:8640:600
68
69 This RRD collects data every 10 seconds and stores its averages over 5 minutes, 
70 15 minutes, 1 hour and 1 day as well as the maxima for 1 hour and 1 day.
71
72 Consider now that you want too fetch the 15 minute average data for last hour. 
73 So you might try
74
75  rrdtool fetch subdata.rrd AVERAGE -r 900 -s -1h
76
77 However, this will almost always result in a time series that is B<NOT> in the 15 
78 minute RRA. Therefore the highest resolution RRA, i.e. 5 minute averages, will 
79 be chosen which, in this case, is not what you want.
80
81 Hence, make sure that
82
83 =over 3
84
85 =item 1.
86
87 both start and end time are a multiple of 900
88
89 =item 2.
90
91 both start and end time are within the wanted RRA
92
93 =back
94
95 So, if time now is called "t",
96
97  do end time == int(t/900)*900,
98  start time == end time -1hour, resolution == 900.
99
100 In e.g. bash this could look as:
101
102  TIME=$(date +%s); RRDRES=900; rrdtool fetch subdata.rrd AVERAGE -r $RRDRES \
103  -e $(echo $(($TIME/$RRDRES*$RRDRES))) -s e-1h
104
105 Or in Perl:
106
107  perl -e '$ctime = time; $rrdres = 900; system "rrdtool fetch subdata.rrd AVERAGE \
108  -r $rrdres -e @{[int($ctime/$rrdres)*$rrdres]} -s e-1h"'
109
110
111 =head2 AT-STYLE TIME SPECIFICATION
112
113 Apart from the traditional I<Seconds since epoch>, RRDtool does also
114 understand at-style time specification.  The specification is called
115 "at-style" after Unix command at(1) that has moderately complex ways
116 to specify time to run your job at.  The at-style specification
117 consists of two parts: B<TIME REFERENCE> specification and B<TIME
118 OFFSET> specification.
119
120 =head2 TIME REFERENCE SPECIFICATION
121
122 Time reference specification is used, well,... to establish a reference
123 moment in time (for time offset to be applied to). When present,
124 it should come first, when omitted, it defaults to B<now>. On its own part,
125 time reference consists of I<time-of-day> reference (which should come
126 first, if present) and I<day> reference.
127
128 I<Time-of-day> can be specified as B<HH:MM>, B<HH.MM>,
129 or just B<HH>, you can suffix it with B<am> or B<pm> or use
130 24-hours clock. The few special times of day are understood as well,
131 these include B<midnight> (00:00), B<noon> (12:00) and British
132 B<teatime> (16:00).
133
134 The I<day> can be specified as I<month-name> I<day-of-the-month>
135 and optional 2- or 4-digit I<year> number (e.g. March 8 1999).
136 Alternatively, you can use I<day-of-week-name> (e.g. Monday),
137 or one of the words: B<yesterday>, B<today>, B<tomorrow>.
138 You can also specify I<day> as a full date in several numerical formats;
139 these include: B<MM/DD/[YY]YY>, B<DD.MM.[YY]YY>, B<YYYYMMDD>.
140
141 I<NOTE1>: this is different from the original at(1) behavior,
142 which interprets a single-number date as MMDD[YY]YY.
143
144 I<NOTE2>: if you specify I<day> this way, the I<time-of-day> is REQUIRED
145 to be present.
146
147 Finally, you can use words B<now>, B<start>, or B<end> as your time
148 reference. B<Now> refers to the current moment (and is also a default
149 time reference). B<Start> (B<end>) can be used to specify time
150 relative to the start (end) time for those tools that use these
151 categories (B<rrdfetch>, L<rrdgraph>).
152
153 Month and weekday names can be used in their naturally abbreviated form
154 (e.g., Dec for December, Sun for Sunday, etc.). The words B<now>,
155 B<start>, B<end> can be abbreviated to B<n>, B<s>, B<e>.
156
157 =head2 TIME OFFSET SPECIFICATION
158
159 Time offset specification is used to add (or subtract) certain time
160 interval to (from) the time reference moment. It consists of I<sign>
161 (S<B<+> or B<->>) and I<amount>. The following time units can be used
162 to specify the I<amount>: B<years>, B<months>, B<weeks>, B<days>,
163 B<hours>, B<minutes>, B<seconds>, these can be used in singular
164 or plural form, and abbreviated naturally or to a single letter
165 (e.g. +3days, -1wk, -3y). Several time units can be combined
166 together (e.g., -5mon1w2d), as well as several time offsets can be
167 concatenated (e.g., -5h45min = -5h-45min = -6h+15min = -7h+1h30m-15min, etc.)
168
169 I<NOTE3>: If you specify time offset in days, weeks, months, or years,
170 you will end with the time offset that may vary depending on you time
171 reference, because all those time units have no single well defined
172 time interval value (S<1 year> contains either 365 or 366 days, S<1 month>
173 is 28 to 31 days long, and even S<1 day> may be not equal to 24 hours
174 twice a year, when DST-related clock adjustments take place).
175 To cope with this, when you use days, weeks, months, or years
176 as your time offset units your time reference date is adjusted
177 accordingly without taking too much further effort to ensure anything
178 about it (in the hope that mktime(3) will take care of this later).
179 This may lead to some surprising (or even invalid!) results,
180 e.g. S<'May 31 -1month'> = S<'Apr 31'> (meaningless) = S<'May 1'>
181 (after mktime(3) normalization); in the EET timezone
182 '3:30am Mar 29 1999 -1 day' yields '3:30am Mar 28 1999' (Sunday)
183 which is invalid time/date combination (because of 3am -> 4am DST
184 forward clock adjustment, see the below example).
185 On the other hand, hours, minutes, and seconds are well defined time
186 intervals, and these are guaranteed to always produce time offsets
187 exactly as specified (e.g. for EET timezone, S<'8:00 Mar 27 1999 +2 days'> =
188 S<'8:00 Mar 29 1999'>, but since there is 1-hour DST forward clock adjustment
189 takes place around S<3:00 Mar 28 1999>, the actual time interval between
190 S<8:00 Mar 27 1999> and S<8:00 Mar 29 1999> equals 47 hours; on the other hand,
191 S<'8:00 Mar 27 1999 +48 hours'> = S<'9:00 Mar 29 1999'>, as expected)
192
193 I<NOTE4>: The single-letter abbreviation for both B<months> and B<minutes>
194 is B<m>. To disambiguate, the parser tries to read your S<mind :)>
195 by applying the following two heuristics:
196
197 =over 3
198
199 =item 1
200
201 If B<m> is used in context of (i.e. right after the) years,
202 months, weeks, or days it is assumed to mean B<months>, while
203 in the context of hours, minutes, and seconds it means minutes.
204 (e.g., in -1y6m or +3w1m B<m> means B<months>, while in
205 -3h20m or +5s2m B<m> means B<minutes>)
206
207 =item 2
208
209 Out of context (i.e. right after the B<+> or B<-> sign) the
210 meaning of B<m> is guessed from the number it directly follows.
211 Currently, if the number absolute value is below 25 it is assumed
212 that B<m> means B<months>, otherwise it is treated as B<minutes>.
213 (e.g., -25m == -25 minutes, while +24m == +24 months)
214
215 =back
216
217 I<Final NOTES>: Time specification is case-insensitive.
218 Whitespace can be inserted freely or omitted altogether,
219 there are, however, cases when whitespace is required
220 (e.g., S<'midnight Thu'>). In this case you should either quote the
221 whole phrase to prevent it from being taken apart by your shell or use
222 '_' (underscore) or ',' (comma) which also count as whitespace
223 (e.g., midnight_Thu or midnight,Thu)
224
225
226 =head2 TIME SPECIFICATION EXAMPLES
227
228 I<Oct 12> -- October 12 this year
229
230 I<-1month> or I<-1m> -- current time of day, only a month before
231 (may yield surprises, see the NOTE3 above)
232
233 I<noon yesterday -3hours> -- yesterday morning; can be put also as I<9am-1day>
234
235 I<23:59 31.12.1999> -- 1 minute to the year 2000
236
237 I<12/31/99 11:59pm> -- 1 minute to the year 2000 for imperialists
238
239 I<12am 01/01/01> -- start of the new millennium
240
241 I<end-3weeks> or I<e-3w> -- 3 weeks before end time
242 (may be used as start time specification)
243
244 I<start+6hours> or I<s+6h> -- 6 hours after start time
245 (may be used as end time specification)
246
247 I<931225537> -- 18:45  July 5th, 1999
248 (yes, seconds since 1970 are valid as well)
249
250 I<19970703 12:45> -- 12:45  July 3th, 1997
251 (my favorite, and its even got an ISO number (8601))
252
253 =head1 AUTHOR
254
255 Tobias Oetiker <oetiker@ee.ethz.ch>
256