X-Git-Url: https://git.octo.it/?p=rrdtool.git;a=blobdiff_plain;f=doc%2Frrdupdate.pod;h=67908d016f986d6d64ee9af32d07160694267d6d;hp=f1500541a23d15207737073f7bbe446d5ace6888;hb=49db9345033e46dbba978386d8e9f73f4e145a48;hpb=7ece23c6836d772648c460f9214d070a7b74ed4f diff --git a/doc/rrdupdate.pod b/doc/rrdupdate.pod index f150054..67908d0 100644 --- a/doc/rrdupdate.pod +++ b/doc/rrdupdate.pod @@ -1,79 +1,174 @@ =head1 NAME -rrdtool update - Store a new set of values into the rrd - -=for html
PDF version.
+rrdupdate - Store a new set of values into the RRD =head1 SYNOPSIS -B B I -S<[B<--template>|B<-t> I[B<:>I]...]> -S|IB<:>I[B<:>I...]> -SB<@>I[B<:>I...]> +B {B | B} I +S<[B<--template>|B<-t> I[B<:>I]...]> +S<[B<--daemon> I
]> [B<-->] +S|IB<:>I[B<:>I...]> +SB<@>I[B<:>I...]> S<[IB<:>I[B<:>I...] ...]> =head1 DESCRIPTION -The B function feeds new data values into an B. The -data gets time aligned according to the properties of the B to -which the data is written. +The B function feeds new data values into an B. The data +is time aligned (interpolated) according to the properties of the +B to 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. + +Since B requires direct disk access, the B<--daemon> option cannot be +used with this command. + =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 its 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 and +so on). This is not very error resistant, as you might be sending the +wrong data into an 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<--daemon> I
+ +If given, B will try to connect to the caching daemon L +at I
and will fail if the connection cannot be established. If the +connection is successfully established the values will be sent to the daemon +instead of accessing the files directly. + +For a list of accepted formats, see the B<-l> option in the L manual. + =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. -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 -(B<:>) remains the data source value separator. +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', in which case 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. + +When using negative time values, options and data have to be separated +by two dashes (B<-->), else the time value would be parsed as an option. +See below for an example. + +When using negative time values, options and data have to be separated +by two dashes (B<-->), else the time value would be parsed as an option. +See below for an example. + +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. If there is no data for a certain data-source, the letter +B (e.g., N:0.1:U:1) can be specified. + +The format of the value acquired from the data source is dependent on +the data source type chosen. Normally it will be numeric, but the data +acquisition modules may impose their very own parsing of this +parameter as long as the colon (B<:>) remains the data source value +separator. + +=back + +=head1 ENVIRONMENT VARIABLES + +The following environment variables may be used to change the behavior of +Cupdate>: + +=over + +=item B + +If this environment variable is set it will have the same effect as specifying +the C<--daemon> option on the command line. If both are present, the command +line argument takes precedence. =back -=head1 EXAMPLE +=head1 EXAMPLES + +=over + +=item * C Update the database file demo1.rrd with 3 known and one I<*UNKNOWN*> value. Use the current time as the update time. -C +=item * + +C Update the database file demo2.rrd which expects data from a single data-source, three times. First with an I<*UNKNOWN*> value then with two -normal readings. The update interval seems to be around 300 seconds. +regular readings. The update interval seems to be around 300 seconds. + +=item * + +C + +Update the database file demo3.rrd two times, using five seconds in the +past and the current time as the update times. + +=item * + +C + +Update the file C with a single data source, using the +current time. If the caching daemon cannot be reached, do B fall back to +direct file access. + +=item * + +C + +Use the UNIX domain socket C to contact the caching daemon. If +the caching daemon is not available, update the file C directly. +B Since a relative path is specified, the following disturbing effect +may occur: If the daemon is available, the file relative to the working +directory B is used. If the daemon is not available, the file +relative to the current working directory of the invoking process is used. +B Don't do relative paths, kids! + +=back -=head1 AUTHOR +=head1 AUTHORS -Tobias Oetiker +Tobias Oetiker , +Florian Forster atEverplant.org>