src/collectd-unixsock.pod

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