| 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 |