[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