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 solutions, or submit externally collected
  21 values to collectd.
  22
  23 For example, this plugin is used by L<collectd-nagios(1)> to check if some
  24 value is in a 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> [I<OptionList>]
  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 Valid options are B<host>, B<plugin>, B<plugin_instance>, B<type> and
  82 B<type_instance>. Each option takes a regular expression as its argument. If at
  83 least one regular expression is supplied, only values where each appropriate
  84 part of the identifier satisfies the given regular expression are returned.
  85
  86 Example:
  87   -> | LISTVAL plugin_instance="^$"
  88   <- | 5 Matching values
  89   <- | 1300311250.802 myhost/load/load
  90   <- | 1300311250.802 myhost/memory/memory-buffered
  91   <- | 1300311250.802 myhost/memory/memory-cached
  92   <- | 1300311250.804 myhost/memory/memory-free
  93   <- | 1300311250.802 myhost/memory/memory-used
  94
  95 Regular expressions follow the I<Extended Regular Expression> syntax (ERE)
  96 described in L<regex(7)> and will match case-sensitive. It is recommended to
  97 enclose the regular expression in double quotes. Please note that you will
  98 need to escape the backslash and double quote characters in this case. To
  99 request all values from hosts with the German top level domain ".de", for
 100 example, use:
 101   LISTVAL host="\\.de$"
 102
 103 =item B<PUTVAL> I<Identifier> [I<OptionList>] I<Valuelist>
 104
 105 Submits one or more values (identified by I<Identifier>, see below) to the
 106 daemon which will dispatch it to all it's write-plugins.
 107
 108 An I<Identifier> is of the form
 109 C<I<host>B</>I<plugin>B<->I<instance>B</>I<type>B<->I<instance>> with both
 110 I<instance>-parts being optional. If they're omitted the hyphen must be
 111 omitted, too. I<plugin> and each I<instance>-part may be chosen freely as long
 112 as the tuple (plugin, plugin instance, type instance) uniquely identifies the
 113 plugin within collectd. I<type> identifies the type and number of values
 114 (i.E<nbsp>e. data-set) passed to collectd. A large list of predefined
 115 data-sets is available in the B<types.db> file.
 116
 117 The I<OptionList> is an optional list of I<Options>, where each option is a
 118 key-value-pair. A list of currently understood options can be found below, all
 119 other options will be ignored. Values that contain spaces must be quoted with
 120 double quotes.
 121
 122 I<Valuelist> is a colon-separated list of the time and the values, each either
 123 an integer if the data-source is a counter, or a double if the data-source is
 124 of type "gauge". You can submit an undefined gauge-value by using B<U>. When
 125 submitting B<U> to a counter the behavior is undefined. The time is given as
 126 epoch (i.E<nbsp>e. standard UNIX time).
 127
 128 You can mix options and values, but the order is important: Options only
 129 effect following values, so specifying an option as last field is allowed, but
 130 useless. Also, an option applies to B<all> following values, so you don't need
 131 to re-set an option over and over again.
 132
 133 The currently defined B<Options> are:
 134
 135 =over 4
 136
 137 =item B<interval=>I<seconds>
 138
 139 Gives the interval in which the data identified by I<Identifier> is being
 140 collected.
 141
 142 =back
 143
 144 Please note that this is the same format as used in the B<exec plugin>, see
 145 L<collectd-exec(5)>.
 146
 147 Example:
 148   -> | PUTVAL testhost/interface/if_octets-test0 interval=10 1179574444:123:456
 149   <- | 0 Success
 150
 151 =item B<PUTNOTIF> [I<OptionList>] B<message=>I<Message>
 152
 153 Submits a notification to the daemon which will then dispatch it to all plugins
 154 which have registered for receiving notifications.
 155
 156 The B<PUTNOTIF> command is followed by a list of options which further describe
 157 the notification. The B<message> option is special in that it will consume the
 158 rest of the line as its value. The B<message>, B<severity>, and B<time> options
 159 are mandatory.
 160
 161 Valid options are:
 162
 163 =over 4
 164
 165 =item B<message=>I<Message> (B<REQUIRED>)
 166
 167 Sets the message of the notification. This is the message that will be made
 168 accessible to the user, so it should contain some useful information. As with
 169 all options: If the message includes spaces, it must be quoted with double
 170 quotes. This option is mandatory.
 171
 172 =item B<severity=failure>|B<warning>|B<okay> (B<REQUIRED>)
 173
 174 Sets the severity of the notification. This option is mandatory.
 175
 176 =item B<time=>I<Time> (B<REQUIRED>)
 177
 178 Sets the time of the notification. The time is given as "epoch", i.E<nbsp>e. as
 179 seconds since January 1st, 1970, 00:00:00. This option is mandatory.
 180
 181 =item B<host=>I<Hostname>
 182
 183 =item B<plugin=>I<Plugin>
 184
 185 =item B<plugin_instance=>I<Plugin-Instance>
 186
 187 =item B<type=>I<Type>
 188
 189 =item B<type_instance=>I<Type-Instance>
 190
 191 These "associative" options establish a relation between this notification and
 192 collected performance data. This connection is purely informal, i.E<nbsp>e. the
 193 daemon itself doesn't do anything with this information. However, websites or
 194 GUIs may use this information to place notifications near the affected graph or
 195 table. All the options are optional, but B<plugin_instance> without B<plugin>
 196 or B<type_instance> without B<type> doesn't make much sense and should be
 197 avoided.
 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 =back
 203
 204 Example:
 205   -> | PUTNOTIF type=temperature severity=warning time=1201094702 message=The roof is on fire!
 206   <- | 0 Success
 207
 208 =item B<FLUSH> [B<timeout=>I<Timeout>] [B<plugin=>I<Plugin> [...]] [B<identifier=>I<Ident> [...]]
 209
 210 Flushes all cached data older than I<Timeout> seconds. If no timeout has been
 211 specified, it defaults to -1 which causes all data to be flushed.
 212
 213 If the B<plugin> option has been specified, only the I<Plugin> plugin will be
 214 flushed. You can have multiple B<plugin> options to flush multiple plugins in
 215 one go. If the B<plugin> option is not given all plugins providing a flush
 216 callback will be flushed.
 217
 218 If the B<identifier> option is given only the specified values will be flushed.
 219 This is meant to be used by graphing or displaying frontends which want to have
 220 the latest values for a specific graph. Again, you can specify the
 221 B<identifier> option multiple times to flush several values. If this option is
 222 not specified at all, all values will be flushed.
 223
 224 Example:
 225   -> | FLUSH plugin=rrdtool identifier=localhost/df/df-root identifier=localhost/df/df-var
 226   <- | 0 Done: 2 successful, 0 errors
 227
 228 =back
 229
 230 =head2 Identifiers
 231
 232 Value or value-lists are identified in a uniform fashion:
 233
 234 I<Hostname>/I<Plugin>/I<Type>
 235
 236 Where I<Plugin> and I<Type> are both either of type "I<Name>" or
 237 "I<Name>-I<Instance>". If the identifier includes spaces, it must be quoted
 238 using double quotes. This sounds more complicated than it is, so here are
 239 some examples:
 240
 241   myhost/cpu-0/cpu-user
 242   myhost/load/load
 243   myhost/memory/memory-used
 244   myhost/disk-sda/disk_octets
 245   "myups/snmp/temperature-Outlet 1"
 246
 247 =head1 ABSTRACTION LAYER
 248
 249 B<collectd> ships the Perl-Module L<Collectd::Unixsock> which
 250 provides an abstraction layer over the actual socket connection. It can be
 251 found in the directory F<bindings/perl/> in the source distribution or
 252 (usually) somewhere near F</usr/share/perl5/> if you're using a package. If
 253 you want to use Perl to communicate with the daemon, you're encouraged to use
 254 and expand this module.
 255
 256 =head1 SEE ALSO
 257
 258 L<collectd(1)>,
 259 L<collectd.conf(5)>,
 260 L<collectd-nagios(1)>,
 261 L<unix(7)>
 262
 263 =head1 AUTHOR
 264
 265 Florian Forster E<lt>octo@verplant.orgE<gt>
 266
 267 =cut