![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
diff --git a/doc/rrdfetch.txt b/doc/rrdfetch.txt
index 8717403342736e385d4dd2cdc07eb111cd91fa2d..b6f3f2c51c9ff7102faf3660d7ff4d20560bd659 100644 (file)
--- a/doc/rrdfetch.txt
+++ b/doc/rrdfetch.txt
D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN
The f\bfe\bet\btc\bch\bh function is normally used internally by the graph function to
get data from R\bRR\bRD\bDs. f\bfe\bet\btc\bch\bh will analyze the R\bRR\bRD\bD and try to retrieve the
- data in the resolution requested. The data fetched is printed to std-
- out. _\b*_\bU_\bN_\bK_\bN_\bO_\bW_\bN_\b* data is often represented by the string "NaN" depending
- on your OS's printf function.
+ data in the resolution requested. The data fetched is printed to
+ stdout. _\b*_\bU_\bN_\bK_\bN_\bO_\bW_\bN_\b* data is often represented by the string "NaN"
+ depending on your OS's printf function.
_\bf_\bi_\bl_\be_\bn_\ba_\bm_\be
the name of the R\bRR\bRD\bD you want to fetch the data from.
how to specify the end time.
-\b--\b-d\bda\bae\bem\bmo\bon\bn _\ba_\bd_\bd_\br_\be_\bs_\bs
- Address of the rrdcached daemon. If specified, a "flush" com-
- mand is sent to the server before reading the RRD files. This
- allows r\brr\brd\bdt\bto\boo\bol\bl to return fresh data even if the daemon is con-
- figured to cache values for a long time. For a list of
+ Address of the rrdcached daemon. If specified, a "flush"
+ command is sent to the server before reading the RRD files.
+ This allows r\brr\brd\bdt\bto\boo\bol\bl 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\bl option in the rrdcached manual.
rrdtool fetch --daemon unix:/var/run/rrdcached.sock /var/lib/rrd/foo.rrd AVERAGE
- R\bRE\bES\bSO\bOL\bLU\bUT\bTI\bIO\bON\bN I\bIN\bNT\bTE\bER\bRV\bVA\bAL\bL
-
- In order to get RRDtool to fetch anything other than the finest resolu-
- tion RRA b\bbo\bot\bth\bh the start and end time must be specified on boundaries
- that are multiples of the desired resolution. Consider the following
- example:
+ R\bRE\bES\bSO\bOL\bLU\bUT\bTI\bIO\bON\bN I\bIN\bNT\bTE\bER\bRV\bVA\bAL\bL
+ In order to get RRDtool to fetch anything other than the finest
+ resolution RRA b\bbo\bot\bth\bh 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 \
system "rrdtool fetch subdata.rrd AVERAGE \
-r $rrdres -e @{[int($ctime/$rrdres)*$rrdres]} -s e-1h"'
- A\bAT\bT-\b-S\bST\bTY\bYL\bLE\bE T\bTI\bIM\bME\bE S\bSP\bPE\bEC\bCI\bIF\bFI\bIC\bCA\bAT\bTI\bIO\bON\bN
-
+ A\bAT\bT-\b-S\bST\bTY\bYL\bLE\bE T\bTI\bIM\bME\bE S\bSP\bPE\bEC\bCI\bIF\bFI\bIC\bCA\bAT\bTI\bIO\bON\bN
Apart from the traditional _\bS_\be_\bc_\bo_\bn_\bd_\bs _\bs_\bi_\bn_\bc_\be _\be_\bp_\bo_\bc_\bh, RRDtool does also
understand at-style time specification. The specification is called
"at-style" after the Unix command _\ba_\bt(1) that has moderately complex
ways to specify time to run your job at a certain date and time. The
- at-style specification consists of two parts: the T\bTI\bIM\bME\bE R\bRE\bEF\bFE\bER\bRE\bEN\bNC\bCE\bE speci-
- fication and the T\bTI\bIM\bME\bE O\bOF\bFF\bFS\bSE\bET\bT specification.
-
- T\bTI\bIM\bME\bE R\bRE\bEF\bFE\bER\bRE\bEN\bNC\bCE\bE S\bSP\bPE\bEC\bCI\bIF\bFI\bIC\bCA\bAT\bTI\bIO\bON\bN
+ at-style specification consists of two parts: the T\bTI\bIM\bME\bE R\bRE\bEF\bFE\bER\bRE\bEN\bNC\bCE\bE
+ specification and the T\bTI\bIM\bME\bE O\bOF\bFF\bFS\bSE\bET\bT specification.
- The time reference specification is used, well, to establish a refer-
- ence moment in time (to which the time offset is then applied to). When
- present, it should come first, when omitted, it defaults to n\bno\bow\bw. On its
- own part, time reference consists of a _\bt_\bi_\bm_\be_\b-_\bo_\bf_\b-_\bd_\ba_\by reference (which
- should come first, if present) and a _\bd_\ba_\by reference.
+ T\bTI\bIM\bME\bE R\bRE\bEF\bFE\bER\bRE\bEN\bNC\bCE\bE S\bSP\bPE\bEC\bCI\bIF\bFI\bIC\bCA\bAT\bTI\bIO\bON\bN
+ The time reference specification is used, well, to establish a
+ reference moment in time (to which the time offset is then applied to).
+ When present, it should come first, when omitted, it defaults to n\bno\bow\bw.
+ On its own part, time reference consists of a _\bt_\bi_\bm_\be_\b-_\bo_\bf_\b-_\bd_\ba_\by reference
+ (which should come first, if present) and a _\bd_\ba_\by reference.
The _\bt_\bi_\bm_\be_\b-_\bo_\bf_\b-_\bd_\ba_\by can be specified as H\bHH\bH:\b:M\bMM\bM, H\bHH\bH.\b.M\bMM\bM, or just H\bHH\bH. You can
suffix it with a\bam\bm or p\bpm\bm or use 24-hours clock. Some special times of
_\bN_\bO_\bT_\bE_\b2: if you specify the _\bd_\ba_\by in this way, the _\bt_\bi_\bm_\be_\b-_\bo_\bf_\b-_\bd_\ba_\by is REQUIRED
as well.
- Finally, you can use the words n\bno\bow\bw, s\bst\bta\bar\brt\bt, or e\ben\bnd\bd as your time refer-
- ence. N\bNo\bow\bw refers to the current moment (and is also the default time
- reference). S\bSt\bta\bar\brt\bt (e\ben\bnd\bd) can be used to specify a time relative to the
- start (end) time for those tools that use these categories (r\brr\brd\bdf\bfe\bet\btc\bch\bh,
- rrdgraph).
+ Finally, you can use the words n\bno\bow\bw, s\bst\bta\bar\brt\bt, or e\ben\bnd\bd as your time
+ reference. N\bNo\bow\bw refers to the current moment (and is also the default
+ time reference). S\bSt\bta\bar\brt\bt (e\ben\bnd\bd) can be used to specify a time relative to
+ the start (end) time for those tools that use these categories
+ (r\brr\brd\bdf\bfe\bet\btc\bch\bh, rrdgraph).
- Month and day of the week names can be used in their naturally abbrevi-
- ated form (e.g., Dec for December, Sun for Sunday, etc.). The words
- n\bno\bow\bw, s\bst\bta\bar\brt\bt, e\ben\bnd\bd can be abbreviated as n\bn, s\bs, e\be.
-
- T\bTI\bIM\bME\bE O\bOF\bFF\bFS\bSE\bET\bT S\bSP\bPE\bEC\bCI\bIF\bFI\bIC\bCA\bAT\bTI\bIO\bON\bN
+ Month and day of the week names can be used in their naturally
+ abbreviated form (e.g., Dec for December, Sun for Sunday, etc.). The
+ words n\bno\bow\bw, s\bst\bta\bar\brt\bt, e\ben\bnd\bd can be abbreviated as n\bn, s\bs, e\be.
+ T\bTI\bIM\bME\bE O\bOF\bFF\bFS\bSE\bET\bT S\bSP\bPE\bEC\bCI\bIF\bFI\bIC\bCA\bAT\bTI\bIO\bON\bN
The time offset specification is used to add/subtract certain time
intervals to/from the time reference moment. It consists of a _\bs_\bi_\bg_\bn
(+\b+ or -\b-) and an _\ba_\bm_\bo_\bu_\bn_\bt. The following time units can be used to specify
= -5h-45min = -6h+15min = -7h+1h30m-15min, etc.)
_\bN_\bO_\bT_\bE_\b3: If you specify time offset in days, weeks, months, or years, you
- will end with the time offset that may vary depending on your time ref-
- erence, because all those time units have no single well defined time
- interval value (1 year contains either 365 or 366 days, 1 month is 28
- to 31 days long, and even 1 day may be not equal to 24 hours twice a
+ will end with the time offset that may vary depending on your time
+ reference, because all those time units have no single well defined
+ time interval value (1 year contains either 365 or 366 days, 1 month is
+ 28 to 31 days long, and even 1 day may be not equal to 24 hours twice a
year, when DST-related clock adjustments take place). To cope with
this, when you use days, weeks, months, or years as your time offset
units your time reference date is adjusted accordingly without too much
invalid time/date combination (because of 3am -> 4am DST forward clock
adjustment, see the below example).
- In contrast, hours, minutes, and seconds are well defined time inter-
- vals, and these are guaranteed to always produce time offsets exactly
- as specified (e.g. for EET timezone, '8:00 Mar 27 1999 +2 days' =
- '8:00 Mar 29 1999', but since there is 1-hour DST forward clock adjust-
- ment that occurs around 3:00 Mar 28 1999, the actual time interval
- between 8:00 Mar 27 1999 and 8:00 Mar 29 1999 equals 47 hours; on the
- other hand, '8:00 Mar 27 1999 +48 hours' = '9:00 Mar 29 1999', as
- expected)
+ In contrast, hours, minutes, and seconds are well defined time
+ intervals, and these are guaranteed to always produce time offsets
+ exactly as specified (e.g. for EET timezone, '8:00 Mar 27 1999 +2 days'
+ = '8:00 Mar 29 1999', but since there is 1-hour DST forward clock
+ adjustment that occurs around 3:00 Mar 28 1999, the actual time
+ interval between 8:00 Mar 27 1999 and 8:00 Mar 29 1999 equals 47 hours;
+ on the other hand, '8:00 Mar 27 1999 +48 hours' = '9:00 Mar 29 1999',
+ as expected)
_\bN_\bO_\bT_\bE_\b4: The single-letter abbreviation for both m\bmo\bon\bnt\bth\bhs\bs and m\bmi\bin\bnu\but\bte\bes\bs is m\bm.
To disambiguate them, the parser tries to read your mind :) by applying
the following two heuristics:
- 1 If m\bm is used in context of (i.e. right after the) years, months,
+ 1. If m\bm is used in context of (i.e. right after the) years, months,
weeks, or days it is assumed to mean m\bmo\bon\bnt\bth\bhs\bs, while in the context of
hours, minutes, and seconds it means minutes. (e.g., in -1y6m or
+3w1m m\bm is interpreted as m\bmo\bon\bnt\bth\bhs\bs, while in -3h20m or +5s2m m\bm the
parser decides for m\bmi\bin\bnu\but\bte\bes\bs).
- 2 Out of context (i.e. right after the +\b+ or -\b- sign) the meaning of m\bm
+ 2. Out of context (i.e. right after the +\b+ or -\b- sign) the meaning of m\bm
is guessed from the number it directly follows. Currently, if the
number's absolute value is below 25 it is assumed that m\bm means
- m\bmo\bon\bnt\bth\bhs\bs, otherwise it is treated as m\bmi\bin\bnu\but\bte\bes\bs. (e.g., -25m == -25 min-
- utes, while +24m == +24 months)
+ m\bmo\bon\bnt\bth\bhs\bs, otherwise it is treated as m\bmi\bin\bnu\but\bte\bes\bs. (e.g., -25m == -25
+ minutes, while +24m == +24 months)
_\bF_\bi_\bn_\ba_\bl _\bN_\bO_\bT_\bE_\bS: Time specification is case-insensitive. Whitespace can be
inserted freely or omitted altogether. There are, however, cases when
your shell or use '_' (underscore) or ',' (comma) which also count as
whitespace (e.g., midnight_Thu or midnight,Thu).
- T\bTI\bIM\bME\bE S\bSP\bPE\bEC\bCI\bIF\bFI\bIC\bCA\bAT\bTI\bIO\bON\bN E\bEX\bXA\bAM\bMP\bPL\bLE\bES\bS
-
+ T\bTI\bIM\bME\bE S\bSP\bPE\bEC\bCI\bIF\bFI\bIC\bCA\bAT\bTI\bIO\bON\bN E\bEX\bXA\bAM\bMP\bPL\bLE\bES\bS
_\bO_\bc_\bt _\b1_\b2 -- October 12 this year
_\b-_\b1_\bm_\bo_\bn_\bt_\bh or _\b-_\b1_\bm -- current time of day, only a month before (may yield
-1.3.99909060808 2008-09-25 RRDFETCH(1)
+1.3.999 2009-06-09 RRDFETCH(1)