1 package Collectd::Unixsock;
5 Collectd::Unixsock - Abstraction layer for accessing the functionality by
6 collectd's unixsock plugin.
10 use Collectd::Unixsock ();
12 my $sock = Collectd::Unixsock->new ($path);
14 my $value = $sock->getval (%identifier);
15 $sock->putval (%identifier,
17 values => [123, 234, 345]);
23 collectd's unixsock plugin allows external programs to access the values it has
24 collected or received and to submit own values. This Perl-module is simply a
25 little abstraction layer over this interface to make it even easier for
26 programmers to interact with the daemon.
33 #use constant { NOTIF_FAILURE => 1, NOTIF_WARNING => 2, NOTIF_OKAY => 4 };
35 use Carp (qw(cluck confess));
37 use Regexp::Common (qw(number));
44 my $sock = IO::Socket::UNIX->new (Type => SOCK_STREAM, Peer => $path);
47 cluck ("Cannot open UNIX-socket $path: $!");
53 =head1 VALUE IDENTIFIER
55 The values in the collectd are identified using an five-tupel (host, plugin,
56 plugin-instance, type, type-instance) where only plugin-instance and
57 type-instance may be NULL (or undefined). Many functions expect an
58 I<%identifier> hash that has at least the members B<host>, B<plugin>, and
59 B<type>, possibly completed by B<plugin_instance> and B<type_instance>.
61 Usually you can pass this hash as follows:
63 $obj->method (host => $host, plugin => $plugin, type => $type, %other_args);
67 sub _create_identifier
74 if (!$args->{'host'} || !$args->{'plugin'} || !$args->{'type'})
76 cluck ("Need `host', `plugin' and `type'");
80 $host = $args->{'host'};
81 $plugin = $args->{'plugin'};
82 $plugin .= '-' . $args->{'plugin_instance'} if (defined ($args->{'plugin_instance'}));
83 $type = $args->{'type'};
84 $type .= '-' . $args->{'type_instance'} if (defined ($args->{'type_instance'}));
86 return ("$host/$plugin/$type");
87 } # _create_identifier
99 ($host, $plugin, $type) = split ('/', $string);
101 ($plugin, $plugin_instance) = split ('-', $plugin, 2);
102 ($type, $type_instance) = split ('-', $type, 2);
110 $ident->{'plugin_instance'} = $plugin_instance if (defined ($plugin_instance));
111 $ident->{'type_instance'} = $type_instance if (defined ($type_instance));
114 } # _parse_identifier
116 =head1 PUBLIC METHODS
120 =item I<$obj> = Collectd::Unixsock->B<new> ([I<$path>]);
122 Creates a new connection to the daemon. The optional I<$path> argument gives
123 the path to the UNIX socket of the C<unixsock plugin> and defaults to
124 F</var/run/collectd-unixsock>. Returns the newly created object on success and
132 my $path = @_ ? shift : '/var/run/collectd-unixsock';
133 my $sock = _create_socket ($path) or return;
143 =item I<$res> = I<$obj>-E<gt>B<getval> (I<%identifier>);
145 Requests a value-list from the daemon. On success a hash-ref is returned with
146 the name of each data-source as the key and the according value as, well, the
147 value. On error false is returned.
157 my $fh = $obj->{'sock'} or confess;
163 $identifier = _create_identifier (\%args) or return;
165 $msg = "GETVAL $identifier\n";
167 send ($fh, $msg, 0) or confess ("send: $!");
170 recv ($fh, $msg, 1024, 0) or confess ("recv: $!");
173 ($status, $msg) = split (' ', $msg, 2);
176 $obj->{'error'} = $msg;
180 for (split (' ', $msg))
183 if ($entry =~ m/^(\w+)=NaN$/)
187 elsif ($entry =~ m/^(\w+)=($RE{num}{real})$/)
189 $ret->{$1} = 0.0 + $2;
196 =item I<$obj>-E<gt>B<putval> (I<%identifier>, B<time> =E<gt> I<$time>, B<values> =E<gt> [...]);
198 Submits a value-list to the daemon. If the B<time> argument is omitted
199 C<time()> is used. The requierd argument B<values> is a reference to an array
200 of values that is to be submitted. The number of values must match the number
201 of values expected for the given B<type> (see L<VALUE IDENTIFIER>), though this
202 is checked by the daemon, not the Perl module. Also, gauge data-sources
203 (e.E<nbsp>g. system-load) may be C<undef>. Returns true upon success and false
214 my $fh = $obj->{'sock'} or confess;
219 $identifier = _create_identifier (\%args) or return;
220 if (!$args{'values'})
222 cluck ("Need argument `values'");
226 if (!ref ($args{'values'}))
228 $values = $args{'values'};
232 my $time = $args{'time'} ? $args{'time'} : time ();
233 $values = join (':', $time, map { defined ($_) ? $_ : 'U' } (@{$args{'values'}}));
236 $msg = "PUTVAL $identifier $values\n";
238 send ($fh, $msg, 0) or confess ("send: $!");
240 recv ($fh, $msg, 1024, 0) or confess ("recv: $!");
243 ($status, $msg) = split (' ', $msg, 2);
244 return (1) if ($status == 0);
246 $obj->{'error'} = $msg;
250 =item I<$res> = I<$obj>-E<gt>B<listval> ()
252 Queries a list of values from the daemon. The list is returned as an array of
253 hash references, where each hash reference is a valid identifier. The C<time>
254 member of each hash holds the epoch value of the last update of that value.
264 my $fh = $obj->{'sock'} or confess;
267 send ($fh, $msg, 0) or confess ("send: $!");
270 ($status, $msg) = split (' ', $msg, 2);
273 $obj->{'error'} = $msg;
277 for (my $i = 0; $i < $status; $i++)
285 ($time, $ident) = split (' ', $msg, 2);
287 $ident = _parse_identifier ($ident);
288 $ident->{'time'} = int ($time);
291 } # for (i = 0 .. $status)
296 =item I<$res> = I<$obj>-E<gt>B<putnotif> (B<severity> =E<gt> I<$severity>, B<message> =E<gt> I<$message>, ...);
298 Submits a notification to the daemon.
306 Sets the severity of the notification. The value must be one of the following
307 strings: C<failure>, C<warning>, or C<okay>. Case does not matter. This option
312 Sets the message of the notification. This option is mandatory.
316 Sets the time. If omitted, C<time()> is used.
318 =item I<Value identifier>
320 All the other fields of the value identifiers, B<host>, B<plugin>,
321 B<plugin_instance>, B<type>, and B<type_instance>, are optional. When given,
322 the notification is associated with the performance data of that identifier.
323 For more details, please see L<collectd-unixsock(5)>.
335 my $fh = $obj->{'sock'} or confess;
337 my $msg; # message sent to the socket
338 my $opt_msg; # message of the notification
340 if (!$args{'message'})
342 cluck ("Need argument `message'");
345 if (!$args{'severity'})
347 cluck ("Need argument `severity'");
350 $args{'severity'} = lc ($args{'severity'});
351 if (($args{'severity'} ne 'failure')
352 && ($args{'severity'} ne 'warning')
353 && ($args{'severity'} ne 'okay'))
355 cluck ("Invalid `severity: " . $args{'severity'});
361 $args{'time'} = time ();
364 $opt_msg = $args{'message'};
365 delete ($args{'message'});
368 . join (' ', map { $_ . '=' . $args{$_} } (keys %args))
369 . " message=$opt_msg\n";
371 send ($fh, $msg, 0) or confess ("send: $!");
373 recv ($fh, $msg, 1024, 0) or confess ("recv: $!");
375 ($status, $msg) = split (' ', $msg, 2);
376 return (1) if ($status == 0);
378 $obj->{'error'} = $msg;
382 =item I<$obj>-E<gt>destroy ();
384 Closes the socket before the object is destroyed. This function is also
385 automatically called then the object goes out of scope.
396 close ($obj->{'sock'});
397 delete ($obj->{'sock'});
411 L<collectd-unixsock(5)>
415 Florian octo Forster E<lt>octo@verplant.orgE<gt>