Attached a patch for the rrd-tool LIBDBI integration with the following improvements:

[rrdtool.git] / doc / rrdcached.pod

diff --git a/doc/rrdcached.pod b/doc/rrdcached.pod
index b01165e..7ecff8b 100644 (file)
--- a/doc/rrdcached.pod
+++ b/doc/rrdcached.pod
@@ -6,7 +6,16 @@ rrdcached - Data caching daemon for rrdtool
 
 =head1 SYNOPSIS
 
-B<rrdcached> [B<-l/-L> I<address>] [B<-w> I<timeout>] [B<-z> I<delay>] [B<-f> I<timeout>] [B<-j> I<dir>] [-F] [B<-b> I<dir> [B<-B>]]
+B<rrdcached>
+[B<-l/-L>E<nbsp>I<address>]
+[B<-w>E<nbsp>I<timeout>]
+[B<-z>E<nbsp>I<delay>]
+[B<-f>E<nbsp>I<timeout>]
+[B<-p>E<nbsp>I<pid_file>]
+[B<-t>E<nbsp>I<write_threads>]
+[B<-j>E<nbsp>I<journal_dir>]
+[-F]
+[B<-b>E<nbsp>I<base_dir>E<nbsp>[B<-B>]]
 
 =head1 DESCRIPTION
 
@@ -81,6 +90,13 @@ cases. This timeout defaults to 3600E<nbsp>seconds.
 Sets the name and location of the PID-file. If not specified, the default,
 C<I<$localststedir>/run/rrdcached.pid> will be used.
 
+=item B<-t> I<write_threads>
+
+Specifies the number of threads used for writing RRD files.  The default
+isE<nbsp>4.  Increasing this number will allow rrdcached to have more
+simultaneous I/O requests into the kernel.  This may allow the kernel to
+re-order disk writes, resulting in better disk throughput.
+
 =item B<-j> I<dir>
 
 Write updates to a journal in I<dir>.  In the event of a program or system
@@ -125,6 +141,18 @@ used.
   updated by the daemon,  assuming the base directory
   "/tmp".
 
+B<WARNING:> The paths up to and including the base directory B<MUST NOT BE>
+symbolic links.  In other words, if the base directory is
+specified as:
+
+    -b /base/dir/somewhere
+
+... then B<NONE> of the following should be symbolic links:
+
+    /base
+    /base/dir
+    /base/dir/somewhere
+
 =item B<-B>
 
 Only permit writes into the base directory specified in B<-b> (and any
@@ -173,7 +201,7 @@ The daemon reports errors in one of two ways: During startup, error messages
 are printed to C<STDERR>. One of the steps when starting up is to fork to the
 background and closing C<STDERR> - after this writing directly to the user is
 no longer possible. Once this has happened, the daemon will send log messages
-to the system logging daemon using L<syslog(3)>. The facility used it
+to the system logging daemon using L<syslog(3)>. The facility used is
 C<LOG_DAEMON>.
 
 =head1 HOW IT WORKS
@@ -372,6 +400,14 @@ not yet been written to the underlying RRD file.
 
 Removes I<filename> from the cache.  Any pending updates B<WILL BE LOST>.
 
+=item B<QUEUE>
+
+Shows the files that are on the output queue.  Returns zero or more lines
+in the following format, where E<lt>num_valsE<gt> is the number of values
+to be written for the E<lt>fileE<gt>:
+
+    <num_vals> <file>
+
 =item B<HELP> [I<command>]
 
 Returns a short usage message. If no command is given, or I<command> is
@@ -409,6 +445,10 @@ Adds more data to a filename. This is B<the> operation the daemon was designed
 for, so describing the mechanism again is unnecessary. Read L<HOW IT WORKS>
 above for a detailed explanation.
 
+Note that rrdcached only accepts absolute timestamps in the update values.
+Updates strings like "N:1:2:3" are automatically converted to absolute
+time by the RRD client library before sending to rrdcached.
+
 =item B<WROTE> I<filename>
 
 This command is written to the journal after a file is successfully
@@ -434,14 +474,18 @@ message itself.  The first user command after B<BATCH> is command number one.
 
     client:  BATCH
     server:  0 Go ahead.  End with dot '.' on its own line.
-    client:  UPDATE x.rrd N:1:2:3            <--- command #1
-    client:  UPDATE y.rrd N:3:4:5            <--- command #2
+    client:  UPDATE x.rrd 1223661439:1:2:3            <--- command #1
+    client:  UPDATE y.rrd 1223661440:3:4:5            <--- command #2
     client:  and so on...
     client:  .
     server:  2 Errors
     server:  1 message for command 1
     server:  12 message for command 12
 
+=item B<QUIT>
+
+Disconnect from rrdcached.
+
 =back
 
 =head2 Performance Values
@@ -469,10 +513,11 @@ daemon was started.
 
 =item B<DataSetsWritten> I<(unsigned 64bit integer)>
 
-Total number of "data sets" written to disk since the daemon was started. A
-data set is one or more values passed to the B<UPDATE> command. For example:
-C<N:123:456> is one data set with two values. The term "data set" is used to
-prevent confusion whether individual values or groups of values are counted.
+Total number of "data sets" written to disk since the daemon was
+started. A data set is one or more values passed to the B<UPDATE>
+command. For example: C<1223661439:123:456> is one data set with two
+values. The term "data set" is used to prevent confusion whether
+individual values or groups of values are counted.
 
 =item B<TreeNodesNumber> I<(unsigned 64bit integer)>