2 # collectd - Collectd::Unixsock
3 # Copyright (C) 2007,2008 Florian octo Forster
5 # This program is free software; you can redistribute it and/or modify it
6 # under the terms of the GNU General Public License as published by the
7 # Free Software Foundation; only version 2 of the License is applicable.
9 # This program is distributed in the hope that it will be useful, but
10 # WITHOUT ANY WARRANTY; without even the implied warranty of
11 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 # General Public License for more details.
14 # You should have received a copy of the GNU General Public License along
15 # with this program; if not, write to the Free Software Foundation, Inc.,
16 # 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
19 # Florian octo Forster <octo at verplant.org>
22 package Collectd::Unixsock;
26 Collectd::Unixsock - Abstraction layer for accessing the functionality by
27 collectd's unixsock plugin.
31 use Collectd::Unixsock ();
33 my $sock = Collectd::Unixsock->new ($path);
35 my $value = $sock->getval (%identifier);
36 $sock->putval (%identifier,
38 values => [123, 234, 345]);
44 collectd's unixsock plugin allows external programs to access the values it has
45 collected or received and to submit own values. This Perl-module is simply a
46 little abstraction layer over this interface to make it even easier for
47 programmers to interact with the daemon.
54 #use constant { NOTIF_FAILURE => 1, NOTIF_WARNING => 2, NOTIF_OKAY => 4 };
56 use Carp (qw(cluck confess));
58 use Regexp::Common (qw(number));
65 my $sock = IO::Socket::UNIX->new (Type => SOCK_STREAM, Peer => $path);
68 cluck ("Cannot open UNIX-socket $path: $!");
74 =head1 VALUE IDENTIFIERS
76 The values in the collectd are identified using an five-tuple (host, plugin,
77 plugin-instance, type, type-instance) where only plugin-instance and
78 type-instance may be NULL (or undefined). Many functions expect an
79 I<%identifier> hash that has at least the members B<host>, B<plugin>, and
80 B<type>, possibly completed by B<plugin_instance> and B<type_instance>.
82 Usually you can pass this hash as follows:
84 $obj->method (host => $host, plugin => $plugin, type => $type, %other_args);
88 sub _create_identifier
95 if (!$args->{'host'} || !$args->{'plugin'} || !$args->{'type'})
97 cluck ("Need `host', `plugin' and `type'");
101 $host = $args->{'host'};
102 $plugin = $args->{'plugin'};
103 $plugin .= '-' . $args->{'plugin_instance'} if (defined ($args->{'plugin_instance'}));
104 $type = $args->{'type'};
105 $type .= '-' . $args->{'type_instance'} if (defined ($args->{'type_instance'}));
107 return ("$host/$plugin/$type");
108 } # _create_identifier
110 sub _parse_identifier
120 ($host, $plugin, $type) = split ('/', $string);
122 ($plugin, $plugin_instance) = split ('-', $plugin, 2);
123 ($type, $type_instance) = split ('-', $type, 2);
131 $ident->{'plugin_instance'} = $plugin_instance if (defined ($plugin_instance));
132 $ident->{'type_instance'} = $type_instance if (defined ($type_instance));
135 } # _parse_identifier
141 if ($string =~ m/^\w+$/)
146 $string =~ s#\\#\\\\#g;
147 $string =~ s#"#\\"#g;
148 $string = "\"$string\"";
153 =head1 PUBLIC METHODS
157 =item I<$obj> = Collectd::Unixsock->B<new> ([I<$path>]);
159 Creates a new connection to the daemon. The optional I<$path> argument gives
160 the path to the UNIX socket of the C<unixsock plugin> and defaults to
161 F</var/run/collectd-unixsock>. Returns the newly created object on success and
169 my $path = @_ ? shift : '/var/run/collectd-unixsock';
170 my $sock = _create_socket ($path) or return;
180 =item I<$res> = I<$obj>-E<gt>B<getval> (I<%identifier>);
182 Requests a value-list from the daemon. On success a hash-ref is returned with
183 the name of each data-source as the key and the according value as, well, the
184 value. On error false is returned.
194 my $fh = $obj->{'sock'} or confess ('object has no filehandle');
200 $identifier = _create_identifier (\%args) or return;
202 $msg = 'GETVAL ' . _escape_argument ($identifier) . "\n";
204 send ($fh, $msg, 0) or confess ("send: $!");
207 recv ($fh, $msg, 1024, 0) or confess ("recv: $!");
210 ($status, $msg) = split (' ', $msg, 2);
213 $obj->{'error'} = $msg;
217 for (split (' ', $msg))
220 if ($entry =~ m/^(\w+)=NaN$/)
224 elsif ($entry =~ m/^(\w+)=($RE{num}{real})$/)
226 $ret->{$1} = 0.0 + $2;
233 =item I<$obj>-E<gt>B<putval> (I<%identifier>, B<time> =E<gt> I<$time>, B<values> =E<gt> [...]);
235 Submits a value-list to the daemon. If the B<time> argument is omitted
236 C<time()> is used. The required argument B<values> is a reference to an array
237 of values that is to be submitted. The number of values must match the number
238 of values expected for the given B<type> (see L<VALUE IDENTIFIERS>), though
239 this is checked by the daemon, not the Perl module. Also, gauge data-sources
240 (e.E<nbsp>g. system-load) may be C<undef>. Returns true upon success and false
251 my $fh = $obj->{'sock'} or confess;
257 if (defined $args{'interval'})
259 $interval = ' interval='
260 . _escape_argument ($args{'interval'});
263 $identifier = _create_identifier (\%args) or return;
264 if (!$args{'values'})
266 cluck ("Need argument `values'");
270 if (!ref ($args{'values'}))
272 $values = $args{'values'};
276 my $time = $args{'time'} ? $args{'time'} : time ();
277 $values = join (':', $time, map { defined ($_) ? $_ : 'U' } (@{$args{'values'}}));
281 . _escape_argument ($identifier)
283 . ' ' . _escape_argument ($values) . "\n";
285 send ($fh, $msg, 0) or confess ("send: $!");
287 recv ($fh, $msg, 1024, 0) or confess ("recv: $!");
290 ($status, $msg) = split (' ', $msg, 2);
291 return (1) if ($status == 0);
293 $obj->{'error'} = $msg;
297 =item I<$res> = I<$obj>-E<gt>B<listval> ()
299 Queries a list of values from the daemon. The list is returned as an array of
300 hash references, where each hash reference is a valid identifier. The C<time>
301 member of each hash holds the epoch value of the last update of that value.
311 my $fh = $obj->{'sock'} or confess;
314 send ($fh, $msg, 0) or confess ("send: $!");
317 ($status, $msg) = split (' ', $msg, 2);
320 $obj->{'error'} = $msg;
324 for (my $i = 0; $i < $status; $i++)
332 ($time, $ident) = split (' ', $msg, 2);
334 $ident = _parse_identifier ($ident);
335 $ident->{'time'} = int ($time);
338 } # for (i = 0 .. $status)
343 =item I<$res> = I<$obj>-E<gt>B<putnotif> (B<severity> =E<gt> I<$severity>, B<message> =E<gt> I<$message>, ...);
345 Submits a notification to the daemon.
353 Sets the severity of the notification. The value must be one of the following
354 strings: C<failure>, C<warning>, or C<okay>. Case does not matter. This option
359 Sets the message of the notification. This option is mandatory.
363 Sets the time. If omitted, C<time()> is used.
365 =item I<Value identifier>
367 All the other fields of the value identifiers, B<host>, B<plugin>,
368 B<plugin_instance>, B<type>, and B<type_instance>, are optional. When given,
369 the notification is associated with the performance data of that identifier.
370 For more details, please see L<collectd-unixsock(5)>.
382 my $fh = $obj->{'sock'} or confess;
384 my $msg; # message sent to the socket
385 my $opt_msg; # message of the notification
387 if (!$args{'message'})
389 cluck ("Need argument `message'");
392 if (!$args{'severity'})
394 cluck ("Need argument `severity'");
397 $args{'severity'} = lc ($args{'severity'});
398 if (($args{'severity'} ne 'failure')
399 && ($args{'severity'} ne 'warning')
400 && ($args{'severity'} ne 'okay'))
402 cluck ("Invalid `severity: " . $args{'severity'});
408 $args{'time'} = time ();
411 $opt_msg = $args{'message'};
412 delete ($args{'message'});
415 . join (' ', map { $_ . '=' . $args{$_} } (keys %args))
416 . " message=$opt_msg\n";
418 send ($fh, $msg, 0) or confess ("send: $!");
420 recv ($fh, $msg, 1024, 0) or confess ("recv: $!");
422 ($status, $msg) = split (' ', $msg, 2);
423 return (1) if ($status == 0);
425 $obj->{'error'} = $msg;
429 =item I<$obj>-E<gt>B<flush> (B<timeout> =E<gt> I<$timeout>, B<plugins> =E<gt> [...], B<identifier> =E<gt> [...]);
439 If this option is specified, only data older than I<$timeout> seconds is
444 If this option is specified, only the selected plugins will be flushed. The
445 argument is a reference to an array of strings.
449 If this option is specified, only the given identifier(s) will be flushed. The
450 argument is a reference to an array of identifiers. Identifiers, in this case,
451 are hash references and have the members as outlined in L<VALUE IDENTIFIERS>.
462 my $fh = $obj->{'sock'} or confess;
467 if (defined ($args{'timeout'}))
469 $msg .= " timeout=" . $args{'timeout'};
472 if ($args{'plugins'})
474 foreach my $plugin (@{$args{'plugins'}})
476 $msg .= " plugin=" . $plugin;
480 if ($args{'identifier'})
482 for (@{$args{'identifier'}})
487 if (ref ($identifier) ne 'HASH')
489 cluck ("The argument of the `identifier' "
490 . "option must be an array reference "
491 . "of hash references.");
495 $ident_str = _create_identifier ($identifier);
501 $msg .= ' identifier=' . _escape_argument ($ident_str);
507 send ($fh, $msg, 0) or confess ("send: $!");
509 recv ($fh, $msg, 1024, 0) or confess ("recv: $!");
511 ($status, $msg) = split (' ', $msg, 2);
512 return (1) if ($status == 0);
514 $obj->{'error'} = $msg;
518 =item I<$obj>-E<gt>destroy ();
520 Closes the socket before the object is destroyed. This function is also
521 automatically called then the object goes out of scope.
532 close ($obj->{'sock'});
533 delete ($obj->{'sock'});
547 L<collectd-unixsock(5)>
551 Florian octo Forster E<lt>octo@verplant.orgE<gt>