+#
+# collectd - Collectd::Unixsock
+# Copyright (C) 2007,2008 Florian octo Forster
+#
+# This program is free software; you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by the
+# Free Software Foundation; only version 2 of the License is applicable.
+#
+# This program is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+# General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along
+# with this program; if not, write to the Free Software Foundation, Inc.,
+# 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
+#
+# Author:
+# Florian octo Forster <octo at verplant.org>
+#
+
package Collectd::Unixsock;
=head1 NAME
-Collectd::Unixsock - Abstraction layer for accessing the functionality by collectd's unixsock plugin.
+Collectd::Unixsock - Abstraction layer for accessing the functionality by
+collectd's unixsock plugin.
=head1 SYNOPSIS
use strict;
use warnings;
+#use constant { NOTIF_FAILURE => 1, NOTIF_WARNING => 2, NOTIF_OKAY => 4 };
+
use Carp (qw(cluck confess));
use IO::Socket::UNIX;
use Regexp::Common (qw(number));
=head1 VALUE IDENTIFIER
-The values in the collectd are identified using an five-tupel (host, plugin,
+The values in the collectd are identified using an five-tuple (host, plugin,
plugin-instance, type, type-instance) where only plugin-instance and
type-instance may be NULL (or undefined). Many functions expect an
I<%identifier> hash that has at least the members B<host>, B<plugin>, and
return ($ret);
} # getval
-=item I<$obj>-E<gt>B<putval> (I<%identifier>, B<time> => I<$time>, B<values> => [...]);
+=item I<$obj>-E<gt>B<putval> (I<%identifier>, B<time> =E<gt> I<$time>, B<values> =E<gt> [...]);
Submits a value-list to the daemon. If the B<time> argument is omitted
-C<time()> is used. The requierd argument B<values> is a reference to an array
+C<time()> is used. The required argument B<values> is a reference to an array
of values that is to be submitted. The number of values must match the number
of values expected for the given B<type> (see L<VALUE IDENTIFIER>), though this
is checked by the daemon, not the Perl module. Also, gauge data-sources
return (@ret);
} # listval
+=item I<$res> = I<$obj>-E<gt>B<putnotif> (B<severity> =E<gt> I<$severity>, B<message> =E<gt> I<$message>, ...);
+
+Submits a notification to the daemon.
+
+Valid options are:
+
+=over 4
+
+=item B<severity>
+
+Sets the severity of the notification. The value must be one of the following
+strings: C<failure>, C<warning>, or C<okay>. Case does not matter. This option
+is mandatory.
+
+=item B<message>
+
+Sets the message of the notification. This option is mandatory.
+
+=item B<time>
+
+Sets the time. If omitted, C<time()> is used.
+
+=item I<Value identifier>
+
+All the other fields of the value identifiers, B<host>, B<plugin>,
+B<plugin_instance>, B<type>, and B<type_instance>, are optional. When given,
+the notification is associated with the performance data of that identifier.
+For more details, please see L<collectd-unixsock(5)>.
+
+=back
+
+=cut
+
+sub putnotif
+{
+ my $obj = shift;
+ my %args = @_;
+
+ my $status;
+ my $fh = $obj->{'sock'} or confess;
+
+ my $msg; # message sent to the socket
+ my $opt_msg; # message of the notification
+
+ if (!$args{'message'})
+ {
+ cluck ("Need argument `message'");
+ return;
+ }
+ if (!$args{'severity'})
+ {
+ cluck ("Need argument `severity'");
+ return;
+ }
+ $args{'severity'} = lc ($args{'severity'});
+ if (($args{'severity'} ne 'failure')
+ && ($args{'severity'} ne 'warning')
+ && ($args{'severity'} ne 'okay'))
+ {
+ cluck ("Invalid `severity: " . $args{'severity'});
+ return;
+ }
+
+ if (!$args{'time'})
+ {
+ $args{'time'} = time ();
+ }
+
+ $opt_msg = $args{'message'};
+ delete ($args{'message'});
+
+ $msg = 'PUTNOTIF '
+ . join (' ', map { $_ . '=' . $args{$_} } (keys %args))
+ . " message=$opt_msg\n";
+
+ send ($fh, $msg, 0) or confess ("send: $!");
+ $msg = undef;
+ recv ($fh, $msg, 1024, 0) or confess ("recv: $!");
+
+ ($status, $msg) = split (' ', $msg, 2);
+ return (1) if ($status == 0);
+
+ $obj->{'error'} = $msg;
+ return;
+} # putnotif
+
+=item I<$obj>-E<gt>B<flush> (B<timeout> =E<gt> I<$timeout>, B<plugins> =E<gt> [...]);
+
+Flush cached data.
+
+Valid options are:
+
+=over 4
+
+=item B<timeout>
+
+If this option is specified, only data older than I<$timeout> seconds is
+flushed.
+
+=item B<plugins>
+
+If this option is specified, only the selected plugins will be flushed.
+
+=back
+
+=cut
+
+sub flush
+{
+ my $obj = shift;
+ my %args = @_;
+
+ my $fh = $obj->{'sock'} or confess;
+
+ my $status = 0;
+ my $msg = "FLUSH";
+
+ if ($args{'timeout'})
+ {
+ $msg .= " timeout=" . $args{'timeout'};
+ }
+
+ if ($args{'plugins'})
+ {
+ foreach my $plugin (@{$args{'plugins'}})
+ {
+ $msg .= " plugin=" . $plugin;
+ }
+ }
+
+ $msg .= "\n";
+
+ send ($fh, $msg, 0) or confess ("send: $!");
+ $msg = undef;
+ recv ($fh, $msg, 1024, 0) or confess ("recv: $!");
+
+ ($status, $msg) = split (' ', $msg, 2);
+ return (1) if ($status == 0);
+
+ $obj->{'error'} = $msg;
+ return;
+}
+
=item I<$obj>-E<gt>destroy ();
Closes the socket before the object is destroyed. This function is also
$obj->destroy ();
}
+=head1 SEE ALSO
+
+L<collectd(1)>,
+L<collectd.conf(5)>,
+L<collectd-unixsock(5)>
+
=head1 AUTHOR
Florian octo Forster E<lt>octo@verplant.orgE<gt>
projects / collectd.git / blobdiff