table of contents
other versions
- wheezy 5.1.0-3
- jessie 5.4.1-6+deb8u1
- jessie-backports 5.7.0-3~bpo8+1
- testing 5.7.1-1.1
- unstable 5.7.1-1.1
COLLECTD-UNIXSOCK(5) | collectd | COLLECTD-UNIXSOCK(5) |
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.
-> | 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".
-> | 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.
- interval=seconds
- Gives the interval in which the data identified by Identifier is being collected.
-> | 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.
- 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.
-> | 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.
-> | 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>2012-04-02 | 5.1.0 |