1Collectd::Unixsock(3) User Contributed Perl DocumentationCollectd::Unixsock(3)
2
3
4

NAME

6       Collectd::Unixsock - Abstraction layer for accessing the functionality
7       by collectd's unixsock plugin.
8

SYNOPSIS

10         use Collectd::Unixsock ();
11
12         my $sock = Collectd::Unixsock->new ($path);
13
14         my $value = $sock->getval (%identifier);
15         $sock->putval (%identifier,
16                        time => time (),
17                        values => [123, 234, 345]);
18
19         $sock->destroy ();
20

DESCRIPTION

22       collectd's unixsock plugin allows external programs to access the
23       values it has collected or received and to submit own values. This
24       Perl-module is simply a little abstraction layer over this interface to
25       make it even easier for programmers to interact with the daemon.
26

VALUE IDENTIFIERS

28       The values in the collectd are identified using an five-tuple (host,
29       plugin, plugin-instance, type, type-instance) where only plugin-
30       instance and type-instance may be NULL (or undefined). Many functions
31       expect an %identifier hash that has at least the members host, plugin,
32       and type, possibly completed by plugin_instance and type_instance.
33
34       Usually you can pass this hash as follows:
35
36         $obj->method (host => $host, plugin => $plugin, type => $type, %other_args);
37

PUBLIC METHODS

39       $obj = Collectd::Unixsock->new ([$path]);
40           Creates a new connection to the daemon. The optional $path argument
41           gives the path to the UNIX socket of the "unixsock plugin" and
42           defaults to /var/run/collectd-unixsock. Returns the newly created
43           object on success and false on error.
44
45       $res = $obj->getval (%identifier);
46           Requests a value-list from the daemon. On success a hash-ref is
47           returned with the name of each data-source as the key and the
48           according value as, well, the value. On error false is returned.
49
50       $res = $obj->getthreshold (%identifier);
51           Requests a threshold from the daemon. On success a hash-ref is
52           returned with the threshold data. On error false is returned.
53
54       $obj->putval (%identifier, time => $time, values => [...]);
55           Submits a value-list to the daemon. If the time argument is omitted
56           "time()" is used. The required argument values is a reference to an
57           array of values that is to be submitted. The number of values must
58           match the number of values expected for the given type (see "VALUE
59           IDENTIFIERS"), though this is checked by the daemon, not the Perl
60           module. Also, gauge data-sources (e. g. system-load) may be
61           "undef". Returns true upon success and false otherwise.
62
63       $res = $obj->listval ()
64           Queries a list of values from the daemon. The list is returned as
65           an array of hash references, where each hash reference is a valid
66           identifier. The "time" member of each hash holds the epoch value of
67           the last update of that value.
68
69       $res = $obj->putnotif (severity => $severity, message => $message,
70       ...);
71           Submits a notification to the daemon.
72
73           Valid options are:
74
75           severity
76               Sets the severity of the notification. The value must be one of
77               the following strings: "failure", "warning", or "okay". Case
78               does not matter. This option is mandatory.
79
80           message
81               Sets the message of the notification. This option is mandatory.
82
83           time
84               Sets the time. If omitted, "time()" is used.
85
86           Value identifier
87               All the other fields of the value identifiers, host, plugin,
88               plugin_instance, type, and type_instance, are optional. When
89               given, the notification is associated with the performance data
90               of that identifier.  For more details, please see
91               collectd-unixsock(5).
92
93       $obj->flush (timeout => $timeout, plugins => [...], identifier  =>
94       [...]);
95           Flush cached data.
96
97           Valid options are:
98
99           timeout
100               If this option is specified, only data older than $timeout
101               seconds is flushed.
102
103           plugins
104               If this option is specified, only the selected plugins will be
105               flushed. The argument is a reference to an array of strings.
106
107           identifier
108               If this option is specified, only the given identifier(s) will
109               be flushed. The argument is a reference to an array of
110               identifiers. Identifiers, in this case, are hash references and
111               have the members as outlined in "VALUE IDENTIFIERS".
112
113       $obj->destroy ();
114           Closes the socket before the object is destroyed. This function is
115           also automatically called then the object goes out of scope.
116

SEE ALSO

118       collectd(1), collectd.conf(5), collectd-unixsock(5)
119

AUTHOR

121       Florian octo Forster <octo@verplant.org>
122
123
124
125perl v5.12.3                      2011-03-26             Collectd::Unixsock(3)