=head1 NAME

collectdctl - Control interface for collectd

=head1 SYNOPSIS

collectdctl I<[options]> I<E<lt>commandE<gt>> I<[command options]>

=head1 DESCRIPTION

collectdctl provides a control interface for collectd, which may be used to
interact with the daemon using the C<unixsock plugin>.

=head1 OPTIONS

collectdctl supports the following options:

=over 4

=item B<-s> I<socket>

Path to the UNIX socket opened by collectd's C<unixsock plugin>.
Default: /var/run/collectd-unixsock

=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>>

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.

Example: B<rrdtool>.

=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).

=item B<show> [I<E<lt>SelectionE<gt>>] [I<E<lt>AggregationE<gt>> I<E<lt>GroupingE<gt>>]
[I<E<lt>FormatE<gt>>]

Show values or an aggregation of values. The I<Selection> selects which values
to show. The selection consists of the five options B<host>, B<plugin>,
B<plugin_instance>, B<type> and B<type_instance> which take a regular
expression each. The regular expressions are passed on to the C<LISTVAL>
command so they will behave exactly as documented in L<collectd-unixsock(5)>.

Example: Show CPU statistics only.

    collectdctl show plugin="^cpu$" type="^cpu$"

If you're not interested in single values, but aggregations of values, you can
use the I<Aggregation> and I<Grouping> options to get an overview over your
system(s) and such. The two options to this effect are:

=over 4

=item B<aggregate=>I<aggr>[B<,>I<aggr>[...]]

List all the aggregation functions that shall be used to combine multiple
values. Available aggregation functions are:

=over 4

=item B<count>

Number of non-NAN values. This value may be zero if all individual values are
NAN.

=item B<min>

Minimum value.

=item B<max>

Maximum value.

=item B<avg>

Average of all values.

=item B<sum>

Sum of all values.

=item B<sdev>

Standard deviation of all non-NAN values. The standard deviation is NAN if
there were no non-NAN values (B<count> reportsE<nbsp>0) and zero if there was
exactly one non-NAN value.

=back

=item B<group=>I<field>[B<,>I<field>[...]]

Chose the fields of the I<identifier> you want to group values by. Valid
I<fields> are B<host>, B<plugin>, B<plugin_instance>, B<type> and
B<type_instance>. In 99E<nbsp>% of all cases, you want to make sure all values
have the same I<type> -- either by using a construct like C<type='^foo$'>
or by adding B<type> to the B<group> option (e.g. C<group=type>).

=back

The output formatting may be specified using the B<format=>I<format> option.
The following formats are available:

=over 4

=item B<table> (default)

Output an aligned table formatted using ASCII characters.

=item B<latex>

Output a table intended to be included in a LaTeX document. This is not a
complete document. In order to compile the document, you have to have a
complete document wrapper.

=back

Example: Print the minimum, average and maximum time spent in each CPU state
for all your web servers:

    collectdctl show host="^www[0-9]\\." plugin="^cpu$" type="^cpu$" aggregate=min,avg,max group=type_instance

=back

=head1 IDENTIFIERS

An identifier has the following format:

[I<hostname>/]I<plugin>[-I<plugin_instance>]/I<type>[-I<type_instance>]

Examples:
 somehost/cpu-0/cpu-idle
 uptime/uptime
 otherhost/memory/memory-used

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).

=head1 VALUE-LIST

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.

=head1 EXAMPLES

=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<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>,
Sebastian Harl E<lt>sh at tokkee.orgE<gt> and
Florian Forster E<lt>octo at collectd.orgE<gt>.

=cut