doc/rrdupdate.1

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  29 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  30 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  31 .\" nothing in troff, for use with C<>.
  32 .tr \(*W-
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "RRDUPDATE 1"
 132 .TH RRDUPDATE 1 "2008-03-15" "1.3.5" "rrdtool"
 133 .SH "NAME"
 134 rrdupdate \- Store a new set of values into the RRD
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 \&\fBrrdtool\fR {\fBupdate\fR | \fBupdatev\fR} \fIfilename\fR
 138 [\fB\-\-template\fR|\fB\-t\fR\ \fIds-name\fR[\fB:\fR\fIds-name\fR]...]
 139 \&\fBN\fR|\fItimestamp\fR\fB:\fR\fIvalue\fR[\fB:\fR\fIvalue\fR...]
 140 \&\fIat-timestamp\fR\fB@\fR\fIvalue\fR[\fB:\fR\fIvalue\fR...]
 141 [\fItimestamp\fR\fB:\fR\fIvalue\fR[\fB:\fR\fIvalue\fR...]\ ...]
 142 .SH "DESCRIPTION"
 143 .IX Header "DESCRIPTION"
 144 The \fBupdate\fR function feeds new data values into an \fB\s-1RRD\s0\fR. The data
 145 is time aligned (interpolated) according to the properties of the
 146 \&\fB\s-1RRD\s0\fR to which the data is written.
 147 .IP "\fBupdatev\fR" 8
 148 .IX Item "updatev"
 149 This alternate version of \fBupdate\fR takes the same arguments and
 150 performs the same function. The \fIv\fR stands for \fIverbose\fR, which
 151 describes the output returned. \fBupdatev\fR returns a list of any and all
 152 consolidated data points (CDPs) written to disk as a result of the
 153 invocation of update. The values are indexed by timestamp (time_t),
 154 \&\s-1RRA\s0 (consolidation function and PDPs per \s-1CDP\s0), and data source (name).
 155 Note that depending on the arguments of the current and previous call to
 156 update, the list may have no entries or a large number of entries.
 157 .IP "\fIfilename\fR" 8
 158 .IX Item "filename"
 159 The name of the \fB\s-1RRD\s0\fR you want to update.
 160 .IP "\fB\-\-template\fR|\fB\-t\fR \fIds-name\fR[\fB:\fR\fIds-name\fR]..." 8
 161 .IX Item "--template|-t ds-name[:ds-name]..."
 162 By default, the \fBupdate\fR function expects its data input in the order
 163 the data sources are defined in the \s-1RRD\s0, excluding any \s-1COMPUTE\s0 data
 164 sources (i.e. if the third data source \fB\s-1DST\s0\fR is \s-1COMPUTE\s0, the third
 165 input value will be mapped to the fourth data source in the \fB\s-1RRD\s0\fR and
 166 so on). This is not very error resistant, as you might be sending the
 167 wrong data into an \s-1RRD\s0.
 168 .Sp
 169 The template switch allows you to specify which data sources you are
 170 going to update and in which order. If the data sources specified in
 171 the template are not available in the \s-1RRD\s0 file, the update process
 172 will abort with an error message.
 173 .Sp
 174 While it appears possible with the template switch to update data sources
 175 asynchronously, \fBRRDtool\fR implicitly assigns non-COMPUTE data sources missing
 176 from the template the \fI*UNKNOWN*\fR value.
 177 .Sp
 178 Do not specify a value for a \s-1COMPUTE\s0 \fB\s-1DST\s0\fR in the \fBupdate\fR
 179 function. If this is done accidentally (and this can only be done
 180 using the template switch), \fBRRDtool\fR will ignore the value specified
 181 for the \s-1COMPUTE\s0 \fB\s-1DST\s0\fR.
 182 .IP "\fBN\fR|\fItimestamp\fR\fB:\fR\fIvalue\fR[\fB:\fR\fIvalue\fR...]" 8
 183 .IX Item "N|timestamp:value[:value...]"
 184 The data used for updating the \s-1RRD\s0 was acquired at a certain
 185 time. This time can either be defined in seconds since 1970\-01\-01 or
 186 by using the letter 'N', in which case the update time is set to be
 187 the current time. Negative time values are subtracted from the current
 188 time. An \s-1AT_STYLE\s0 \s-1TIME\s0 \s-1SPECIFICATION\s0 (see the \fIrrdfetch\fR
 189 documentation) may also be used by delimiting the end of the time
 190 specification with the '@' character instead of a ':'. Getting the
 191 timing right to the second is especially important when you are
 192 working with data-sources of type \fB\s-1COUNTER\s0\fR, \fB\s-1DERIVE\s0\fR or
 193 \&\fB\s-1ABSOLUTE\s0\fR.
 194 .Sp
 195 The remaining elements of the argument are \s-1DS\s0 updates. The order of
 196 this list is the same as the order the data sources were defined in
 197 the \s-1RRA\s0. If there is no data for a certain data\-source, the letter
 198 \&\fBU\fR (e.g., N:0.1:U:1) can be specified.
 199 .Sp
 200 The format of the value acquired from the data source is dependent on
 201 the data source type chosen. Normally it will be numeric, but the data
 202 acquisition modules may impose their very own parsing of this
 203 parameter as long as the colon (\fB:\fR) remains the data source value
 204 separator.
 205 .SH "EXAMPLE"
 206 .IX Header "EXAMPLE"
 207 \&\f(CW\*(C`rrdtool update demo1.rrd N:3.44:3.15:U:23\*(C'\fR
 208 .PP
 209 Update the database file demo1.rrd with 3 known and one \fI*UNKNOWN*\fR
 210 value. Use the current time as the update time.
 211 .PP
 212 \&\f(CW\*(C`rrdtool update demo2.rrd 887457267:U 887457521:22 887457903:2.7\*(C'\fR
 213 .PP
 214 Update the database file demo2.rrd which expects data from a single
 215 data\-source, three times. First with an \fI*UNKNOWN*\fR value then with two
 216 regular readings. The update interval seems to be around 300 seconds.
 217 .SH "AUTHOR"
 218 .IX Header "AUTHOR"
 219 Tobias Oetiker <tobi@oetiker.ch>