src/collectdctl.pod

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