NAME
collectd-unixsock - Documentation of collectd's "unixsock plugin"
SYNOPSIS
# See collectd.conf(5)
LoadPlugin unixsock
# ...
<Plugin unixsock>
SocketFile "/path/to/socket"
SocketGroup "collectd"
SocketPerms "0770"
</Plugin>
DESCRIPTION
The "unixsock plugin" opens an UNIX-socket over which one can interact
with the daemon. This can be used to use the values collected by
collectd in other applications, such as monitoring solutions, or submit
externally collected values to collectd.
For example, this plugin is used by collectd-nagios(1) to check if some
value is in a certain range and exit with a Nagios-compatible exit
code.
COMMANDS
Upon start the "unixsock plugin" opens a UNIX-socket and waits for
connections. Once a connection is established the client can send
commands to the daemon which it will answer, if it understand them.
In general the plugin answers with a status line of the following form:
Status Message
If Status is greater than or equal to zero the message indicates
success, if Status is less than zero the message indicates failure.
Message is a human-readable string that further describes the return
value.
On success, Status furthermore indicates the number of subsequent lines
of output (not including the status line). Each such lines usually
contains a single return value. See the description of each command for
details.
The following commands are implemented:
GETVAL Identifier
If the value identified by Identifier (see below) is found the
complete value-list is returned. The response is a list of name-
value-pairs, each pair on its own line (the number of lines is
indicated by the status line - see above). Each name-value-pair is
of the form name=value. Counter-values are converted to a rate,
e. g. bytes per second. Undefined values are returned as NaN.
Example:
-> | GETVAL myhost/cpu-0/cpu-user
<- | 1 Value found
<- | value=1.260000e+00
LISTVAL
Returns a list of the values available in the value cache together
with the time of the last update, so that querying applications can
issue a GETVAL command for the values that have changed. Each
return value consists of the update time as an epoch value and the
identifier, separated by a space. The update time is the time of
the last value, as provided by the collecting instance and may be
very different from the time the server considers to be "now".
Example:
-> | LISTVAL
<- | 69 Values found
<- | 1182204284 myhost/cpu-0/cpu-idle
<- | 1182204284 myhost/cpu-0/cpu-nice
<- | 1182204284 myhost/cpu-0/cpu-system
<- | 1182204284 myhost/cpu-0/cpu-user
...
PUTVAL Identifier [OptionList] Valuelist
Submits one or more values (identified by Identifier, see below) to
the daemon which will dispatch it to all it's write-plugins.
An Identifier is of the form "host/plugin-instance/type-instance"
with both instance-parts being optional. If they're omitted the
hyphen must be omitted, too. plugin and each instance-part may be
chosen freely as long as the tuple (plugin, plugin instance, type
instance) uniquely identifies the plugin within collectd. type
identifies the type and number of values (i. e. data-set) passed to
collectd. A large list of predefined data-sets is available in the
types.db file.
The OptionList is an optional list of Options, where each option is
a key-value-pair. A list of currently understood options can be
found below, all other options will be ignored. Values that contain
spaces must be quoted with double quotes.
Valuelist is a colon-separated list of the time and the values,
each either an integer if the data-source is a counter, or a double
if the data-source is of type "gauge". You can submit an undefined
gauge-value by using U. When submitting U to a counter the behavior
is undefined. The time is given as epoch (i. e. standard UNIX
time).
You can mix options and values, but the order is important: Options
only effect following values, so specifying an option as last field
is allowed, but useless. Also, an option applies to all following
values, so you don't need to re-set an option over and over again.
The currently defined Options are:
interval=seconds
Gives the interval in which the data identified by Identifier
is being collected.
Please note that this is the same format as used in the exec
plugin, see collectd-exec(5).
Example:
-> | PUTVAL testhost/interface/if_octets-test0 interval=10
1179574444:123:456
<- | 0 Success
PUTNOTIF [OptionList] message=Message
Submits a notification to the daemon which will then dispatch it to
all plugins which have registered for receiving notifications.
The PUTNOTIF command is followed by a list of options which further
describe the notification. The message option is special in that it
will consume the rest of the line as its value. The message,
severity, and time options are mandatory.
Valid options are:
message=Message (REQUIRED)
Sets the message of the notification. This is the message that
will be made accessible to the user, so it should contain some
useful information. As with all options: If the message
includes spaces, it must be quoted with double quotes. This
option is mandatory.
severity=failure|warning|okay (REQUIRED)
Sets the severity of the notification. This option is
mandatory.
time=Time (REQUIRED)
Sets the time of the notification. The time is given as
"epoch", i. e. as seconds since January 1st, 1970, 00:00:00.
This option is mandatory.
host=Hostname
plugin=Plugin
plugin_instance=Plugin-Instance
type=Type
type_instance=Type-Instance
These "associative" options establish a relation between this
notification and collected performance data. This connection is
purely informal, i. e. the daemon itself doesn't do anything
with this information. However, websites or GUIs may use this
information to place notifications near the affected graph or
table. All the options are optional, but plugin_instance
without plugin or type_instance without type doesn't make much
sense and should be avoided.
Please note that this is the same format as used in the exec
plugin, see collectd-exec(5).
Example:
-> | PUTNOTIF type=temperature severity=warning time=1201094702
message=The roof is on fire!
<- | 0 Success
FLUSH [timeout=Timeout] [plugin=Plugin [...]] [identifier=Ident [...]]
Flushes all cached data older than Timeout seconds. If no timeout
has been specified, it defaults to -1 which causes all data to be
flushed.
If the plugin option has been specified, only the Plugin plugin
will be flushed. You can have multiple plugin options to flush
multiple plugins in one go. If the plugin option is not given all
plugins providing a flush callback will be flushed.
If the identifier option is given only the specified values will be
flushed. This is meant to be used by graphing or displaying
frontends which want to have the latest values for a specific
graph. Again, you can specify the identifier option multiple times
to flush several values. If this option is not specified at all,
all values will be flushed.
Example:
-> | FLUSH plugin=rrdtool identifier=localhost/df/df-root
identifier=localhost/df/df-var
<- | 0 Done: 2 successful, 0 errors
Identifiers
Value or value-lists are identified in a uniform fashion:
Hostname/Plugin/Type
Where Plugin and Type are both either of type "Name" or
"Name-Instance". If the identifier includes spaces, it must be quoted
using double quotes. This sounds more complicated than it is, so here
are some examples:
myhost/cpu-0/cpu-user
myhost/load/load
myhost/memory/memory-used
myhost/disk-sda/disk_octets
"myups/snmp/temperature-Outlet 1"
ABSTRACTION LAYER
collectd ships the Perl-Module Collectd::Unixsock which provides an
abstraction layer over the actual socket connection. It can be found in
the directory bindings/perl/ in the source distribution or (usually)
somewhere near /usr/share/perl5/ if you're using a package. If you want
to use Perl to communicate with the daemon, you're encouraged to use
and expand this module.
SEE ALSO
collectd(1), collectd.conf(5), collectd-nagios(1), unix(7)
AUTHOR
Florian Forster <octo@verplant.org>