Oh, man page is below also.
cheers.
---------------------------- Original Message ----------------------------
Subject: [rfc, patch] new PCP host specification syntax
From: nscott@xxxxxxxxxx
Date: Thu, November 15, 2007 10:47 am
To: pcp@xxxxxxxxxxx
--------------------------------------------------------------------------
Hi all,
I'm looking for further feedback following on from our discussion a few
weeks back about allowing an extended host specification syntax to
bypass the PMPROXY_HOST, PMPROXY_PORT, and PMCD_PORT variables,
and encoding those directly in the hostname passed to all the tools. The
current libpcp limitations (i.e. the one trip setup of proxy/port vars for
all contexts created by a process) is resolved by this too, making dynamic
pmproxy support viable for kmchart now. Use of the current environment
variables works as before, in the absence of any extended host syntax.
For example, these commands are now possible (and working with the
attached patch):
$ pcp -h app1.aconex.com:44321,4321@xxxxxxxxxxxxxxxxxxx:44322
$ pcp -h app1.aconex.com:44321@xxxxxxxxxxxxxxxxxxx:44322
$ pcp -h app1.aconex.com:44321@xxxxxxxxxxxxxxxxxxx
$ pcp -h app1.aconex.com@xxxxxxxxxxxxxxxxxxx
$ pcp -h app1.aconex.com:44321
I've introduced a PMAPI function named pmParseHostSpec, along the lines
of pmParseMetricSpec, and this is used within libpcp now. It caters for the
goal of multiple pmproxy hosts that Mark had, but I have not attempted to
implement the protocol extension that would provide that.
Any further thoughts? We use pmproxy heavily here, and this is so much
better than using the environment variables! (clear syntax and less error
prone).
Attached is a git patch. You will need to mv mspec.c to spec.c below the
src/libpcp/src directory before applying it, I think, since diff can't
express
the git rename.
Also, can someone outline what the procedure is in terms of libpcp version
numbering and adding new API functions? (Max?) Thanks!
cheers.
--------------------------------------------------------------------------
'\"macro stdmacro
.\"
.\" Copyright (c) 2007 Aconex, Inc. All Rights Reserved.
.\"
.\" 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; either version 2 of the License, or (at your
.\" option) any later version.
.\"
.\" 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.,
.\" 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
.\"
.ie \(.g \{\
.\" ... groff (hack for khelpcenter, man2html, etc.)
.TH PMPARSEHOSTSPEC 3 "Aconex" "Performance Co-Pilot"
\}
.el \{\
.if \nX=0 .ds x} PMPARSEHOSTSPEC 3 "Aconex" "Performance Co-Pilot"
.if \nX=1 .ds x} PMPARSEHOSTSPEC 3 "Performance Co-Pilot"
.if \nX=2 .ds x} PMPARSEHOSTSPEC 3 "" "\&"
.if \nX=3 .ds x} PMPARSEHOSTSPEC "" "" "\&"
.TH \*(x}
.rr X
\}
.SH NAME
\f3pmParseHostSpec\f1,
\f3pmFreeHostSpec\f1 \- uniform host specification parser
.SH "C SYNOPSIS"
.ft 3
#include <pcp/pmapi.h>
.sp
int pmParseHostSpec(const char *string, pmHostSpec **rsltp, int *count,
char **errmsg)
.sp
void pmFreeHostSpec(pmHostSpec *rslt, int count)
.sp
cc ... \-lpcp
.ft 1
.SH DESCRIPTION
.B pmParseHostSpec
accepts a
.B string
specifying the location of a PCP performance metric collector daemon.
.B
The syntax allows the initial
.BR pmcd (1)
hostname to be optionally followed by a list of port numbers,
which will be tried in order when connecting to
.B pmcd
on that host.
The portlist is separated from the hostname using a colon, and
each port in the list is comma-separated.
.PP
In addition, one or more optional
.BR pmproxy (1)
hosts can be specified (currently, only one proxy host is supported
by the PCP protocols).
These are separated from each other and from the
.B pmcd
component using the @ character.
These may also be followed by an optional port list, using the
same comma-separated syntax as before.
.PP
.B pmParseHostSpec
takes a null-terminated host specification
.B string
and returns an array of
.B pmHostSpec
structures, where the array has
.B count
entries.
.PP
These
.B pmHostSpec
structures that are returned via
.B rsltp
represent each individual host in the specification
.B string
and has the following
declaration:
.PP
.nf
.ft CW
typedef struct {
char *name; /* hostname (always valid) */
int *ports; /* array of host port numbers */
int nports; /* number of ports in host port array */
} pmHostSpec;
.fi
.PP
.B pmParseHostSpec
returns 0 if the given
.B string
was successfully parsed. In this case all the storage allocated by
.B pmParseHostSpec
can be released by calling
.B pmFreeHostSpec
using the address returned from
.B pmParseHostSpec
via
.BR rsltp .
.P
.B pmParseHostSpec
returns
.B PM_ERR_GENERIC
and a dynamically allocated error message string in
.BR errmsg ,
if the given
.B string
does not parse, and the user-supplied
.B errmsg
pointer is non-null.
Be sure to
.BR free (3C)
the error message string in this situation.
.PP
In the case of an error,
.B rsltp
is undefined.
In the case of success,
.B errmsg
is undefined.
.SH EXAMPLES
.PP
The following are valid host specifications that specify connections to
.B pmcd
on host
.I app1.aconex.com
with/without a list of ports and with/without a
.B pmproxy
connection through a firewall.
.PP
.in +0.5i
.nf
.ft CW
$ pcp -h app1.aconex.com:44321,4321@xxxxxxxxxxxxxxxxxxx:44322
$ pcp -h app1.aconex.com:44321@xxxxxxxxxxxxxxxxxxx:44322
$ pcp -h app1.aconex.com:44321@xxxxxxxxxxxxxxxxxxx
$ pcp -h app1.aconex.com@xxxxxxxxxxxxxxxxxxx
$ pcp -h app1.aconex.com:44321
.ft R
.fi
.in
.SH SEE ALSO
.BR pmcd (1),
.BR pmproxy (1),
.BR PMAPI (3)
and
.BR pmNewContext (3).
|