updated for release

[rrdtool.git] / doc / rrdcached.pod

diff --git a/doc/rrdcached.pod b/doc/rrdcached.pod
index fd56523..5113c2d 100644 (file)
--- a/doc/rrdcached.pod
+++ b/doc/rrdcached.pod
@@ -6,7 +6,17 @@ rrdcached - Data caching daemon for rrdtool
 
 =head1 SYNOPSIS
 
 
 =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]
+[-g]
+[B<-b>E<nbsp>I<base_dir>E<nbsp>[B<-B>]]

 
 =head1 DESCRIPTION
 
 
 =head1 DESCRIPTION
 


@@ -81,6 +91,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.
 
 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
 =item B<-j> I<dir>
 
 Write updates to a journal in I<dir>.  In the event of a program or system


@@ -107,6 +124,10 @@ To disable fast shutdown, use the B<-F> option.
 ALWAYS flush all updates to the RRD data files when the daemon is shut
 down, regardless of journal setting.
 
 ALWAYS flush all updates to the RRD data files when the daemon is shut
 down, regardless of journal setting.
 

+=item B<-g>
+
+Run in the foreground.  The daemon will not fork().
+

 =item B<-b> I<dir>
 
 The daemon will change into a specific directory at startup. All files passed
 =item B<-b> I<dir>
 
 The daemon will change into a specific directory at startup. All files passed


@@ -125,6 +146,18 @@ used.
   updated by the daemon,  assuming the base directory
   "/tmp".
 
   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
 =item B<-B>
 
 Only permit writes into the base directory specified in B<-b> (and any


@@ -372,6 +405,14 @@ not yet been written to the underlying RRD file.
 
 Removes I<filename> from the cache.  Any pending updates B<WILL BE LOST>.
 
 
 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
 =item B<HELP> [I<command>]
 
 Returns a short usage message. If no command is given, or I<command> is


@@ -409,6 +450,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.
 
 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
 =item B<WROTE> I<filename>
 
 This command is written to the journal after a file is successfully


@@ -434,14 +479,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:  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
 
     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
 =back
 
 =head2 Performance Values


@@ -469,10 +518,11 @@ daemon was started.
 
 =item B<DataSetsWritten> I<(unsigned 64bit integer)>
 
 
 =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)>
 
 
 =item B<TreeNodesNumber> I<(unsigned 64bit integer)>