NAME¶
Collectd::Unixsock - Abstraction layer for accessing the functionality by
collectd's unixsock plugin.
SYNOPSIS¶
use Collectd::Unixsock ();
my $sock = Collectd::Unixsock->new ($path);
my $value = $sock->getval (%identifier);
$sock->putval (%identifier,
time => time (),
values => [123, 234, 345]);
$sock->destroy ();
DESCRIPTION¶
collectd's unixsock plugin allows external programs to access the values it has
collected or received and to submit own values. This Perl-module is simply a
little abstraction layer over this interface to make it even easier for
programmers to interact with the daemon.
VALUE IDENTIFIERS¶
The values in the collectd are identified using an five-tuple (host, plugin,
plugin-instance, type, type-instance) where only plugin-instance and
type-instance may be NULL (or undefined). Many functions expect an
%identifier hash that has at least the members
host,
plugin, and
type, possibly completed by
plugin_instance and
type_instance.
Usually you can pass this hash as follows:
$obj->method (host => $host, plugin => $plugin, type => $type, %other_args);
PUBLIC METHODS¶
- $obj = Collectd::Unixsock->new
([$path ]);
- Creates a new connection to the daemon. The optional
$path argument gives the path to the UNIX socket of
the "unixsock plugin" and defaults to
/var/run/collectd-unixsock. Returns the newly created object on
success and false on error.
- $res = $obj->getval
(%identifier);
- Requests a value-list from the daemon. On success a hash-ref is returned
with the name of each data-source as the key and the according value as,
well, the value. On error false is returned.
- $res =
$obj->getthreshold (
%identifier );
- Requests a threshold from the daemon. On success a hash-ref is returned
with the threshold data. On error false is returned.
- $obj->putval
(%identifier, time =>
$time, values => [...]);
- Submits a value-list to the daemon. If the time argument is omitted
"time()" is used. The required argument values is a
reference to an array of values that is to be submitted. The number of
values must match the number of values expected for the given type
(see "VALUE IDENTIFIERS"), though this is checked by the daemon,
not the Perl module. Also, gauge data-sources (e. g. system-load)
may be "undef". Returns true upon success and false
otherwise.
- $res = $obj->listval
()
- Queries a list of values from the daemon. The list is returned as an array
of hash references, where each hash reference is a valid identifier. The
"time" member of each hash holds the epoch value of the last
update of that value.
- $res = $obj->putnotif
( severity => $severity, message =>
$message, ...);
- Submits a notification to the daemon.
Valid options are:
- severity
- Sets the severity of the notification. The value must be one of the
following strings: "failure", "warning", or
"okay". Case does not matter. This option is mandatory.
- message
- Sets the message of the notification. This option is mandatory.
- time
- Sets the time. If omitted, "time()" is used.
- Value identifier
- All the other fields of the value identifiers, host, plugin,
plugin_instance, type, and type_instance, are
optional. When given, the notification is associated with the performance
data of that identifier. For more details, please see
collectd-unixsock(5).
- $obj->flush (timeout =>
$timeout, plugins => [...], identifier
=> [...]);
- Flush cached data.
Valid options are:
- timeout
- If this option is specified, only data older than
$timeout seconds is flushed.
- plugins
- If this option is specified, only the selected plugins will be flushed.
The argument is a reference to an array of strings.
- identifier
- If this option is specified, only the given identifier(s) will be flushed.
The argument is a reference to an array of identifiers. Identifiers, in
this case, are hash references and have the members as outlined in
"VALUE IDENTIFIERS".
- $obj->destroy ();
- Closes the socket before the object is destroyed. This function is also
automatically called then the object goes out of scope.
SEE ALSO¶
collectd(1),
collectd.conf(5),
collectd-unixsock(5)
AUTHOR¶
Florian octo Forster <octo@verplant.org>