Scroll to navigation

PMPROXY(1) General Commands Manual PMPROXY(1)

NAME

pmproxy - proxy for performance metrics collector and querying

SYNOPSIS

pmproxy [-AdfFt?] [-c conffile] [-h host[,host ...] [-i ipaddress] [-l logfile] [-L bytes] [-p port[,port ...] [-r port[,port ...] [-s sockname] [-U username] [-x outfile]

DESCRIPTION

pmproxyacts as a protocol proxy,allowing Performance Co-Pilot (PCP) monitoring clients to connect toone or morepmcd(1)and/orredis-server(1)instances viapmproxy.

In its default mode of operationpmproxyprovides the REST API for PCP services (seePMWEBAPI(3)for details).This includes provision of an Open Metrics -https://openmetrics.io- text interface for PCP metrics at/metrics,realtime access to PCP metrics through the/pmapiinterfaces,and access to the fast, scalable PCP time series querycapabilities offered in conjunction with aredis-server(1)(seepmseries(1)for details) via the/queryREST interfaces.

pmproxycan be deployed in a firewall domain, or on a cluster ``head'' nodewhere the IP (Internet Protocol) address of the hosts wherepmcdand/orredis-serverare running may be unknown to the PCP monitoring clients, but wherethe IP address of the host runningpmproxyis known to these clients.Similarly, the clients may have network connectivity only to thehost wherepmproxyis running, while there is network connectivity from that host to thehosts of interest wherepmcdand/orredis-serverare running.

The behaviour of the PCP monitoring clients is controlled by either thePMPROXY_HOSTenvironment variable or through the extended hostname specification(seePCPIntro(1)for details).If neither of these mechanisms is used, clients will make theirPMAPI(3)connections directly topmcd.If the proxy hostname syntax is used orPMPROXY_HOSTis set, then this should be the hostname or IP address of the systemwherepmproxyis running, and the clients will connect topmcdorredis-serverindirectly through the protocol proxy services ofpmproxy.

OPTIONS

The available command line options are:

Disable service advertisement.By default,pmproxywill advertise its presence on the network using any available mechanisms(such as Avahi/DNS-SD), assisting remote monitoring tools with finding it.These mechanisms are disabled with this option.
Specify the path to an optional configurationconffile,with format as described in the ``CONFIGURATION'' section.This option implies pmproxy is running in timeseries mode.
By defaultpmproxyprefers to run in the new timeseries mode, providing REST APIs, asynchronous network I/O, scalable time series, and secure connections using OpenSSL. However, legacy deployments may wish to use the original synchronous pmproxyimplementation using libpcp networking; this can be achieved usingthis option.Note that the -d and -t options are mutually exclusive.
By defaultpmproxyis started as a daemon.The-foption indicates that it should run in the foreground.This is most useful when trying to diagnose problems with establishingconnections.
Like-f,the-Foption runspmproxyin the foreground, but also does some housekeeping (like create a``pid'' file and change user id). This is intended for use whenpmproxyis launched fromsystemd(1)and the daemonizing has already been done bysystemd(1)and does not need to be done again bypmproxy,which is the case when neither-fnor-Fis specified.

At most one of-fand-Fmay be specified.

Specify an alternate Redishostto connect to for time series querying, overriding any configurationfile settings.This option implies pmproxy is running in timeseries mode.
This option is usually only used on hosts with more than one networkinterface (very common for firewall and ``head'' node hosts wherepmproxyis likely to be deployed to arbitrate access to an internal network).If no-ioptions are specifiedpmproxyaccepts PCP client connections on any of its host's IP addresses.The-ioption is used to specify explicitly an IP address that PCP client connections should beaccepted on.ipaddressshould be in the standard dotted form (e.g. 100.23.45.6).The-ioption may be used multiple times to define a list of IP addresses.When one or more-ioptions is specified, attempted connections made on any other IP addresses will be refused.
By default a log file namedpmproxy.logis written in the current directory.The-loption causes the log file to be written to a givenlogfileinstead of the default.If thislogfilecannot be created or is not writable, output iswritten to the standard error instead.
PDUsreceived bypmproxyfrom PCP monitoring clients are restricted to amaximum size of 65536 bytes by default to defend against Denial ofService attacks.The-Loption may be used to change the maximum incomingPDUsize.
Specify an alternateportnumber to listen on for client connections.The default value is 44322.
Specify an alternate Redisportnumber to connect to for time series querying, overriding anyconfiguration file settings.This option implies pmproxy is running in timeseries mode.
Specify the path to a local unix domain socket (for platforms supporting thissocket family only).The default value is$PCP_RUN_DIR/pmproxy.socket.This option implies pmproxy is running in timeseries mode.
Operate in automatic archive timeseries discovery mode.This mode of operation will enable thePMWEBAPI(3)REST APIs, dynamiclly and automatically detect active systemarchives being written bypmlogger(1)and import them into aredis-server(1),for fast, scalable time series querying described inpmseries(1).Note that in this mode of operation,pmproxyonly "log-tails" and ingests actively growing archives, e.g. as written by one or morepmlogger(1)instances.When an archive is first discovered (usually but not limited topmproxystartup),all metadata is loaded and sent to the configuredredis-server(1)however note that onlynewarchive metric value data from the tail end of each archive is ingested.Compressed archives never grow and so are ignored.See the--loadoption topmseries(1)for a supported mechanism for manually loading all of the metric value datafrom previously collected (inactive) archives,whether compressed or not.It would be normal, though not mandated, for a set of archives being manually loadedto cover the same time period, e.g. archive data for a particular week for one or morehosts in the same data-centre.
Assume the identity of the givenusernamebefore starting to accept incoming packets from PCP monitoring clients.
Before thepmproxylogfilecan be opened,pmproxymay encounter a fatal error which prevents it from starting.By default the output describing this error is sent to/dev/ttybut it may redirected tooutfile.
-?, --help
Display usage message and exit.

CONFIGURATION

When running in the timeseries mode of operation, runtime configuration is relatively complex and typically handled via the $PCP_SYSCONF_DIR/pmproxy/pmproxy.conffile.This file is in the common ``ini'' format, with section headersand individual variables and values with each section.The configuration file installed as part of PCP documentsevery available section and option.

At a high level, the[pmproxy]section can be used to explicitly enable or disable each of thedifferent protocols.

The[redis]section allows connection information for one or more backingredis-serverprocesses to be configured (hostnames and ports).Note to access multiple (scalable) Redis servers, theserversvariable in this section can be a comma-separated list ofhostname:port pairs.Alternatively, it can be a singleredis-serverhost that will be queried using the "CLUSTER INFO" command toautomatically configure multiple backing hosts, described athttps://redis.io/topics/cluster-spec.

In earlier versions of PCP (before 6) an alternative configurationsetting section was used for this purpose - Redisserverswere specified in the[pmseries]section and this is still accepted as a fallback for backwardscompatibility.

STARTINGANDSTOPPINGPMPROXY

Normally,pmproxyis started automatically at boot time and stopped when thesystem is being brought down.Under certain circumstances it is necessary to start or stoppmproxymanually.To do this one must become superuser and type

# $PCP_RC_DIR/pmproxy start

to startpmproxy,or

# $PCP_RC_DIR/pmproxy stop

to stoppmproxy.Startingpmproxywhen it is already running is the same as stoppingit and then starting it again.

Normallypmproxylistens for PCP client connections on TCP/IP port number 44322(as well as 44323 with timeseries enabled) registered at https://www.iana.org/.Either the environmentvariablePMPROXY_PORTor the-pcommand line option may be used to specify alternative portnumber(s) whenpmproxyis started; in each case, the specification is a comma-separated listof one or more numerical port numbers.Should both methods be used or multiple-poptions appear on the command line,pmproxywill listen on the union of the set of ports specified via all-poptions and thePMPROXY_PORTenvironment variable.If non-default ports are used withpmproxycare should be taken to ensure thatPMPROXY_PORTis also set in the environment of any client application thatwill connect topmproxy,or that the extended host specification syntax is used(seePCPIntro(1)for details).

DIAGNOSTICS

Ifpmproxyis already running the message "Error: OpenRequestSocket bind: Address alreadyin use" will appear.This may also appear ifpmproxywas shutdown with an outstanding request from a client.In this case, arequest socket has been left in the TIME_WAIT state and until the system closesit down (after some timeout period) it will not be possible to runpmproxy.

In addition to the standardPCPdebugging options, seepmdbg(1),pmproxycurrently supports the debugging optioncontextfor tracing client connections and disconnections.

FILES

$PCP_PMPROXYOPTIONS_PATH
command line options forpmproxywhen launched from$PCP_RC_DIR/pmproxyAll the command line option lines should start with a hyphen asthe first character.
$PCP_SYSCONFIG_DIR/pmproxy
Environment variables that will be set whenpmproxyexecutes.Only settings of the form "PMPROXY_VARIABLE=value" will be honoured.
./pmproxy.log
(or$PCP_LOG_DIR/pmproxy/pmproxy.logwhen started automatically)
All messages and diagnostics are directed here
/etc/pki/tls
default OpenSSL certificate database directory, optionally used forSecure Socket Layer connection in timeseries mode of operation. These certificates can be created and queried using the openssltool, amongst others.

ENVIRONMENT

In addition to the PCP environment variables described in thePCP ENVIRONMENTsection below, there are several environment variables thatinfluence the interactions between a PCP monitoring client,pmproxyandpmcd.

For the PCP monitoring client this (or the default port number) is passed topmproxyand used to connect topmcd.In the environment ofpmproxyPMCD_PORT is not used.
For the PCP monitoring client this is the hostname or IP address of thehost wherepmproxyis running.In recent versions of PCP (since version 3) this has been superseded bythe extended hostname syntax(seePCPIntro(1)for details).
For the PCP monitoring client this is the port on whichpmproxywill accept connections.The default is 44322, as well as 44323 with timeseries enabled.
(seePCPIntro(1))For the PCP monitoring client, setting these environment variableswill modify the timeouts used for interactions between the clientandpmproxy(independent of whichpmcdis being used).Forpmproxythese same environment variables control the timeouts betweenpmproxyand allpmcd(1)instances (independent of which monitoring client is involved).

If set to the value 1, thePMPROXY_LOCALenvironment variable will causepmproxyto run in a localhost-only mode of operation, where it binds onlyto the loopback interface.

ThePMPROXY_MAXPENDINGvariable can be set to indicate the maximum length to which the queueof pending client connections may grow.

PCPENVIRONMENT

Environment variables with the prefix PCP_ are used to parameterize the file and directory names used by PCP. On each installation, the file /etc/pcp.conf contains the local values for these variables. The $PCP_CONF variable may be used to specify an alternative configuration file, as described in pcp.conf(5).

For environment variables affecting PCP tools, see pmGetOptions(3).

SEEALSO

PCPIntro(1),pmcd(1),pmdbg(1),pmlogger(1),pmseries(1),redis-server(1),PMAPI(3),PMWEBAPI(3),pmGetOptions(3),pcp.conf(5)andpcp.env(5).

PCP Performance Co-Pilot