Debian Codegraph @

src/collectd-unixsock.pod

raw
1 =encoding UTF-8
2
3 =head1 NAME
4
5 collectd-unixsock - Documentation of collectd's C<unixsock plugin>
6
7 =head1 SYNOPSIS
8
9 # See collectd.conf(5)
10 LoadPlugin unixsock
11 # ...
12 <Plugin unixsock>
13 SocketFile "/path/to/socket"
14 SocketGroup "collectd"
15 SocketPerms "0770"
16 DeleteSocket false
17 </Plugin>
18
19 =head1 DESCRIPTION
20
21 The C<unixsock plugin> opens an UNIX-socket over which one can interact with
22 the daemon. This can be used to use the values collected by collectd in other
23 applications, such as monitoring solutions, or submit externally collected
24 values to collectd.
25
26 For example, this plugin is used by L<collectd-nagios(1)> to check if some
27 value is in a certain range and exit with a Nagios-compatible exit code.
28
29 =head1 COMMANDS
30
31 Upon start the C<unixsock plugin> opens a UNIX-socket and waits for
32 connections. Once a connection is established the client can send commands to
33 the daemon which it will answer, if it understand them.
34
35 In general the plugin answers with a status line of the following form:
36
37 I<Status> I<Message>
38
39 If I<Status> is greater than or equal to zero the message indicates success,
40 if I<Status> is less than zero the message indicates failure. I<Message> is a
41 human-readable string that further describes the return value.
42
43 On success, I<Status> furthermore indicates the number of subsequent lines of
44 output (not including the status line). Each such lines usually contains a
45 single return value. See the description of each command for details.
46
47 The following commands are implemented:
48
49 =over 4
50
51 =item B<GETVAL> I<Identifier>
52
53 If the value identified by I<Identifier> (see below) is found the complete
54 value-list is returned. The response is a list of name-value-pairs, each pair
55 on its own line (the number of lines is indicated by the status line - see
56 above). Each name-value-pair is of the form I<name>B<=>I<value>.
57 Counter-values are converted to a rate, e.E<nbsp>g. bytes per second.
58 Undefined values are returned as B<NaN>.
59
60 Example:
61 -> | GETVAL myhost/cpu-0/cpu-user
62 <- | 1 Value found
63 <- | value=1.260000e+00
64
65 =item B<LISTVAL>
66
67 Returns a list of the values available in the value cache together with the
68 time of the last update, so that querying applications can issue a B<GETVAL>
69 command for the values that have changed. Each return value consists of the
70 update time as an epoch value and the identifier, separated by a space. The
71 update time is the time of the last value, as provided by the collecting
72 instance and may be very different from the time the server considers to be
73 "now".
74
75 Example:
76 -> | LISTVAL
77 <- | 69 Values found
78 <- | 1182204284 myhost/cpu-0/cpu-idle
79 <- | 1182204284 myhost/cpu-0/cpu-nice
80 <- | 1182204284 myhost/cpu-0/cpu-system
81 <- | 1182204284 myhost/cpu-0/cpu-user
82 ...
83
84 =item B<PUTVAL> I<Identifier> [I<OptionList>] I<Valuelist>
85
86 Submits one or more values (identified by I<Identifier>, see below) to the
87 daemon which will dispatch it to all its write-plugins.
88
89 An I<Identifier> is of the form
90 C<I<host>B</>I<plugin>B<->I<instance>B</>I<type>B<->I<instance>> with both
91 I<instance>-parts being optional. If they're omitted the hyphen must be
92 omitted, too. I<plugin> and each I<instance>-part may be chosen freely as long
93 as the tuple (plugin, plugin instance, type instance) uniquely identifies the
94 plugin within collectd. I<type> identifies the type and number of values
95 (i.E<nbsp>e. data-set) passed to collectd. A large list of predefined
96 data-sets is available in the B<types.db> file.
97
98 The I<OptionList> is an optional list of I<Options>, where each option is a
99 key-value-pair. A list of currently understood options can be found below, all
100 other options will be ignored. Values that contain spaces must be quoted with
101 double quotes.
102
103 I<Valuelist> is a colon-separated list of the time and the values, each either
104 an integer if the data-source is a counter, or a double if the data-source is
105 of type "gauge". You can submit an undefined gauge-value by using B<U>. When
106 submitting B<U> to a counter the behavior is undefined. The time is given as
107 epoch (i.E<nbsp>e. standard UNIX time).
108
109 You can mix options and values, but the order is important: Options only
110 effect following values, so specifying an option as last field is allowed, but
111 useless. Also, an option applies to B<all> following values, so you don't need
112 to re-set an option over and over again.
113
114 The currently defined B<Options> are:
115
116 =over 4
117
118 =item B<interval=>I<seconds>
119
120 Gives the interval in which the data identified by I<Identifier> is being
121 collected.
122
123 =item meta:B<key>=I<value>
124
125 Add meta data with the key B<key> and the value I<value>.
126
127 =back
128
129 Please note that this is the same format as used in the B<exec plugin>, see
130 L<collectd-exec(5)>.
131
132 Example:
133 -> | PUTVAL testhost/interface/if_octets-test0 interval=10 1179574444:123:456
134 <- | 0 Success
135
136 =item B<PUTNOTIF> [I<OptionList>] B<message=>I<Message>
137
138 Submits a notification to the daemon which will then dispatch it to all plugins
139 which have registered for receiving notifications.
140
141 The B<PUTNOTIF> command is followed by a list of options which further describe
142 the notification. The B<message> option is special in that it will consume the
143 rest of the line as its value. The B<message>, B<severity>, and B<time> options
144 are mandatory.
145
146 Valid options are:
147
148 =over 4
149
150 =item B<message=>I<Message> (B<REQUIRED>)
151
152 Sets the message of the notification. This is the message that will be made
153 accessible to the user, so it should contain some useful information. As with
154 all options: If the message includes spaces, it must be quoted with double
155 quotes. This option is mandatory.
156
157 =item B<severity=failure>|B<warning>|B<okay> (B<REQUIRED>)
158
159 Sets the severity of the notification. This option is mandatory.
160
161 =item B<time=>I<Time> (B<REQUIRED>)
162
163 Sets the time of the notification. The time is given as "epoch", i.E<nbsp>e. as
164 seconds since January 1st, 1970, 00:00:00. This option is mandatory.
165
166 =item B<host=>I<Hostname>
167
168 =item B<plugin=>I<Plugin>
169
170 =item B<plugin_instance=>I<Plugin-Instance>
171
172 =item B<type=>I<Type>
173
174 =item B<type_instance=>I<Type-Instance>
175
176 These "associative" options establish a relation between this notification and
177 collected performance data. This connection is purely informal, i.E<nbsp>e. the
178 daemon itself doesn't do anything with this information. However, websites or
179 GUIs may use this information to place notifications near the affected graph or
180 table. All the options are optional, but B<plugin_instance> without B<plugin>
181 or B<type_instance> without B<type> doesn't make much sense and should be
182 avoided.
183
184 =item B<type:key=>I<value>
185
186 Sets user defined meta information. The B<type> key is a single character
187 defining the type of the meta information.
188
189 The current supported types are:
190
191 =over 8
192
193 =item B<s> A string passed as-is.
194
195 =back
196
197 =back
198
199 Please note that this is the same format as used in the B<exec plugin>, see
200 L<collectd-exec(5)>.
201
202 Example:
203 -> | PUTNOTIF type=temperature severity=warning time=1201094702 message=The roof is on fire!
204 <- | 0 Success
205
206 =item B<FLUSH> [B<timeout=>I<Timeout>] [B<plugin=>I<Plugin> [...]] [B<identifier=>I<Ident> [...]]
207
208 Flushes all cached data older than I<Timeout> seconds. If no timeout has been
209 specified, it defaults to -1 which causes all data to be flushed.
210
211 If the B<plugin> option has been specified, only the I<Plugin> plugin will be
212 flushed. You can have multiple B<plugin> options to flush multiple plugins in
213 one go. If the B<plugin> option is not given all plugins providing a flush
214 callback will be flushed.
215
216 If the B<identifier> option is given only the specified values will be flushed.
217 This is meant to be used by graphing or displaying frontends which want to have
218 the latest values for a specific graph. Again, you can specify the
219 B<identifier> option multiple times to flush several values. If this option is
220 not specified at all, all values will be flushed.
221
222 Example:
223 -> | FLUSH plugin=rrdtool identifier=localhost/df/df-root identifier=localhost/df/df-var
224 <- | 0 Done: 2 successful, 0 errors
225
226 =back
227
228 =head2 Identifiers
229
230 Value or value-lists are identified in a uniform fashion:
231
232 I<Hostname>/I<Plugin>/I<Type>
233
234 Where I<Plugin> and I<Type> are both either of type "I<Name>" or
235 "I<Name>-I<Instance>". If the identifier includes spaces, it must be quoted
236 using double quotes. This sounds more complicated than it is, so here are
237 some examples:
238
239 myhost/cpu-0/cpu-user
240 myhost/load/load
241 myhost/memory/memory-used
242 myhost/disk-sda/disk_octets
243 "myups/snmp/temperature-Outlet 1"
244
245 =head1 ABSTRACTION LAYER
246
247 B<collectd> ships the Perl-Module L<Collectd::Unixsock> which
248 provides an abstraction layer over the actual socket connection. It can be
249 found in the directory F<bindings/perl/> in the source distribution or
250 (usually) somewhere near F</usr/share/perl5/> if you're using a package. If
251 you want to use Perl to communicate with the daemon, you're encouraged to use
252 and expand this module.
253
254 =head1 SEE ALSO
255
256 L<collectd(1)>,
257 L<collectd.conf(5)>,
258 L<collectd-nagios(1)>,
259 L<unix(7)>
260
261 =head1 AUTHOR
262
263 Florian Forster E<lt>[email protected]<gt>
264
265 =cut