+=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
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>]
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
projects / collectd.git / blobdiff