src/collectd-unixsock.pod

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