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