1 package Collectd::Unixsock;
5 Collectd::Unixsock - Abstraction layer for accessing the functionality by collectd's unixsock plugin.
9 use Collectd::Unixsock ();
11 my $sock = Collectd::Unixsock->new ($path);
13 my $value = $sock->getval (%identifier);
14 $sock->putval (%identifier,
16 values => [123, 234, 345]);
22 collectd's unixsock plugin allows external programs to access the values it has
23 collected or received and to submit own values. This Perl-module is simply a
24 little abstraction layer over this interface to make it even easier for
25 programmers to interact with the daemon.
32 use Carp (qw(cluck confess));
34 use Regexp::Common (qw(number));
41 my $sock = IO::Socket::UNIX->new (Type => SOCK_STREAM, Peer => $path);
44 cluck ("Cannot open UNIX-socket $path: $!");
50 =head1 VALUE IDENTIFIER
52 The values in the collectd are identified using an five-tupel (host, plugin,
53 plugin-instance, type, type-instance) where only plugin-instance and
54 type-instance may be NULL (or undefined). Many functions expect an
55 I<%identifier> hash that has at least the members B<host>, B<plugin>, and
56 B<type>, possibly completed by B<plugin_instance> and B<type_instance>.
58 Usually you can pass this hash as follows:
60 $obj->method (host => $host, plugin => $plugin, type => $type, %other_args);
64 sub _create_identifier
71 if (!$args->{'host'} || !$args->{'plugin'} || !$args->{'type'})
73 cluck ("Need `host', `plugin' and `type'");
77 $host = $args->{'host'};
78 $plugin = $args->{'plugin'};
79 $plugin .= '-' . $args->{'plugin_instance'} if (defined ($args->{'plugin_instance'}));
80 $type = $args->{'type'};
81 $type .= '-' . $args->{'type_instance'} if (defined ($args->{'type_instance'}));
83 return ("$host/$plugin/$type");
84 } # _create_identifier
90 =item I<$obj> = Collectd::Unixsock->B<new> ([I<$path>]);
92 Creates a new connection to the daemon. The optional I<$path> argument gives
93 the path to the UNIX socket of the C<unixsock plugin> and defaults to
94 F</var/run/collectd-unixsock>. Returns the newly created object on success and
102 my $path = @_ ? shift : '/var/run/collectd-unixsock';
103 my $sock = _create_socket ($path) or return;
113 =item I<$res> = I<$obj>-E<gt>B<getval> (I<%identifier>);
115 Requests a value-list from the daemon. On success a hash-ref is returned with
116 the name of each data-source as the key and the according value as, well, the
117 value. On error false is returned.
127 my $fh = $obj->{'sock'} or confess;
133 $identifier = _create_identifier (\%args) or return;
135 $msg = "GETVAL $identifier\n";
137 send ($fh, $msg, 0) or confess ("send: $!");
140 recv ($fh, $msg, 1024, 0) or confess ("recv: $!");
143 ($status, $msg) = split (' ', $msg, 2);
146 $obj->{'error'} = $msg;
150 for (split (' ', $msg))
153 if ($entry =~ m/^(\w+)=NaN$/)
157 elsif ($entry =~ m/^(\w+)=($RE{num}{real})$/)
159 $ret->{$1} = 0.0 + $2;
166 =item I<$obj>-E<gt>B<putval> (I<%identifier>, B<time> => I<$time>, B<values> => [...]);
168 Submits a value-list to the daemon. If the B<time> argument is omitted
169 C<time()> is used. The requierd argument B<values> is a reference to an array
170 of values that is to be submitted. The number of values must match the number
171 of values expected for the given B<type> (see L<VALUE IDENTIFIER>), though this
172 is checked by the daemon, not the Perl module. Also, gauge data-sources
173 (e.E<nbsp>g. system-load) may be C<undef>. Returns true upon success and false
184 my $fh = $obj->{'sock'} or confess;
189 $identifier = _create_identifier (\%args) or return;
190 if (!$args{'values'})
192 cluck ("Need argument `values'");
196 if (!ref ($args{'values'}))
198 $values = $args{'values'};
202 my $time = $args{'time'} ? $args{'time'} : time ();
203 $values = join (':', $time, map { defined ($_) ? $_ : 'U' } (@{$args{'values'}}));
206 $msg = "PUTVAL $identifier $values\n";
208 send ($fh, $msg, 0) or confess ("send: $!");
210 recv ($fh, $msg, 1024, 0) or confess ("recv: $!");
213 ($status, $msg) = split (' ', $msg, 2);
214 return (1) if ($status == 0);
216 $obj->{'error'} = $msg;
220 =item I<$obj>-E<gt>destroy ();
222 Closes the socket before the object is destroyed. This function is also
223 automatically called then the object goes out of scope.
234 close ($obj->{'sock'});
235 delete ($obj->{'sock'});
247 Florian octo Forster E<lt>octo@verplant.orgE<gt>