1=encoding UTF-8 2 3=head1 NAME 4 5collectdctl - Control interface for collectd 6 7=head1 SYNOPSIS 8 9collectdctl I<[options]> I<E<lt>commandE<gt>> I<[command options]> 10 11=head1 DESCRIPTION 12 13collectdctl provides a control interface for collectd, which may be used to 14interact with the daemon using the C<unixsock plugin>. 15 16=head1 OPTIONS 17 18collectdctl supports the following options: 19 20=over 4 21 22=item B<-s> I<socket> 23 24Path to the UNIX socket opened by collectd's C<unixsock plugin>. 25Default: /var/run/collectd-unixsock 26 27=item B<-h> 28 29Display usage information and exit. 30 31=back 32 33=head1 AVAILABLE COMMANDS 34 35The following commands are supported: 36 37=over 4 38 39=item B<getval> I<E<lt>identifierE<gt>> 40 41Query the latest collected value identified by the specified 42I<E<lt>identifierE<gt>> (see below). The value-list associated with that 43data-set is returned as a list of key-value-pairs, each on its own line. Keys 44and values are separated by the equal sign (C<=>). 45 46=item B<flush> [B<timeout=>I<E<lt>secondsE<gt>>] [B<plugin=>I<E<lt>nameE<gt>>] 47[B<identifier=>I<E<lt>idE<gt>>] 48 49Flush the daemon. This is useful, e.E<nbsp>g., to make sure that the latest 50values have been written to the respective RRD file before graphing them or 51copying them to somewhere else. 52 53The following options are supported by the flush command: 54 55=over 4 56 57=item B<timeout=>I<E<lt>secondsE<gt>> 58 59Flush values older than the specified timeout (in seconds) only. 60 61=item B<plugin=>I<E<lt>nameE<gt>> 62 63Flush the specified plugin only. I.E<nbsp>e., data cached by the specified 64plugin is written to disk (or network or whatever), if the plugin supports 65that operation. 66 67Example: B<rrdtool>. 68 69=item B<identifier=>I<E<lt>idE<gt>> 70 71If this option is present, only the data specified by the specified identifier 72(see below) will be flushed. Note that this option is not supported by all 73plugins (e.E<nbsp>g., the C<network> plugin does not support this). 74 75=back 76 77The B<plugin> and B<identifier> options may be specified more than once. In 78that case, all combinations of specified plugins and identifiers will be 79flushed only. 80 81=item B<listval> 82 83Returns a list of all values (by their identifier) available to the 84C<unixsock> plugin. Each value is printed on its own line. I.E<nbsp>e., this 85command returns a list of valid identifiers that may be used with the other 86commands. 87 88=item B<putval> I<E<lt>identifierE<gt>> [B<interval=>I<E<lt>secondsE<gt>>] 89I<E<lt>value-list(s)E<gt>> 90 91Submit one or more values (identified by I<E<lt>identifierE<gt>>, see below) 92to the daemon which will then dispatch them to the write plugins. B<interval> 93specifies the interval (in seconds) used to collect the values following that 94option. It defaults to the default of the running collectd instance receiving 95the data. Multiple I<E<lt>value-list(s)E<gt>> (see below) may be specified. 96Each of them will be submitted to the daemon. The values have to match the 97data-set definition specified by the type as given in the identifier (see 98L<types.db(5)> for details). 99 100=back 101 102=head1 IDENTIFIERS 103 104An identifier has the following format: 105 106[I<hostname>/]I<plugin>[-I<plugin_instance>]/I<type>[-I<type_instance>] 107 108Examples: 109 somehost/cpu-0/cpu-idle 110 uptime/uptime 111 otherhost/memory/memory-used 112 113Hostname defaults to the local (non-fully qualified) hostname if omitted. No 114error is returned if the specified identifier does not exist (this is a 115limitation in the C<libcollectdclient> library). 116 117=head1 VALUE-LIST 118 119A value list describes one data-set as handled by collectd. It is a colon 120(C<:>) separated list of the time and the values. Each value is either given 121as an integer if the data-type is a counter, or as a double if the data-type 122is a gauge value. A literal C<U> is interpreted as an undefined gauge value. 123The number of values and the data-types have to match the type specified in 124the identifier (see L<types.db(5)> for details). The time is specified as 125epoch (i.E<nbsp>e., standard UNIX time) or as a literal C<N> which will be 126interpreted as now. 127 128=head1 EXAMPLES 129 130=over 4 131 132=item C<collectdctl flush plugin=rrdtool identifier=somehost/cpu-0/cpu-wait> 133 134Flushes all CPU wait RRD values of the first CPU of the local host. 135I.E<nbsp>e., writes all pending RRD updates of that data-source to disk. 136 137=item C<for ident in `collectdctl listval | grep users/users`; do 138 collectdctl getval $ident; 139 done> 140 141Query the latest number of logged in users on all hosts known to the local 142collectd instance. 143 144=back 145 146=head1 SEE ALSO 147 148L<collectd(1)>, 149L<collectd.conf(5)>, 150L<collectd-unixsock(5)>, 151L<types.db(5)> 152 153=head1 AUTHOR 154 155collectd has been written by Florian Forster E<lt>octo at collectd.orgE<gt> 156and many contributors (see `AUTHORS'). 157 158collectdctl has been written by 159H�kon J Dugstad Johnsen E<lt>hakon-dugstad.johnsenE<nbsp>atE<nbsp>telenor.comE<gt> 160and Sebastian Harl E<lt>sh at tokkee.orgE<gt>. 161 162=cut 163