X-Git-Url: https://git.octo.it/?p=collectd.git;a=blobdiff_plain;f=src%2Fcollectdctl.pod;h=d921330464aba9487d7d9caa4fee7480497ad691;hp=f3fb866a971e70ac580897ee3a74d97c1d5c1313;hb=633c3966f770e4d46651a2fe219a18d8a9907a9f;hpb=ef3517dc3971eaf3986331b532f201e52dea7817

diff --git a/src/collectdctl.pod b/src/collectdctl.pod
index f3fb866a..d9213304 100644
--- a/src/collectdctl.pod
+++ b/src/collectdctl.pod
@@ -1,23 +1,21 @@
+=encoding UTF-8
+
 =head1 NAME
 
-collectd-flush - Small command line utility to flush collectd
+collectdctl - Control interface for collectd
 
 =head1 SYNOPSIS
 
-collectd-flush I<[options]>
+collectdctl I<[options]> I<E<lt>commandE<gt>> I<[command options]>
 
 =head1 DESCRIPTION
 
-This small command line utitilty uses C<libcollectdclient> to flush collectd
-through a socket from the L<unixsock plugin>. Useful if you want to be sure
-you have the latest values in your RRD files before graphing them or copying
-them somewhere else.
+collectdctl provides a control interface for collectd, which may be used to
+interact with the daemon using the C<unixsock plugin>.
 
-=head1 ARGUMENTS AND OPTIONS
+=head1 OPTIONS
 
-The following arguments and options are understood by collectd-flush. The order
-of the arguments generally doesn't matter, as long as no argument is passed
-more than once.
+collectdctl supports the following options:
 
 =over 4
 
@@ -26,14 +24,84 @@ more than once.
 Path to the UNIX socket opened by collectd's C<unixsock plugin>.
 Default: /var/run/collectd-unixsock
 
-=item B<-p> I<plugin>
+=item B<-h>
+
+Display usage information and exit.
+
+=back
+
+=head1 AVAILABLE COMMANDS
+
+The following commands are supported:
+
+=over 4
+
+=item B<getval> I<E<lt>identifierE<gt>>
+
+Query the latest collected value identified by the specified
+I<E<lt>identifierE<gt>> (see below). The value-list associated with that
+data-set is returned as a list of key-value-pairs, each on its own line. Keys
+and values are separated by the equal sign (C<=>).
+
+=item B<flush> [B<timeout=>I<E<lt>secondsE<gt>>] [B<plugin=>I<E<lt>nameE<gt>>]
+[B<identifier=>I<E<lt>idE<gt>>]
+
+Flush the daemon. This is useful, e.E<nbsp>g., to make sure that the latest
+values have been written to the respective RRD file before graphing them or
+copying them to somewhere else.
+
+The following options are supported by the flush command:
+
+=over 4
+
+=item B<timeout=>I<E<lt>secondsE<gt>>
+
+Flush values older than the specified timeout (in seconds) only.
+
+=item B<plugin=>I<E<lt>nameE<gt>>
 
-Plugin to flush I<to>. Example: B<rrdtool>.
+Flush the specified plugin only. I.E<nbsp>e., data cached by the specified
+plugin is written to disk (or network or whatever), if the plugin supports
+that operation.
 
-=item B<-i> I<identifier>
+Example: B<rrdtool>.
 
-If this option is present, only the data specified by I<identifier> will be flushed.
-I<identifier> has the following format:
+=item B<identifier=>I<E<lt>idE<gt>>
+
+If this option is present, only the data specified by the specified identifier
+(see below) will be flushed. Note that this option is not supported by all
+plugins (e.E<nbsp>g., the C<network> plugin does not support this).
+
+=back
+
+The B<plugin> and B<identifier> options may be specified more than once. In
+that case, all combinations of specified plugins and identifiers will be
+flushed only.
+
+=item B<listval>
+
+Returns a list of all values (by their identifier) available to the
+C<unixsock> plugin. Each value is printed on its own line. I.E<nbsp>e., this
+command returns a list of valid identifiers that may be used with the other
+commands.
+
+=item B<putval> I<E<lt>identifierE<gt>> [B<interval=>I<E<lt>secondsE<gt>>]
+I<E<lt>value-list(s)E<gt>>
+
+Submit one or more values (identified by I<E<lt>identifierE<gt>>, see below)
+to the daemon which will then dispatch them to the write plugins. B<interval>
+specifies the interval (in seconds) used to collect the values following that
+option. It defaults to the default of the running collectd instance receiving
+the data. Multiple I<E<lt>value-list(s)E<gt>> (see below) may be specified.
+Each of them will be submitted to the daemon. The values have to match the
+data-set definition specified by the type as given in the identifier (see
+L<types.db(5)> for details).
+
+=back
+
+=head1 IDENTIFIERS
+
+An identifier has the following format:
 
 [I<hostname>/]I<plugin>[-I<plugin_instance>]/I<type>[-I<type_instance>]
 
@@ -42,30 +110,53 @@ Examples:
  uptime/uptime
  otherhost/memory/memory-used
 
-Hostname defaults to the local hostname if omitted. No error is returned if the
-specified identifier does not exist (this is a limitation in the
-C<libcollectdclient> library). You can only specify one identifier each time you
-run this program (even though L<collectd-unixsock(5)> supports multiple
-identifiers).
+Hostname defaults to the local (non-fully qualified) hostname if omitted. No
+error is returned if the specified identifier does not exist (this is a
+limitation in the C<libcollectdclient> library).
 
-=item B<-t> I<timeout>
+=head1 VALUE-LIST
 
-Only flush values older than I<timeout> seconds.
+A value list describes one data-set as handled by collectd. It is a colon
+(C<:>) separated list of the time and the values. Each value is either given
+as an integer if the data-type is a counter, or as a double if the data-type
+is a gauge value. A literal C<U> is interpreted as an undefined gauge value.
+The number of values and the data-types have to match the type specified in
+the identifier (see L<types.db(5)> for details). The time is specified as
+epoch (i.E<nbsp>e., standard UNIX time) or as a literal C<N> which will be
+interpreted as now.
 
-=item B<-h>
+=head1 EXAMPLES
 
-Display usage information and exit.
+=over 4
+
+=item C<collectdctl flush plugin=rrdtool identifier=somehost/cpu-0/cpu-wait>
+
+Flushes all CPU wait RRD values of the first CPU of the local host.
+I.E<nbsp>e., writes all pending RRD updates of that data-source to disk.
+
+=item C<for ident in `collectdctl listval | grep users/users`; do
+      collectdctl getval $ident;
+  done>
+
+Query the latest number of logged in users on all hosts known to the local
+collectd instance.
 
 =back
 
 =head1 SEE ALSO
 
-L<collectd(1)>
-L<collectd.conf(5)>
-L<collectd-unixsock(5)>
+L<collectd(1)>,
+L<collectd.conf(5)>,
+L<collectd-unixsock(5)>,
+L<types.db(5)>
 
 =head1 AUTHOR
 
+collectd has been written by Florian Forster E<lt>octo at collectd.orgE<gt>
+and many contributors (see `AUTHORS').
+
+collectdctl has been written by
 Håkon J Dugstad Johnsen E<lt>hakon-dugstad.johnsenE<nbsp>atE<nbsp>telenor.comE<gt>
+and Sebastian Harl E<lt>sh at tokkee.orgE<gt>.
 
 =cut