=head1 NAME
-rrdtool update - Store a new set of values into the rrd
+rrdtool update - Store a new set of values into the RRD
=for html <div align="right"><a href="rrdupdate.pdf">PDF</a> version.</div>
=head1 SYNOPSIS
-B<rrdtool> B<update> I<filename>
+B<rrdtool> {B<update> | B<updatev>} I<filename>
S<[B<--template>|B<-t> I<ds-name>[B<:>I<ds-name>]...]>
S<B<N>|I<timestamp>B<:>I<value>[B<:>I<value>...]>
+S<I<at-timestamp>B<@>I<value>[B<:>I<value>...]>
S<[I<timestamp>B<:>I<value>[B<:>I<value>...] ...]>
=head1 DESCRIPTION
=over 8
+=item B<updatev>
+
+This alternate version of B<update> takes the same arguments and
+performs the same function. The I<v> stands for I<verbose>, which
+describes the output returned. B<updatev> returns a list of any and all
+consolidated data points (CDPs) written to disk as a result of the
+invocation of update. The values are indexed by timestamp (time_t),
+RRA (consolidation function and PDPs per CDP), and data source (name).
+Note that depending on the arguments of the current and previous call to
+update, the list may have no entries or a large number of entries.
+
=item I<filename>
The name of the B<RRD> you want to update.
=item B<--template>|B<-t> I<ds-name>[B<:>I<ds-name>]...
-by default, the update function expects the data input in the order,
-the data sources are defined in the RRD. This is not very error
-resistant, as you might be sending the wrong data into a RRD.
+by default, the B<update> function expects the data input in the order
+the data sources are defined in the RRD, excluding any COMPUTE data sources
+(i.e. if the third data source B<DST> is COMPUTE, the third input value
+will be mapped to the fourth data source in the B<RRD>). This is not very
+error resistant, as you might be sending the wrong data into a RRD.
The template switch allows you to specify which data sources you are
going to update and in which order. If the data sources specified in
-the template are not available in the rrd file, the update process
+the template are not available in the RRD file, the update process
will abort with an error message.
+While it appears possible with the template switch to update data sources
+asynchronously, B<RRDtool> implicitly assigns non-COMPUTE data sources missing
+from the template the I<*UNKNOWN*> value.
+
+Do not specify a value for a COMPUTE B<DST> in the B<update> function. If
+this is done accidentally (and this can only be done using the template switch),
+B<RRDtool> will ignore the value specified for the COMPUTE B<DST>.
+
=item B<N>|I<timestamp>B<:>I<value>[B<:>I<value>...]
The data used for updating the RRD was acquired at a certain time. This
time can either be defined in seconds since 1970-01-01. Or by using the
letter 'N' the update time is set to be the current time. Negative time
values are subtracted from the current time.
+An AT_STYLE TIME SPECIFICATION (see the I<rrdfetch> documentation) may
+also be used by delimiting the end of the time specification with the '@' character
+instead of a ':'.
Getting the timing right to the second is especially
important when you are working with data-sources of type B<COUNTER>,
B<DERIVE> or B<ABSOLUTE>.
The remaining elements of the argument are DS updates. The order of this list is
-the same as the order the data sources were defined in the rra.
+the same as the order the data sources were defined in the RRA.
If there is no data for a certain data-source, the letter
B<U> (eg. N:0.1:U:1) can be defined.
The format of the value acquired from the data source is dependent of the
data source type chosen. Normally it will be numeric, but the data acquisition
-modules my impose their very own parsing of this parameter as long as the colon
+modules may impose their very own parsing of this parameter as long as the colon
(B<:>) remains the data source value separator.
=back
projects / rrdtool.git / blobdiff