5 collectd-unixsock - Documentation of collectd's C<unixsock plugin>
13 SocketFile "/path/to/socket"
14 SocketGroup "collectd"
20 The C<unixsock plugin> opens an UNIX-socket over which one can interact with
21 the daemon. This can be used to use the values collected by collectd in other
22 applications, such as monitoring solutions, or submit externally collected
25 For example, this plugin is used by L<collectd-nagios(1)> to check if some
26 value is in a certain range and exit with a Nagios-compatible exit code.
30 Upon start the C<unixsock plugin> opens a UNIX-socket and waits for
31 connections. Once a connection is established the client can send commands to
32 the daemon which it will answer, if it understand them.
34 In general the plugin answers with a status line of the following form:
38 If I<Status> is greater than or equal to zero the message indicates success,
39 if I<Status> is less than zero the message indicates failure. I<Message> is a
40 human-readable string that further describes the return value.
42 On success, I<Status> furthermore indicates the number of subsequent lines of
43 output (not including the status line). Each such lines usually contains a
44 single return value. See the description of each command for details.
46 The following commands are implemented:
50 =item B<GETVAL> I<Identifier>
52 If the value identified by I<Identifier> (see below) is found the complete
53 value-list is returned. The response is a list of name-value-pairs, each pair
54 on its own line (the number of lines is indicated by the status line - see
55 above). Each name-value-pair is of the form I<name>B<=>I<value>.
56 Counter-values are converted to a rate, e.E<nbsp>g. bytes per second.
57 Undefined values are returned as B<NaN>.
60 -> | GETVAL myhost/cpu-0/cpu-user
62 <- | value=1.260000e+00
64 =item B<LISTVAL> [I<OptionList>]
66 Returns a list of the values available in the value cache together with the
67 time of the last update, so that querying applications can issue a B<GETVAL>
68 command for the values that have changed. Each return value consists of the
69 update time as an epoch value and the identifier, separated by a space. The
70 update time is the time of the last value, as provided by the collecting
71 instance and may be very different from the time the server considers to be
77 <- | 1182204284 myhost/cpu-0/cpu-idle
78 <- | 1182204284 myhost/cpu-0/cpu-nice
79 <- | 1182204284 myhost/cpu-0/cpu-system
80 <- | 1182204284 myhost/cpu-0/cpu-user
83 Valid options are B<host>, B<plugin>, B<plugin_instance>, B<type> and
84 B<type_instance>. Each option takes a regular expression as its argument. If at
85 least one regular expression is supplied, only values where each appropriate
86 part of the identifier satisfies the given regular expression are returned.
89 -> | LISTVAL plugin_instance="^$"
90 <- | 5 Matching values
91 <- | 1300311250.802 myhost/load/load
92 <- | 1300311250.802 myhost/memory/memory-buffered
93 <- | 1300311250.802 myhost/memory/memory-cached
94 <- | 1300311250.804 myhost/memory/memory-free
95 <- | 1300311250.802 myhost/memory/memory-used
97 Regular expressions follow the I<Extended Regular Expression> syntax (ERE)
98 described in L<regex(7)> and will match case-sensitive. It is recommended to
99 enclose the regular expression in double quotes. Please note that you will
100 need to escape the backslash and double quote characters in this case. To
101 request all values from hosts with the German top level domain ".de", for
103 LISTVAL host="\\.de$"
105 =item B<PUTVAL> I<Identifier> [I<OptionList>] I<Valuelist>
107 Submits one or more values (identified by I<Identifier>, see below) to the
108 daemon which will dispatch it to all it's write-plugins.
110 An I<Identifier> is of the form
111 C<I<host>B</>I<plugin>B<->I<instance>B</>I<type>B<->I<instance>> with both
112 I<instance>-parts being optional. If they're omitted the hyphen must be
113 omitted, too. I<plugin> and each I<instance>-part may be chosen freely as long
114 as the tuple (plugin, plugin instance, type instance) uniquely identifies the
115 plugin within collectd. I<type> identifies the type and number of values
116 (i.E<nbsp>e. data-set) passed to collectd. A large list of predefined
117 data-sets is available in the B<types.db> file.
119 The I<OptionList> is an optional list of I<Options>, where each option is a
120 key-value-pair. A list of currently understood options can be found below, all
121 other options will be ignored. Values that contain spaces must be quoted with
124 I<Valuelist> is a colon-separated list of the time and the values, each either
125 an integer if the data-source is a counter, or a double if the data-source is
126 of type "gauge". You can submit an undefined gauge-value by using B<U>. When
127 submitting B<U> to a counter the behavior is undefined. The time is given as
128 epoch (i.E<nbsp>e. standard UNIX time).
130 You can mix options and values, but the order is important: Options only
131 effect following values, so specifying an option as last field is allowed, but
132 useless. Also, an option applies to B<all> following values, so you don't need
133 to re-set an option over and over again.
135 The currently defined B<Options> are:
139 =item B<interval=>I<seconds>
141 Gives the interval in which the data identified by I<Identifier> is being
146 Please note that this is the same format as used in the B<exec plugin>, see
150 -> | PUTVAL testhost/interface/if_octets-test0 interval=10 1179574444:123:456
153 =item B<PUTNOTIF> [I<OptionList>] B<message=>I<Message>
155 Submits a notification to the daemon which will then dispatch it to all plugins
156 which have registered for receiving notifications.
158 The B<PUTNOTIF> command is followed by a list of options which further describe
159 the notification. The B<message> option is special in that it will consume the
160 rest of the line as its value. The B<message>, B<severity>, and B<time> options
167 =item B<message=>I<Message> (B<REQUIRED>)
169 Sets the message of the notification. This is the message that will be made
170 accessible to the user, so it should contain some useful information. As with
171 all options: If the message includes spaces, it must be quoted with double
172 quotes. This option is mandatory.
174 =item B<severity=failure>|B<warning>|B<okay> (B<REQUIRED>)
176 Sets the severity of the notification. This option is mandatory.
178 =item B<time=>I<Time> (B<REQUIRED>)
180 Sets the time of the notification. The time is given as "epoch", i.E<nbsp>e. as
181 seconds since January 1st, 1970, 00:00:00. This option is mandatory.
183 =item B<host=>I<Hostname>
185 =item B<plugin=>I<Plugin>
187 =item B<plugin_instance=>I<Plugin-Instance>
189 =item B<type=>I<Type>
191 =item B<type_instance=>I<Type-Instance>
193 These "associative" options establish a relation between this notification and
194 collected performance data. This connection is purely informal, i.E<nbsp>e. the
195 daemon itself doesn't do anything with this information. However, websites or
196 GUIs may use this information to place notifications near the affected graph or
197 table. All the options are optional, but B<plugin_instance> without B<plugin>
198 or B<type_instance> without B<type> doesn't make much sense and should be
201 Please note that this is the same format as used in the B<exec plugin>, see
207 -> | PUTNOTIF type=temperature severity=warning time=1201094702 message=The roof is on fire!
210 =item B<FLUSH> [B<timeout=>I<Timeout>] [B<plugin=>I<Plugin> [...]] [B<identifier=>I<Ident> [...]]
212 Flushes all cached data older than I<Timeout> seconds. If no timeout has been
213 specified, it defaults to -1 which causes all data to be flushed.
215 If the B<plugin> option has been specified, only the I<Plugin> plugin will be
216 flushed. You can have multiple B<plugin> options to flush multiple plugins in
217 one go. If the B<plugin> option is not given all plugins providing a flush
218 callback will be flushed.
220 If the B<identifier> option is given only the specified values will be flushed.
221 This is meant to be used by graphing or displaying frontends which want to have
222 the latest values for a specific graph. Again, you can specify the
223 B<identifier> option multiple times to flush several values. If this option is
224 not specified at all, all values will be flushed.
227 -> | FLUSH plugin=rrdtool identifier=localhost/df/df-root identifier=localhost/df/df-var
228 <- | 0 Done: 2 successful, 0 errors
234 Value or value-lists are identified in a uniform fashion:
236 I<Hostname>/I<Plugin>/I<Type>
238 Where I<Plugin> and I<Type> are both either of type "I<Name>" or
239 "I<Name>-I<Instance>". If the identifier includes spaces, it must be quoted
240 using double quotes. This sounds more complicated than it is, so here are
243 myhost/cpu-0/cpu-user
245 myhost/memory/memory-used
246 myhost/disk-sda/disk_octets
247 "myups/snmp/temperature-Outlet 1"
249 =head1 ABSTRACTION LAYER
251 B<collectd> ships the Perl-Module L<Collectd::Unixsock> which
252 provides an abstraction layer over the actual socket connection. It can be
253 found in the directory F<bindings/perl/> in the source distribution or
254 (usually) somewhere near F</usr/share/perl5/> if you're using a package. If
255 you want to use Perl to communicate with the daemon, you're encouraged to use
256 and expand this module.
262 L<collectd-nagios(1)>,
267 Florian Forster E<lt>octo@verplant.orgE<gt>