X-Git-Url: https://git.octo.it/?a=blobdiff_plain;f=doc%2Frrdcached.pod;fp=doc%2Frrdcached.pod;h=f40f065c48fe2aa1e16f98aa06dbf356df5b742e;hb=3ad3cec5db1ba33a23e3e0fbb8c19198cab59c3d;hp=48ab1886c38f57bb95dfde92354186b8fef6aa21;hpb=d5102d959fce145c0fac926517a946290bee1124;p=rrdtool.git diff --git a/doc/rrdcached.pod b/doc/rrdcached.pod index 48ab188..f40f065 100644 --- a/doc/rrdcached.pod +++ b/doc/rrdcached.pod @@ -192,6 +192,120 @@ files will be messed up good! You have been warned. +=head1 PROTOCOL + +The daemon communicates with clients using a line based ASCII protocol which is +easy to read and easy to type. This makes it easy for scripts to implement the +protocol and possible for users to use L to connect to the daemon +and test stuff "by hand". + +The protocol is line based, this means that each record consists of one or more +lines. A line is terminated by the line feed character C<0x0A>, commonly +written as C<\n>. In the examples below, this character will be written as +CLFE> ("line feed"). + +After the connection has been established, the client is expected to send a +"command". A command consists of the command keyword, possibly some arguments, +and a terminating newline character. For a list of commands, see +L below. + +Example: + + FLUSH /tmp/foo.rrd + +The daemon answers with a line consisting of a status code and a short status +message, seperated by one or more space characters. A negative status code +signals an error, a positive status code or zero signal success. If the status +code is greater than zero, it indicates the number of lines that follow the +status line. + +Examples: + + 0 Success + + 2 Two lines follow + This is the first line + And this is the second line + +=head2 Valid Commands + +The following commands are understood by the daemon: + +=over 4 + +=item B I + +Causes the daemon to put I to the B of the update queue +(possibly moving it there if the node is already enqueued). The answer will be +sent B the node has been dequeued. + +=item B [I] + +Returns a short usage message. If no command is given, or I is +B, a list of commands supported by the daemon is returned. Otherwise a +short description, possibly containing a pointer to a manpage, is returned. +Obviously, this is meant for interactive usage and the format in which the +commands and usage summaries are returned is not well defined. + +=item B + +Returns a list of metrics which can be used to measure the daemons performance +and check its status. For a description of the values returned, see +L below. + +The format in which the values are returned is similar to many other line based +protocols: Each value is printed on a separate line, each consisting of the +name of the value, a colon, one or more spaces and the actual value. + +Example: + + 5 Statistics follow + QueueLength: 0 + UpdatesWritten: 13 + DataSetsWritten: 390 + TreeNodesNumber: 13 + TreeDepth: 4 + +=item B I I [I ...] + +Adds more data to a filename. This is B operation the daemon was designed +for, so describing the mechanism again is inappropriate. Read L +above for a detailed description. + +=back + +=head2 Performance Values + +The following counters are returned by the B command: + +=over 4 + +=item B I<(unsigned 64bit integer)> + +Number of nodes currently enqueued in the update queue. + +=item B I<(unsigned 64bit integer)> + +Depth of the tree used for fast key lookup. + +=item B I<(unsigned 64bit integer)> + +Number of nodes in the cache. + +=item B I<(unsigned 64bit integer)> + +Total number of updates, i.Ee. calls to C, since the daemon +was started. + +=item B 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 command. For example: +C 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. + +=back + =head1 BUGS No known bugs at the moment.