X-Git-Url: https://git.octo.it/?p=rrdtool.git;a=blobdiff_plain;f=doc%2Frrdcached.pod;h=d8d88c59e520de524a8d72fdc274d53baff24fcb;hp=8ad37beb8f00798ad29463fba44e30fe31139f04;hb=afdd543a34762dba360a103e9b17f38b64be83ff;hpb=ac630adec930653637199258efd99024d49325c7

diff --git a/doc/rrdcached.pod b/doc/rrdcached.pod
index 8ad37be..d8d88c5 100644
--- a/doc/rrdcached.pod
+++ b/doc/rrdcached.pod
@@ -6,7 +6,7 @@ rrdcached - Data caching daemon for rrdtool
 
 =head1 SYNOPSIS
 
-B<rrdcached> [B<-l> I<address>] [B<-w> I<timeout>] [B<-f> I<timeout>]
+B<rrdcached> [B<-l> I<address>] [B<-w> I<timeout>] [B<-z> I<delay>] [B<-f> I<timeout>] [B<-j> I<dir>]
 
 =head1 DESCRIPTION
 
@@ -34,6 +34,21 @@ socket. If I<address> begins with C<unix:>, everything following that prefix is
 interpreted as the path to a UNIX domain socket. Otherwise the address or node
 name are resolved using L<getaddrinfo>.
 
+For network sockets, a port may be specified by using the form
+C<B<[>I<address>B<]:>I<port>>. If the address is an IPv4 address or a fully
+qualified domain name (i.E<nbsp>e. the address contains at least one dot
+(C<.>)), the square brackets can be omitted, resulting in the (simpler)
+C<I<address>B<:>I<port>> pattern.. The default port is B<42217/udp>.
+
+The following formats are accepted. Please note that the address of the UNIX
+domain socket B<must> start with a slash in the second case!
+
+   unix:</path/to/unix.sock>
+   /<path/to/unix.sock>
+   <hostname-or-ip>
+   [<hostname-or-ip>]:<port>
+   <hostname-or-ipv4>:<port>
+
 If the B<-l> option is not specified the default address,
 C<unix:/tmp/rrdcached.sock>, will be used.
 
@@ -42,6 +57,13 @@ C<unix:/tmp/rrdcached.sock>, will be used.
 Data is written to disk every I<timeout> seconds. If this option is not
 specified the default interval of 300E<nbsp>seconds will be used.
 
+=item B<-z> I<delay>
+
+If specified, rrdcached will delay writing of each RRD for a random number
+of seconds in the rangeE<nbsp>[0,I<delay>).  This will avoid too many
+writes being queued simultaneously.  This value should be no greater than
+the value specified in B<-w>.  By default, there is no delay.
+
 =item B<-f> I<timeout>
 
 Every I<timeout> seconds the entire cache is searched for old values which are
@@ -54,6 +76,19 @@ 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<-j> I<dir>
+
+Write updates to a journal in I<dir>.  In the event of a program or system
+crash, this will allow the daemon to write any updates that were pending
+at the time of the crash.
+
+On startup, the daemon will check for journal files in this directory.  If
+found, all updates therein will be read into memory before the daemon
+starts accepting new connections.
+
+The journal will be rotated with the same frequency as the flush timer
+given by B<-f>.  On clean shutdown, the journal files are removed.
+
 =item B<-b> I<dir>
 
 The daemon will change into a specific directory at startup. All files passed
@@ -108,6 +143,15 @@ the disk itself. All other commands can send a B<FLUSH> command (see below) to
 the daemon before accessing the files, so they work with up-to-date data even
 if the cache timeout is large.
 
+=head1 ERROR REPORTING
+
+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
+C<LOG_DAEMON>.
+
 =head1 HOW IT WORKS
 
 When receiving an update, B<rrdcached> does not write to disk but looks for an
@@ -143,9 +187,8 @@ The downside of caching values is that they won't show up in graphs generated
 from the RRDE<nbsp>files. To get around this, the daemon provides the "flush
 command" to flush specific files. This means that the file is inserted at the
 B<head> of the update queue or moved there if it is already enqueued. The flush
-command will return after the update thread has dequeued the file, so there is
-a good chance that the file has been updated by the time the client receives
-the response from the daemon, but there is no guarantee.
+command will return only after the file's pending updates have been written
+to disk.
 
  +------+   +------+                               +------+
  ! head !   ! root !                               ! tail !
@@ -273,6 +316,11 @@ Causes the daemon to put I<filename> to the B<head> of the update queue
 (possibly moving it there if the node is already enqueued). The answer will be
 sent B<after> the node has been dequeued.
 
+=item B<FLUSHALL>
+
+Causes the daemon to start flushing ALL pending values to disk.  This
+returns immediately, even though the writes may take a long time.
+
 =item B<HELP> [I<command>]
 
 Returns a short usage message. If no command is given, or I<command> is
@@ -293,12 +341,16 @@ name of the value, a colon, one or more spaces and the actual value.
 
 Example:
 
- 5 Statistics follow
+ 9 Statistics follow
  QueueLength: 0
+ UpdatesReceived: 30
+ FlushesReceived: 2
  UpdatesWritten: 13
  DataSetsWritten: 390
  TreeNodesNumber: 13
  TreeDepth: 4
+ JournalBytes: 190
+ JournalRotate: 0
 
 =item B<UPDATE> I<filename> I<values> [I<values> ...]
 
@@ -306,6 +358,13 @@ 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.
 
+=item B<WROTE> I<filename>
+
+This command is written to the journal after a file is successfully
+written out to disk.  It is used during journal replay to determine which
+updates have already been applied.  It is I<only> valid in the journal; it
+is not accepted from the other command channels.
+
 =back
 
 =head2 Performance Values
@@ -318,18 +377,18 @@ The following counters are returned by the B<STATS> command:
 
 Number of nodes currently enqueued in the update queue.
 
-=item B<TreeDepth> I<(unsigned 64bit integer)>
+=item B<UpdatesReceived> I<(unsigned 64bit integer)>
 
-Depth of the tree used for fast key lookup.
+Number of UPDATE commands received.
 
-=item B<TreeNodesNumber> I<(unsigned 64bit integer)>
+=item B<FlushesReceived> I<(unsigned 64bit integer)>
 
-Number of nodes in the cache.
+Number of FLUSH commands received.
 
 =item B<UpdatesWritten> I<(unsigned 64bit integer)>
 
-Total number of updates, i.E<nbsp>e. calls to C<rrd_update_r>, since the daemon
-was started.
+Total number of updates, i.E<nbsp>e. calls to C<rrd_update_r>, since the
+daemon was started.
 
 =item B<DataSetsWritten> I<(unsigned 64bit integer)>
 
@@ -338,6 +397,32 @@ 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.
 
+=item B<TreeNodesNumber> I<(unsigned 64bit integer)>
+
+Number of nodes in the cache.
+
+=item B<TreeDepth> I<(unsigned 64bit integer)>
+
+Depth of the tree used for fast key lookup.
+
+=item B<JournalBytes> I<(unsigned 64bit integer)>
+
+Total number of bytes written to the journal since startup.
+
+=item B<JournalRotate> I<(unsigned 64bit integer)>
+
+Number of times the journal has been rotated since startup.
+
+=back
+
+=head1 SIGNALS
+
+=over 4
+
+=item SIGINT and SIGTERM
+
+The daemon exits normally on receipt of either of these signals.
+
 =back
 
 =head1 BUGS
@@ -348,7 +433,14 @@ No known bugs at the moment.
 
 L<rrdtool>, L<rrdgraph>
 
-=head1 AUHOR
+=head1 AUTHOR
 
 B<rrdcached> and this manual page have been written by Florian Forster
 E<lt>octoE<nbsp>atE<nbsp>verplant.orgE<gt>.
+
+=head1 CONTRIBUTORS
+
+kevin brintnall E<lt>kbrint@rufus.netE<gt>
+
+=cut
+