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     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 it's 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 =back
 124
 125 Please note that this is the same format as used in the B<exec plugin>, see
 126 L<collectd-exec(5)>.
 127
 128 Example:
 129   -> | PUTVAL testhost/interface/if_octets-test0 interval=10 1179574444:123:456
 130   <- | 0 Success
 131
 132 =item B<PUTNOTIF> [I<OptionList>] B<message=>I<Message>
 133
 134 Submits a notification to the daemon which will then dispatch it to all plugins
 135 which have registered for receiving notifications.
 136
 137 The B<PUTNOTIF> command is followed by a list of options which further describe
 138 the notification. The B<message> option is special in that it will consume the
 139 rest of the line as its value. The B<message>, B<severity>, and B<time> options
 140 are mandatory.
 141
 142 Valid options are:
 143
 144 =over 4
 145
 146 =item B<message=>I<Message> (B<REQUIRED>)
 147
 148 Sets the message of the notification. This is the message that will be made
 149 accessible to the user, so it should contain some useful information. As with
 150 all options: If the message includes spaces, it must be quoted with double
 151 quotes. This option is mandatory.
 152
 153 =item B<severity=failure>|B<warning>|B<okay> (B<REQUIRED>)
 154
 155 Sets the severity of the notification. This option is mandatory.
 156
 157 =item B<time=>I<Time> (B<REQUIRED>)
 158
 159 Sets the time of the notification. The time is given as "epoch", i.E<nbsp>e. as
 160 seconds since January 1st, 1970, 00:00:00. This option is mandatory.
 161
 162 =item B<host=>I<Hostname>
 163
 164 =item B<plugin=>I<Plugin>
 165
 166 =item B<plugin_instance=>I<Plugin-Instance>
 167
 168 =item B<type=>I<Type>
 169
 170 =item B<type_instance=>I<Type-Instance>
 171
 172 These "associative" options establish a relation between this notification and
 173 collected performance data. This connection is purely informal, i.E<nbsp>e. the
 174 daemon itself doesn't do anything with this information. However, websites or
 175 GUIs may use this information to place notifications near the affected graph or
 176 table. All the options are optional, but B<plugin_instance> without B<plugin>
 177 or B<type_instance> without B<type> doesn't make much sense and should be
 178 avoided.
 179
 180 Please note that this is the same format as used in the B<exec plugin>, see
 181 L<collectd-exec(5)>.
 182
 183 =back
 184
 185 Example:
 186   -> | PUTNOTIF type=temperature severity=warning time=1201094702 message=The roof is on fire!
 187   <- | 0 Success
 188
 189 =item B<FLUSH> [B<timeout=>I<Timeout>] [B<plugin=>I<Plugin> [...]] [B<identifier=>I<Ident> [...]]
 190
 191 Flushes all cached data older than I<Timeout> seconds. If no timeout has been
 192 specified, it defaults to -1 which causes all data to be flushed.
 193
 194 If the B<plugin> option has been specified, only the I<Plugin> plugin will be
 195 flushed. You can have multiple B<plugin> options to flush multiple plugins in
 196 one go. If the B<plugin> option is not given all plugins providing a flush
 197 callback will be flushed.
 198
 199 If the B<identifier> option is given only the specified values will be flushed.
 200 This is meant to be used by graphing or displaying frontends which want to have
 201 the latest values for a specific graph. Again, you can specify the
 202 B<identifier> option multiple times to flush several values. If this option is
 203 not specified at all, all values will be flushed.
 204
 205 Example:
 206   -> | FLUSH plugin=rrdtool identifier=localhost/df/df-root identifier=localhost/df/df-var
 207   <- | 0 Done: 2 successful, 0 errors
 208
 209 =back
 210
 211 =head2 Identifiers
 212
 213 Value or value-lists are identified in a uniform fashion:
 214
 215 I<Hostname>/I<Plugin>/I<Type>
 216
 217 Where I<Plugin> and I<Type> are both either of type "I<Name>" or
 218 "I<Name>-I<Instance>". If the identifier includes spaces, it must be quoted
 219 using double quotes. This sounds more complicated than it is, so here are
 220 some examples:
 221
 222   myhost/cpu-0/cpu-user
 223   myhost/load/load
 224   myhost/memory/memory-used
 225   myhost/disk-sda/disk_octets
 226   "myups/snmp/temperature-Outlet 1"
 227
 228 =head1 ABSTRACTION LAYER
 229
 230 B<collectd> ships the Perl-Module L<Collectd::Unixsock> which
 231 provides an abstraction layer over the actual socket connection. It can be
 232 found in the directory F<bindings/perl/> in the source distribution or
 233 (usually) somewhere near F</usr/share/perl5/> if you're using a package. If
 234 you want to use Perl to communicate with the daemon, you're encouraged to use
 235 and expand this module.
 236
 237 =head1 SEE ALSO
 238
 239 L<collectd(1)>,
 240 L<collectd.conf(5)>,
 241 L<collectd-nagios(1)>,
 242 L<unix(7)>
 243
 244 =head1 AUTHOR
 245
 246 Florian Forster E<lt>octo@verplant.orgE<gt>
 247
 248 =cut