X-Git-Url: https://git.octo.it/?p=rrdtool.git;a=blobdiff_plain;f=doc%2Frrdupdate.pod;h=50a656eb8b06afbf1269db7878d7f4cc35f48a5c;hp=bc4e902c87e1090203189e094ed3e84c69d30931;hb=d828f3eccac8dbad7bfc14812e406377669baaa4;hpb=5837606887a6d81e8b1f7588525cb1c8783fb62b diff --git a/doc/rrdupdate.pod b/doc/rrdupdate.pod index bc4e902..50a656e 100644 --- a/doc/rrdupdate.pod +++ b/doc/rrdupdate.pod @@ -1,14 +1,15 @@ =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
PDF version.
=head1 SYNOPSIS -B B I +B {B | B} I S<[B<--template>|B<-t> I[B<:>I]...]> S|IB<:>I[B<:>I...]> +SB<@>I[B<:>I...]> S<[IB<:>I[B<:>I...] ...]> =head1 DESCRIPTION @@ -19,39 +20,63 @@ which the data is written. =over 8 +=item B + +This alternate version of B takes the same arguments and +performs the same function. The I stands for I, which +describes the output returned. B 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 The name of the B you want to update. =item B<--template>|B<-t> I[B<:>I]... -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 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 is COMPUTE, the third input value +will be mapped to the fourth data source in the B). 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 implicitly assigns non-COMPUTE data sources missing +from the template the I<*UNKNOWN*> value. + +Do not specify a value for a COMPUTE B in the B function. If +this is done accidentally (and this can only be done using the template switch), +B will ignore the value specified for the COMPUTE B. + =item B|IB<:>I[B<:>I...] 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 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, B or B. 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 (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