Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help

       collectd-unixsock - Documentation of collectd's "unixsock plugin"

	 # See collectd.conf(5)
	 LoadPlugin unixsock
	 # ...
	 <Plugin unixsock>
	   SocketFile "/path/to/socket"
	   SocketGroup "collectd"
	   SocketPerms "0770"
	   DeleteSocket	false

       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

       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

       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

       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

	   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 its	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

	   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:

	       Gives the interval in which the data identified by Identifier
	       is being	collected.

	       Add meta	data with the key key and the value value.

	   Please note that this is the	same format as used in the exec
	   plugin, see collectd-exec(5).

	     ->	| PUTVAL testhost/interface/if_octets-test0 interval=10
	     <-	| 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

	   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.

	       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.

	       Sets user defined meta information. The type key	is a single
	       character defining the type of the meta information.

	       The current supported types are:

	       s A string passed as-is.

	   Please note that this is the	same format as used in the exec
	   plugin, see collectd-exec(5).

	     ->	| 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

	   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.

	     ->	| FLUSH	plugin=rrdtool identifier=localhost/df/df-root
	     <-	| 0 Done: 2 successful,	0 errors

       Value or	value-lists are	identified in a	uniform	fashion:


       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:

	 "myups/snmp/temperature-Outlet	1"

       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.

       collectd(1), collectd.conf(5), collectd-nagios(1), unix(7)

       Florian Forster <>		  2020-07-20		  COLLECTD-UNIXSOCK(5)


Want to link to this manual page? Use this URL:

home | help