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 a five-tuple (host, plugin, plugin-instance, type, type-instance) where only plugin instance and type instance may be undef. 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:
$self->method (host => $host, plugin => $plugin, type => $type, %other_args);
PUBLIC METHODS
- $self = 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 = $self->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 = $self->getthreshold (%identifier);
- Requests a threshold from the daemon. On success a hash-ref is returned with the threshold data. On error false is returned.
- $self->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 = $self->listval_filter ( %identifier )
- Queries a list of values from the daemon while restricting the results to certain hosts, plugins etc. The argument may be anything that passes for an identifier (cf. ``VALUE IDENTIFIERS''), although all fields are optional. The returned data is in the same format as from "listval".
- $res = $self->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 = $self->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).
-
- $self->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''.
-
- $self->destroy ();
- Closes the socket before the object is destroyed. This function is also automatically called then the object goes out of scope.