[collectd] [PATCH] Disambiguated the protocol used by the unixsock (and other) plugins.
Sebastian Harl
sh at tokkee.org
Tue Mar 25 15:56:14 CET 2008
As discussed with Florian on IRC, the interpretation of the status line
returned by the unixsock plugin (et.al.) is now strictly specified. A status
greater than or equal to zero indicates success and the number of subsequent
lines of output. A negative status still indicates failure.
This way, frontends can manage the output without having to know any
command-specific interpretation rules.
The GETVAL command has been updated to implement this specification. It now
returns each value on a separate line. collectd-unixsock(5) has been updated to
reflect the changes.
Signed-off-by: Sebastian Harl <sh at tokkee.org>
---
src/collectd-unixsock.pod | 54 +++++++++++++++++++-------------------------
src/utils_cmd_getval.c | 11 ++++-----
src/utils_cmd_listval.c | 2 +-
3 files changed, 29 insertions(+), 38 deletions(-)
diff --git a/src/collectd-unixsock.pod b/src/collectd-unixsock.pod
index 53f8a57..971cb36 100644
--- a/src/collectd-unixsock.pod
+++ b/src/collectd-unixsock.pod
@@ -29,6 +29,18 @@ Upon start the C<unixsock plugin> opens a UNIX-socket and waits for
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
@@ -36,40 +48,34 @@ The following commands are implemented:
=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
+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 consideres to be
+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>
@@ -208,20 +214,6 @@ some examples:
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
B<collectd> ships the Perl-Module L<Collectd::Unixsock> which
diff --git a/src/utils_cmd_getval.c b/src/utils_cmd_getval.c
index a4edf4f..fa5cdf2 100644
--- a/src/utils_cmd_getval.c
+++ b/src/utils_cmd_getval.c
@@ -98,17 +98,16 @@ int handle_getval (FILE *fh, char **fields, int fields_num)
return (-1);
}
- fprintf (fh, "%u", (unsigned int) values_num);
+ fprintf (fh, "%u Value%s found\n", (unsigned int) values_num,
+ (values_num == 1) ? "" : "s");
for (i = 0; i < values_num; i++)
{
- fprintf (fh, " %s=", ds->ds[i].name);
+ fprintf (fh, "%s=", ds->ds[i].name);
if (isnan (values[i]))
- fprintf (fh, "NaN");
+ fprintf (fh, "NaN\n");
else
- fprintf (fh, "%12e", values[i]);
+ fprintf (fh, "%12e\n", values[i]);
}
-
- fprintf (fh, "\n");
fflush (fh);
sfree (values);
diff --git a/src/utils_cmd_listval.c b/src/utils_cmd_listval.c
index 644a67c..8d6c783 100644
--- a/src/utils_cmd_listval.c
+++ b/src/utils_cmd_listval.c
@@ -53,7 +53,7 @@ int handle_listval (FILE *fh, char **fields, int fields_num)
return (-1);
}
- fprintf (fh, "%i Values found\n", (int) number);
+ fprintf (fh, "%i Value%s found\n", (int) number, (number == 1) ? "" : "s");
for (i = 0; i < number; i++)
fprintf (fh, "%u %s\n", (unsigned int) times[i], names[i]);
fflush (fh);
--
1.5.5.rc1
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: Digital signature
Url : http://mailman.verplant.org/pipermail/collectd/attachments/20080325/3233a99c/attachment.pgp
More information about the collectd
mailing list