=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
=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;
} # 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
AC_DEFINE_UNQUOTED(COLLECT_LIBIOKIT, [$collect_libiokit], [Wether or not to use the IOKit library])
AM_CONDITIONAL(BUILD_WITH_LIBIOKIT, test "x$with_libiokit" = "xyes")
- with_libstatgrab="yes"
- with_libdevstat="no"
AC_ARG_WITH(libstatgrab, [AS_HELP_STRING([--with-libstatgrab@<:@=PREFIX@:>@], [Path to libstatgrab.])],
[
if test "x$withval" != "xno" -a "x$withval" != "xyes"
AC_PLUGIN([snmp], [$with_libnetsnmp], [SNMP querying plugin])
AC_PLUGIN([swap], [$plugin_swap], [Swap usage statistics])
AC_PLUGIN([syslog], [$have_syslog], [Syslog logging plugin])
+AC_PLUGIN([tail], [yes], [Parsing of logfiles])
AC_PLUGIN([tape], [$plugin_tape], [Tape drive statistics])
AC_PLUGIN([tcpconns], [$plugin_tcpconns], [TCP connection statistics])
AC_PLUGIN([unixsock], [yes], [Unixsock communication plugin])
snmp . . . . . . . $enable_snmp
swap . . . . . . . $enable_swap
syslog . . . . . . $enable_syslog
+ tail . . . . . . . $enable_tail
tape . . . . . . . $enable_tape
tcpconns . . . . . $enable_tcpconns
unixsock . . . . . $enable_unixsock
connections. Once a connection is established the client can send commands to
the daemon which it will answer, if it understand them.
+In general the plugin answers with a status line of the following form:
+
+I<Status> I<Message>
+
+If I<Status> is greater than or equal to zero the message indicates success,
+if I<Status> is less than zero the message indicates failure. I<Message> is a
+human-readable string that further describes the return value.
+
+On success, I<Status> furthermore indicates the number of subsequent lines of
+output (not including the status line). Each such lines usually contains a
+single return value. See the description of each command for details.
+
The following commands are implemented:
=over 4
=item B<GETVAL> I<Identifier>
If the value identified by I<Identifier> (see below) is found the complete
-value-list is returned. The response is a space separated list of
-name-value-pairs:
-
-I<num> I<name>B<=>I<value>[ I<name>B<=>I<value>[ ...]]
-
-If I<num> is less then zero, an error occurred. Otherwise it contains the
-number of values that follow. Each value is of the form I<name>B<=>I<value>.
+value-list is returned. The response is a list of name-value-pairs, each pair
+on its own line (the number of lines is indicated by the status line - see
+above). Each name-value-pair is of the form I<name>B<=>I<value>.
Counter-values are converted to a rate, e.E<nbsp>g. bytes per second.
Undefined values are returned as B<NaN>.
Example:
-> | GETVAL myhost/cpu-0/cpu-user
- <- | 1 value=1.260000e+00
+ <- | 1 Value found
+ <- | value=1.260000e+00
=item B<LISTVAL>
Returns a list of the values available in the value cache together with the
time of the last update, so that querying applications can issue a B<GETVAL>
-command for the values that have changed.
-
-The first line's status number is the number of identifiers returned or less
-than zero if an error occurred. Each of the following lines contains the
-update time as an epoch value and the identifier, separated by a space.
+command for the values that have changed. Each return value consists of the
+update time as an epoch value and the identifier, separated by a space. The
+update time is the time of the last value, as provided by the collecting
+instance and may be very different from the time the server considers to be
+"now".
Example:
-> | LISTVAL
<- | 69 Values found
- <- | 1182204284 leeloo/cpu-0/cpu-idle
- <- | 1182204284 leeloo/cpu-0/cpu-nice
- <- | 1182204284 leeloo/cpu-0/cpu-system
- <- | 1182204284 leeloo/cpu-0/cpu-user
+ <- | 1182204284 myhost/cpu-0/cpu-idle
+ <- | 1182204284 myhost/cpu-0/cpu-nice
+ <- | 1182204284 myhost/cpu-0/cpu-system
+ <- | 1182204284 myhost/cpu-0/cpu-user
...
=item B<PUTVAL> I<Identifier> [I<OptionList>] I<Valuelist>
(i.E<nbsp>e. data-set) passed to collectd. A large list of predefined
data-sets is available in the B<types.db> file.
- The I<OptionList> is an optional list of I<Options>, where each option if a
+ The I<OptionList> is an optional list of I<Options>, where each option is a
key-value-pair. A list of currently understood options can be found below, all
other options will be ignored.
I<Valuelist> is a colon-separated list of the time and the values, each either
- an integer if the data-source is a counter, of a double if the data-source if
+ an integer if the data-source is a counter, or a double if the data-source is
of type "gauge". You can submit an undefined gauge-value by using B<U>. When
submitting B<U> to a counter the behavior is undefined. The time is given as
epoch (i.E<nbsp>e. standard UNIX time).
-> | PUTNOTIF type=temperature severity=warning time=1201094702 message=The roof is on fire!
<- | 0 Success
+=item B<FLUSH> [B<timeout=>I<Timeout>] [B<plugin=>I<Plugin> [...]]
+
+Flushes all cached data older than I<Timeout> seconds. If no timeout has been
+specified, it defaults to -1 which causes all data to be flushed. B<timeout>
+may be specified multiple times - each occurrence applies to plugins listed
+afterwards.
+
+If specified, only specific plugins are flushed. Otherwise all plugins
+providing a flush callback are flushed.
+
+Example:
+ -> | FLUSH
+ <- | 0 Done
+
=back
=head2 Identifiers
myhost/memory/memory-used
myhost/disk-sda/disk_octets
-=head2 Return values
-
-Unless otherwise noted the plugin answers with a line of the following form:
-
-I<Num> I<Message>
-
-If I<Num> is zero the message indicates success, if I<Num> is non-zero the
-message indicates failure. I<Message> is a human-readable string that describes
-the return value further.
-
-Commands that return values may use I<Num> to return the number of values that
-follow, such as the B<GETVAL> command. These commands usually return a negative
-value on failure and never return zero.
-
=head1 ABSTRACTION LAYER
- Shipped with the sourcecode comes the Perl-Module L<Collectd::Unixsock> which
+ B<collectd> ships the Perl-Module L<Collectd::Unixsock> which
provides an abstraction layer over the actual socket connection. It can be
- found in the directory F<contrib/PerlLib>. If you want to use Perl to
- communicate with the daemon, you're encouraged to use and expand this module.
+ found in the directory F<bindings/perl/> in the source distribution or
+ (usually) somewhere near F</usr/share/perl5/> if you're using a package. If
+ you want to use Perl to communicate with the daemon, you're encouraged to use
+ and expand this module.
=head1 SEE ALSO
projects / collectd.git / commitdiff