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