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