user/rrdtool/doc/rrdfetch.txt

   1 RRDFETCH(1)                  rrdtool                  RRDFETCH(1)
   2
   3
   4
   5 N\bNA\bAM\bME\bE
   6        rrdfetch - Fetch data from an RRD.
   7
   8 S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS
   9        r\brr\brd\bdt\bto\boo\bol\bl f\bfe\bet\btc\bch\bh _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be _\bC_\bF [-\b--\b-r\bre\bes\bso\bol\blu\but\bti\bio\bon\bn|-\b-r\br _\br_\be_\bs_\bo_\bl_\bu_\bt_\bi_\bo_\bn]
  10        [-\b--\b-s\bst\bta\bar\brt\bt|-\b-s\bs _\bs_\bt_\ba_\br_\bt] [-\b--\b-e\ben\bnd\bd|-\b-e\be _\be_\bn_\bd]
  11
  12 D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN
  13        The f\bfe\bet\btc\bch\bh function is normally used internally by the
  14        graph function to get data from R\bRR\bRD\bDs. f\bfe\bet\btc\bch\bh will analyze
  15        the R\bRR\bRD\bD and try to retrieve the data in the resolution
  16        requested.  The data fetched is printed to stdout.
  17        _\b*_\bU_\bN_\bK_\bN_\bO_\bW_\bN_\b* data is often represented by the string "NaN"
  18        depending on your OS's printf function.
  19
  20        _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be
  21                the name of the R\bRR\bRD\bD you want to fetch the data
  22                from.
  23
  24        _\bC_\bF      the consolidation function that is applied to the
  25                data you want to fetch (AVERAGE,MIN,MAX,LAST)
  26
  27        -\b--\b-r\bre\bes\bso\bol\blu\but\bti\bio\bon\bn|-\b-r\br _\br_\be_\bs_\bo_\bl_\bu_\bt_\bi_\bo_\bn (default is the highest resolu-
  28        tion)
  29                the interval you want the values to have (seconds
  30                per value). r\brr\brd\bdf\bfe\bet\btc\bch\bh will try to match your
  31                request, but it will return data even if no abso-
  32                lute match is possible. N\bNB\bB.\b. See note below.
  33
  34        -\b--\b-s\bst\bta\bar\brt\bt|-\b-s\bs _\bs_\bt_\ba_\br_\bt (default end-1day)
  35                start of the time series. A time in seconds since
  36                epoch (1970-01-01) is required. Negative numbers
  37                are relative to the current time. By default, one
  38                day worth of data will be fetched. See also AT-
  39                STYLE TIME SPECIFICATION section for a detailed
  40                explanation on  ways to specify the start time.
  41
  42        -\b--\b-e\ben\bnd\bd|-\b-e\be _\be_\bn_\bd (default now)
  43                the end of the time series in seconds since epoch.
  44                See also AT-STYLE TIME SPECIFICATION section for a
  45                detailed explanation of how to specify the end
  46                time.
  47
  48        R\bRE\bES\bSO\bOL\bLU\bUT\bTI\bIO\bON\bN I\bIN\bNT\bTE\bER\bRV\bVA\bAL\bL
  49
  50        In order to get RRDtool to fetch anything other than the
  51        finest resolution RRA b\bbo\bot\bth\bh the start and end time must be
  52        specified on boundaries that are multiples of the desired
  53        resolution. Consider the following example:
  54
  55         rrdtool create subdata.rrd -s 10 DS:ds0:GAUGE:300:0:U \
  56          RRA:AVERAGE:0.5:30:3600 \
  57          RRA:AVERAGE:0.5:90:1200 \
  58          RRA:AVERAGE:0.5:360:1200 \
  59          RRA:MAX:0.5:360:1200 \
  60          RRA:AVERAGE:0.5:8640:600 \
  61          RRA:MAX:0.5:8640:600
  62
  63        This RRD collects data every 10 seconds and stores its
  64        averages over 5 minutes, 15 minutes, 1 hour, and 1 day, as
  65        well as the maxima for 1 hour and 1 day.
  66
  67        Consider now that you want to fetch the 15 minute average
  68        data for the last hour.  You might try
  69
  70         rrdtool fetch subdata.rrd AVERAGE -r 900 -s -1h
  71
  72        However, this will almost always result in a time series
  73        that is N\bNO\bOT\bT in the 15 minute RRA. Therefore, the highest
  74        resolution RRA, i.e. 5 minute averages, will be chosen
  75        which in this case is not what you want.
  76
  77        Hence, make sure that
  78
  79        1. both start and end time are a multiple of 900
  80
  81        2. both start and end time are within the desired RRA
  82
  83        So, if time now is called "t", do
  84
  85         end time == int(t/900)*900,
  86         start time == end time - 1hour,
  87         resolution == 900.
  88
  89        Using the bash shell, this could look be:
  90
  91         TIME=$(date +%s)
  92         RRDRES=900
  93         rrdtool fetch subdata.rrd AVERAGE -r $RRDRES \
  94            -e $(echo $(($TIME/$RRDRES*$RRDRES))) -s e-1h
  95
  96        Or in Perl:
  97
  98         perl -e '$ctime = time; $rrdres = 900; \
  99                  system "rrdtool fetch subdata.rrd AVERAGE \
 100                          -r $rrdres -e @{[int($ctime/$rrdres)*$rrdres]} -s e-1h"'
 101
 102        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
 103
 104        Apart from the traditional _\bS_\be_\bc_\bo_\bn_\bd_\bs _\bs_\bi_\bn_\bc_\be _\be_\bp_\bo_\bc_\bh, RRDtool
 105        does also understand at-style time specification. The
 106        specification is called "at-style" after the Unix command
 107        _\ba_\bt(1) that has moderately complex ways to specify time to
 108        run your job at a certain date and time. The at-style
 109        specification consists of two parts: the T\bTI\bIM\bME\bE R\bRE\bEF\bFE\bER\bRE\bEN\bNC\bCE\bE
 110        specification and the T\bTI\bIM\bME\bE O\bOF\bFF\bFS\bSE\bET\bT specification.
 111
 112        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
 113
 114        The time reference specification is used, well, to estab-
 115        lish a reference moment in time (to which the time offset
 116        is then applied to). When present, it should come first,
 117        when omitted, it defaults to n\bno\bow\bw. On its own part, time
 118        reference consists of a _\bt_\bi_\bm_\be_\b-_\bo_\bf_\b-_\bd_\ba_\by reference (which
 119        should come first, if present) and a _\bd_\ba_\by reference.
 120
 121        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
 122        H\bHH\bH. You can suffix it with a\bam\bm or p\bpm\bm or use 24-hours clock.
 123        Some special times of day are understood as well, includ-
 124        ing m\bmi\bid\bdn\bni\big\bgh\bht\bt (00:00), n\bno\boo\bon\bn (12:00) and British t\bte\bea\bat\bti\bim\bme\be
 125        (16:00).
 126
 127        The _\bd_\ba_\by can be specified as _\bm_\bo_\bn_\bt_\bh_\b-_\bn_\ba_\bm_\be _\bd_\ba_\by_\b-_\bo_\bf_\b-_\bt_\bh_\be_\b-_\bm_\bo_\bn_\bt_\bh
 128        and optional a 2- or 4-digit _\by_\be_\ba_\br number (e.g. March 8
 129        1999). Alternatively, you can use _\bd_\ba_\by_\b-_\bo_\bf_\b-_\bw_\be_\be_\bk_\b-_\bn_\ba_\bm_\be (e.g.
 130        Monday), or one of the words: y\bye\bes\bst\bte\ber\brd\bda\bay\by, t\bto\bod\bda\bay\by, t\bto\bom\bmo\bor\brr\bro\bow\bw.
 131        You can also specify the _\bd_\ba_\by as a full date in several
 132        numerical formats, including M\bMM\bM/\b/D\bDD\bD/\b/[\b[Y\bYY\bY]\b]Y\bYY\bY, D\bDD\bD.\b.M\bMM\bM.\b.[\b[Y\bYY\bY]\b]Y\bYY\bY,
 133        or Y\bYY\bYY\bYY\bYM\bMM\bMD\bDD\bD.
 134
 135        _\bN_\bO_\bT_\bE_\b1: this is different from the original _\ba_\bt(1) behavior,
 136        where a single-number date is interpreted as MMDD[YY]YY.
 137
 138        _\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
 139        is REQUIRED as well.
 140
 141        Finally, you can use the words n\bno\bow\bw, s\bst\bta\bar\brt\bt, or e\ben\bnd\bd as your
 142        time reference. N\bNo\bow\bw refers to the current moment (and is
 143        also the default time reference). S\bSt\bta\bar\brt\bt (e\ben\bnd\bd) can be used
 144        to specify a time relative to the start (end) time for
 145        those tools that use these categories (r\brr\brd\bdf\bfe\bet\btc\bch\bh, rrd-
 146        graph).
 147
 148        Month and day of the week names can be used in their natu-
 149        rally abbreviated form (e.g., Dec for December, Sun for
 150        Sunday, etc.). The words n\bno\bow\bw, s\bst\bta\bar\brt\bt, e\ben\bnd\bd can be abbrevi-
 151        ated as n\bn, s\bs, e\be.
 152
 153        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
 154
 155        The time offset specification is used to add/subtract cer-
 156        tain time intervals to/from the time reference moment. It
 157        consists of a _\bs_\bi_\bg_\bn (+\b+ or -\b-) and an _\ba_\bm_\bo_\bu_\bn_\bt. The following
 158        time units can be used to specify the _\ba_\bm_\bo_\bu_\bn_\bt: y\bye\bea\bar\brs\bs,
 159        m\bmo\bon\bnt\bth\bhs\bs, w\bwe\bee\bek\bks\bs, d\bda\bay\bys\bs, h\bho\bou\bur\brs\bs, m\bmi\bin\bnu\but\bte\bes\bs, or s\bse\bec\bco\bon\bnd\bds\bs. These
 160        units can be used in singular or plural form, and abbrevi-
 161        ated naturally or to a single letter (e.g. +3days, -1wk,
 162        -3y). Several time units can be combined (e.g., -5mon1w2d)
 163        or concatenated (e.g., -5h45min = -5h-45min = -6h+15min =
 164        -7h+1h30m-15min, etc.)
 165
 166        _\bN_\bO_\bT_\bE_\b3: If you specify time offset in days, weeks, months,
 167        or years, you will end with the time offset that may vary
 168        depending on your time reference, because all those time
 169        units have no single well defined time interval value
 170        (1 year contains either 365 or 366 days, 1 month is 28 to
 171        31 days long, and even 1 day may be not equal to 24 hours
 172        twice a year, when DST-related clock adjustments take
 173        place).  To cope with this, when you use days, weeks,
 174        months, or years as your time offset units your time ref-
 175        erence date is adjusted accordingly without too much fur-
 176        ther effort to ensure anything about it (in the hope that
 177        _\bm_\bk_\bt_\bi_\bm_\be(3) will take care of this later).  This may lead to
 178        some surprising (or even invalid!) results, e.g.
 179        'May 31 -1month' = 'Apr 31' (meaningless) = 'May 1' (after
 180        _\bm_\bk_\bt_\bi_\bm_\be(3) normalization); in the EET timezone '3:30am Mar
 181        29 1999 -1 day' yields '3:30am Mar 28 1999' (Sunday) which
 182        is an invalid time/date combination (because of 3am -> 4am
 183        DST forward clock adjustment, see the below example).
 184
 185        In contrast, hours, minutes, and seconds are well defined
 186        time intervals, and these are guaranteed to always produce
 187        time offsets exactly as specified (e.g. for EET timezone,
 188        '8:00 Mar 27 1999 +2 days' = '8:00 Mar 29 1999', but since
 189        there is 1-hour DST forward clock adjustment that occurs
 190        around 3:00 Mar 28 1999, the actual time interval between
 191        8:00 Mar 27 1999 and 8:00 Mar 29 1999 equals 47 hours; on
 192        the other hand, '8:00 Mar 27 1999 +48 hours' =
 193        '9:00 Mar 29 1999', as expected)
 194
 195        _\bN_\bO_\bT_\bE_\b4: The single-letter abbreviation for both m\bmo\bon\bnt\bth\bhs\bs and
 196        m\bmi\bin\bnu\but\bte\bes\bs is m\bm. To disambiguate them, the parser tries to
 197        read your mind :) by applying the following two heuris-
 198        tics:
 199
 200        1  If m\bm is used in context of (i.e. right after the)
 201           years, months, weeks, or days it is assumed to mean
 202           m\bmo\bon\bnt\bth\bhs\bs, while in the context of hours, minutes, and
 203           seconds it means minutes.  (e.g., in -1y6m or +3w1m m\bm
 204           is interpreted as m\bmo\bon\bnt\bth\bhs\bs, while in -3h20m or +5s2m m\bm
 205           the parser decides for m\bmi\bin\bnu\but\bte\bes\bs).
 206
 207        2  Out of context (i.e. right after the +\b+ or -\b- sign) the
 208           meaning of m\bm is guessed from the number it directly
 209           follows.  Currently, if the number's absolute value is
 210           below 25 it is assumed that m\bm means m\bmo\bon\bnt\bth\bhs\bs, otherwise
 211           it is treated as m\bmi\bin\bnu\but\bte\bes\bs.  (e.g., -25m == -25 minutes,
 212           while +24m == +24 months)
 213
 214        _\bF_\bi_\bn_\ba_\bl _\bN_\bO_\bT_\bE_\bS: Time specification is case-insensitive.
 215        Whitespace can be inserted freely or omitted altogether.
 216        There are, however, cases when whitespace is required
 217        (e.g., 'midnight Thu'). In this case you should either
 218        quote the whole phrase to prevent it from being taken
 219        apart by your shell or use '_' (underscore) or ',' (comma)
 220        which also count as whitespace (e.g., midnight_Thu or mid-
 221        night,Thu).
 222
 223        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
 224
 225        _\bO_\bc_\bt _\b1_\b2 -- October 12 this year
 226
 227        _\b-_\b1_\bm_\bo_\bn_\bt_\bh or _\b-_\b1_\bm -- current time of day, only a month before
 228        (may yield surprises, see NOTE3 above).
 229
 230        _\bn_\bo_\bo_\bn _\by_\be_\bs_\bt_\be_\br_\bd_\ba_\by _\b-_\b3_\bh_\bo_\bu_\br_\bs -- yesterday morning; can also be
 231        specified as _\b9_\ba_\bm_\b-_\b1_\bd_\ba_\by.
 232
 233        _\b2_\b3_\b:_\b5_\b9 _\b3_\b1_\b._\b1_\b2_\b._\b1_\b9_\b9_\b9 -- 1 minute to the year 2000.
 234
 235        _\b1_\b2_\b/_\b3_\b1_\b/_\b9_\b9 _\b1_\b1_\b:_\b5_\b9_\bp_\bm -- 1 minute to the year 2000 for imperi-
 236        alists.
 237
 238        _\b1_\b2_\ba_\bm _\b0_\b1_\b/_\b0_\b1_\b/_\b0_\b1 -- start of the new millennium
 239
 240        _\be_\bn_\bd_\b-_\b3_\bw_\be_\be_\bk_\bs or _\be_\b-_\b3_\bw -- 3 weeks before end time (may be used
 241        as start time specification).
 242
 243        _\bs_\bt_\ba_\br_\bt_\b+_\b6_\bh_\bo_\bu_\br_\bs or _\bs_\b+_\b6_\bh -- 6 hours after start time (may be
 244        used as end time specification).
 245
 246        _\b9_\b3_\b1_\b2_\b2_\b5_\b5_\b3_\b7 -- 18:45  July 5th, 1999 (yes, seconds since
 247        1970 are valid as well).
 248
 249        _\b1_\b9_\b9_\b7_\b0_\b7_\b0_\b3 _\b1_\b2_\b:_\b4_\b5 -- 12:45  July 3th, 1997 (my favorite, and
 250        its even got an ISO number (8601)).
 251
 252 A\bAU\bUT\bTH\bHO\bOR\bR
 253        Tobias Oetiker <oetiker@ee.ethz.ch>
 254
 255
 256
 257 1.2.10                      2005-06-17                RRDFETCH(1)