From: Peter Stamfest Date: Sun, 11 Jan 2015 19:25:26 +0000 (+0100) Subject: Adapt man pages to cover new "tune" capabilites and remove obsolete X-Git-Tag: v1.5.0-rc2~28^2^2~1 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=a0e9ed271adc33c667e3682640b2e612d474dd83;p=thirdparty%2Frrdtool-1.x.git Adapt man pages to cover new "tune" capabilites and remove obsolete "modify" man page. --- diff --git a/doc/rrdcreate.pod b/doc/rrdcreate.pod index 6de2dc52..b7b33ece 100644 --- a/doc/rrdcreate.pod +++ b/doc/rrdcreate.pod @@ -743,6 +743,6 @@ divides each PDP of the AccumDuration by the corresponding PDP of TotalRequests and stores the average request duration. The remainder of the RPN expression handles the divide by zero case. -=head1 AUTHOR +=head1 AUTHORS -Tobias Oetiker Etobi@oetiker.chE +Tobias Oetiker Etobi@oetiker.chE, Peter Stamfest Epeter@stamfest.atE diff --git a/doc/rrdmodify.pod b/doc/rrdmodify.pod deleted file mode 100644 index 5e1efe81..00000000 --- a/doc/rrdmodify.pod +++ /dev/null @@ -1,121 +0,0 @@ -=head1 NAME - -rrdmodify - Change the data source structure of an RRD - -=head1 SYNOPSIS - -B {B} S<[-d
]> S<[-s ]> -I I -S<[ BI | BI ... ]> - -=head1 DESCRIPTION - -The B function copies an RRD file I to -I, possible removing or adding data sources and -round-robin archives (RRAs) on the fly. When I and -I denote the same file, this is (almost) identical to an -in-place modification. - -=over 8 - -=item S<-d
> - -If given, B will try to connect to the caching daemon -L at I
to flush any data not yet written to the -input RRD before reading it in. After writing the final file a FORGET -command is sent to the daemon. This will make the daemon recognize the -updated structure of the underlying RRD file. - -=item S<-s > - -Changes the step size if the RRD to newstep. There are restrictions on -the possible I that can be given, namely: The current -stepping of the I must be a multiple of the -I. This also means that currently the step size can only be -reduced. - -When giving this option, modifications to RRAs will be done AFTER -adapting the step size, so any RRA specifications referring to counts -of PDPs will allready use the new stepping. - -Note that changing the step size does NOT change the number of rows of -any existing RRA by itself: Only the stepsize and assorted other meta -values get changed (namely the PDP count of RRAs and possibly some CDP -information). - -For a reduced step size to make sense in practice, it is usually a -good idea to add one or more new RRAs with a step size of 1, because -all existing RRAs will afterwards definitly have a pdp step count of -larger than one, effectively hiding the step smaller size. - -=item I - -The name of the source B file you want to copy/modify. - -=item I - -The name of the destination B file. If it names the same file as -I, the new RRD will effectively relace the old one. - -=item BI - -Every data source named with a DEL specification will be removed -during the copy operation. The resulting RRD will miss both the -definition and the data for that data source. Multiple DEL -specifications are permitted. - -=item BI - -For every such data source definition (for the exact syntax see the -create command), a new data source will be added to the output -RRD. Multiple DS specifications are permitted. - -=item BI - -Removes the RRA with index I. - -=item BI - -For every such archive definition (for the exact syntax see the -create command), a new RRA will be added to the output -RRD. Multiple RRA specifications are permitted. - -=item BI:[+-=] - -Adds/removes or sets the given number of rows for the RRA with index -. - -=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 data -for the I will be flushed before performing the -copy/modify operation. Afterwards the I will be -forgotten by the cache daemon, so that the next access using the -caching daemon will read the proper structure. - -For a list of accepted formats, see the B<-l> option in the L manual. - -=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 AUTHORS - -Tobias Oetiker , -Peter Stamfest - diff --git a/doc/rrdtool.pod b/doc/rrdtool.pod index 4e336d64..46368fb7 100644 --- a/doc/rrdtool.pod +++ b/doc/rrdtool.pod @@ -80,11 +80,7 @@ uses fetch to retrieve its data from an RRD. Check L. =item B -Alter setup of an RRD. Check L. - -=item B - -Alter structure of an RRD. Check L. +Alter setup and structure of an RRD. Check L. =item B diff --git a/doc/rrdtune.pod b/doc/rrdtune.pod index 859c1434..71d70469 100644 --- a/doc/rrdtune.pod +++ b/doc/rrdtune.pod @@ -21,6 +21,12 @@ S<[B<--gamma-deviation> I]> S<[B<--smoothing-window> I]> S<[B<--smoothing-window-deviation> I]> S<[B<--aberrant-reset> I]> +S<[B<--daemon>|B<-D> I
]> +S<[BI]> +S<[BI]> +S<[BI]> +S<[BI]> +S<[BI:[+-=]]> =head1 DESCRIPTION @@ -38,6 +44,15 @@ the data source header in the B. A second application of the B function is to set or alter parameters used by the specialized function B for aberrant behavior detection. +Still another application is to add or remove data sources (DS) or +add / remove or alter some aspects of round-robin archives (RRA). These operations +are not really done in-place, but rather generate a new RRD file internally and +move it over the original file. Data is kept intact during theses operations. +For even more in-depth modifications you may review the +S> and S> options of the B function which +allow you to combine multiple RRD files into a new one and which is even more clever +in what data it is able to keep or "regenerate". + =over 8 =item I @@ -157,6 +172,58 @@ data source. Use of this tuning option is advised when the behavior of the data source time series changes in a drastic and permanent manner. +=item B<--daemon>|B<-D> I
+ +B: Because the B<-d> (small letter 'd') option was already taken, this +function (unlike most other) uses the capital letter 'D' for the one-letter +option to name the cache daemon. + +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 data +for the I will be flushed before performing the +copy/modify operation. Afterwards the I will be +forgotten by the cache daemon, so that the next access using the +caching daemon will read the proper structure. + +This sequence of operations is designed to achieve a consistent overall +result with respect to +RRD internal file consistency when using one of the B or B changing +operations (that is: the resulting file should always be a valid RRD file, +regardless of concurrent updates through the caching daemon). +Regarding data consistency such guarantees are not made: Without external +synchronisation concurrent updates may be lost. + +For a list of accepted formats, see the B<-l> option in the L manual. + +=item BI + +Every data source named with a DEL specification will be removed. +The resulting RRD will miss both the definition and the data for that +data source. Multiple DEL specifications are permitted. + +=item BI + +For every such data source definition (for the exact syntax see the +B command), a new data source will be added to the RRD. Multiple DS +specifications are permitted. + +=item BI + +Removes the RRA with index I. The index is zero-based, +that is the very first RRA has index 0. + +=item BI + +For every such archive definition (for the exact syntax see the +B command), a new RRA will be added to the output +RRD. Multiple RRA specifications are permitted. + +=item BI:[+-=] + +Adds/removes or sets the given number of rows for the RRA with index +. The index is zero-based, that is the very first RRA has index 0. + =back =head1 EXAMPLE 1 @@ -177,7 +244,15 @@ window-length is 9 and the default failure-threshold is 7. This command now defines a failure as 3 or more violations in a temporal window of 5 time points. -=head1 AUTHOR +=head1 EXAMPLE 3 + +C + +Delete the data source named B and extend the very first archive by 10 rows. +This will in fact replace the input RRD with a new RRD keeping all existing data. +For most practical use cases this is identical to a real in-place modification. + +=head1 AUTHORS -Tobias Oetiker +Tobias Oetiker Etobi@oetiker.chE, Peter Stamfest Epeter@stamfest.atE