1Collectd::Unixsock(3) User Contributed Perl DocumentationCollectd::Unixsock(3)
2
3
4
6 Collectd::Unixsock - Abstraction layer for accessing the functionality
7 by collectd's unixsock plugin.
8
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
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
28 The values in the collectd are identified using a five-tuple (host,
29 plugin, plugin-instance, type, type-instance) where only plugin
30 instance and type instance may be undef. Many functions expect an
31 %identifier hash that has at least the members host, plugin, and type,
32 possibly completed by plugin_instance and type_instance.
33
34 Usually you can pass this hash as follows:
35
36 $self->method (host => $host, plugin => $plugin, type => $type, %other_args);
37
39 $self = 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 = $self->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 = $self->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 $self->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 = $self->listval_filter ( %identifier )
64 Queries a list of values from the daemon while restricting the
65 results to certain hosts, plugins etc. The argument may be anything
66 that passes for an identifier (cf. "VALUE IDENTIFIERS"), although
67 all fields are optional. The returned data is in the same format
68 as from "listval".
69
70 $res = $self->listval ()
71 Queries a list of values from the daemon. The list is returned as
72 an array of hash references, where each hash reference is a valid
73 identifier. The "time" member of each hash holds the epoch value of
74 the last update of that value.
75
76 $res = $self->putnotif (severity => $severity, message => $message,
77 ...);
78 Submits a notification to the daemon.
79
80 Valid options are:
81
82 severity
83 Sets the severity of the notification. The value must be one of
84 the following strings: "failure", "warning", or "okay". Case
85 does not matter. This option is mandatory.
86
87 message
88 Sets the message of the notification. This option is mandatory.
89
90 time
91 Sets the time. If omitted, "time()" is used.
92
93 Value identifier
94 All the other fields of the value identifiers, host, plugin,
95 plugin_instance, type, and type_instance, are optional. When
96 given, the notification is associated with the performance data
97 of that identifier. For more details, please see
98 collectd-unixsock(5).
99
100 $self->flush (timeout => $timeout, plugins => [...], identifier =>
101 [...]);
102 Flush cached data.
103
104 Valid options are:
105
106 timeout
107 If this option is specified, only data older than $timeout
108 seconds is flushed.
109
110 plugins
111 If this option is specified, only the selected plugins will be
112 flushed. The argument is a reference to an array of strings.
113
114 identifier
115 If this option is specified, only the given identifier(s) will
116 be flushed. The argument is a reference to an array of
117 identifiers. Identifiers, in this case, are hash references and
118 have the members as outlined in "VALUE IDENTIFIERS".
119
120 $self->destroy ();
121 Closes the socket before the object is destroyed. This function is
122 also automatically called then the object goes out of scope.
123
125 collectd(1), collectd.conf(5), collectd-unixsock(5)
126
128 Florian octo Forster <octo@collectd.org>
129
130
131
132perl v5.34.1 2022-06-11 Collectd::Unixsock(3)