3. Common Conventions and Arguments

This chapter deals with the user interface components that are common to most text-based utilities that make up the monitor portion of Performance Co-Pilot (PCP). These are the major sections in this chapter:

Section 3.1, “Alternate Metrics Source Options”, details some basic standards used in the development of PCP tools.

Section 3.2, “General PCP Tool Options”, details other options to use with PCP tools.

Section 3.3, “Time Duration and Control”, describes the time control dialog and time-related command line options available for use with PCP tools.

Section 3.4, “PCP Environment Variables”, describes the environment variables supported by PCP tools.

Section 3.5, “Running PCP Tools through a Firewall”, describes how to execute PCP tools that must retrieve performance data from the Performance Metrics Collection Daemon (PMCD) on the other side of a TCP/IP security firewall.

Section 3.6, “Transient Problems with Performance Metric Values”, covers some uncommon scenarios that may compromise performance metric integrity over the short term.

Many of the utilities provided with PCP conform to a common set of naming and syntactic conventions for command line arguments and options. This section outlines these conventions and their meaning. The options may be generally assumed to be honored for all utilities supporting the corresponding functionality.

In all cases, the man pages for each utility fully describe the supported command arguments and options.

Command line options are also relevant when starting PCP applications from the desktop using the Alt double-click method. This technique launches the pmrun program to collect additional arguments to pass along when starting a PCP application.

3.1. Alternate Metrics Source Options

The default source of performance metrics is from PMCD on the local host. This default pmcd connection will be made using the Unix domain socket, if the platform supports that, else a localhost Inet socket connection is made. This section describes how to obtain metrics from sources other than this default.

3.1.1. Fetching Metrics from Another Host

The option -h host directs any PCP utility (such as pmchart or pmie) to make a connection with the PMCD instance running on host. Once established, this connection serves as the principal real-time source of performance metrics and metadata. The host specification may be more than a simple host name or address - it can also contain decorations specifying protocol type (secure or not), authentication information, and other connection attributes. Refer to the PCPIntro(1) man page for full details of these, and examples of use of these specifications can also be found in the PCP Tutorials and Case Studies companion document.

3.1.2. ⁠Fetching Metrics from an Archive Log

The option -a archive directs the utility to treat the set of PCP archive logs designated by archive as the principal source of performance metrics and metadata. archive is a comma-separated list of names, each of which may be the base name of an archive or the name of a directory containing archives.

PCP archive logs are created with pmlogger. Most PCP utilities operate with equal facility for performance information coming from either a real-time feed via PMCD on some host, or for historical data from a set of PCP archive logs. For more information on archive logs and their use, see Chapter 6, Archive Logging.

The list of names (archive) used with the -a option implies the existence of the files created automatically by pmlogger, as listed in Table 3.1, “Physical Filenames for Components of a PCP Archive Log”.

Table 3.1. Physical Filenames for Components of a PCP Archive Log

Filename

Contents

archive. index

Temporal index for rapid access to archive contents

archive. meta

Metadata descriptions for performance metrics and instance domains appearing in the archive

archive.N

Volumes of performance metrics values, for N = 0,1,2,…

Most tools are able to concurrently process multiple PCP archive logs (for example, for retrospective analysis of performance across multiple hosts), and accept either multiple -a options or a comma separated list of archive names following the -a option.

Note

The -h and -a options are almost always mutually exclusive. Currently, pmchart is the exception to this rule but other tools may continue to blur this line in the future.

3.2. General PCP Tool Options

The following sections provide information relevant to most of the PCP tools. It is presented here in a single place for convenience.

3.2.1. ⁠Common Directories and File Locations

The following files and directories are used by the PCP tools as repositories for option and configuration files and for binaries:

${PCP_DIR}/etc/pcp.env

Script to set PCP run-time environment variables.

${PCP_DIR}/etc/pcp.conf

PCP configuration and environment file.

${PCP_PMCDCONF_PATH}

Configuration file for Performance Metrics Collection Daemon (PMCD). Sets environment variables, including PATH.

${PCP_BINADM_DIR}/pmcd

The PMCD binary.

${PCP_PMCDOPTIONS_PATH}

Command line options for PMCD.

${PCP_RC_DIR}/pmcd

The PMCD startup script.

${PCP_BIN_DIR}/pcptool

Directory containing PCP tools such as pmstat , pminfo, pmlogger, pmlogsummary, pmchart, pmie, and so on.

${PCP_SHARE_DIR}

Directory containing shareable PCP-specific files and repository directories such as bin, demos, examples and lib.

${PCP_VAR_DIR}

Directory containing non-shareable (that is, per-host) PCP specific files and repository directories.

${PCP_BINADM_DIR}/pcptool

PCP tools that are typically not executed directly by the end user such as pmcd_wait.

${PCP_SHARE_DIR}/lib/pcplib

Miscellaneous PCP libraries and executables.

${PCP_PMDAS_DIR}

Performance Metric Domain Agents (PMDAs), one directory per PMDA.

${PCP_VAR_DIR}/config

Configuration files for PCP tools, typically with one directory per tool.

${PCP_DEMOS_DIR}

Demonstration data files and example programs.

${PCP_LOG_DIR}

By default, diagnostic and trace log files generated by PMCD and PMDAs. Also, the PCP archive logs are managed in one directory per logged host below here.

${PCP_VAR_DIR}/pmns

Files and scripts for the Performance Metrics Name Space (PMNS).

3.2.2. Alternate Performance Metric Name Spaces

The Performance Metrics Name Space (PMNS) defines a mapping from a collection of human-readable names for performance metrics (convenient to the user) into corresponding internal identifiers (convenient for the underlying implementation).

The distributed PMNS used in PCP avoids most requirements for an alternate PMNS, because clients’ PMNS operations are supported at the Performance Metrics Collection Daemon (PMCD) or by means of PMNS data in a PCP archive log. The distributed PMNS is the default, but alternates may be specified using the -n namespace argument to the PCP tools. When a PMNS is maintained on a host, it is likely to reside in the ${PCP_VAR_DIR}/pmns directory.

3.3. Time Duration and Control

The periodic nature of sampling performance metrics and refreshing the displays of the PCP tools makes specification and control of the temporal domain a common operation. In the following sections, the services and conventions for specifying time positions and intervals are described.

3.3.1. ⁠Performance Monitor Reporting Frequency and Duration

Many of the performance monitoring utilities have periodic reporting patterns. The -t interval and -s samples options are used to control the sampling (reporting) interval, usually expressed as a real number of seconds (interval), and the number of samples to be reported, respectively. In the absence of the -s flag, the default behavior is for the performance monitoring utilities to run until they are explicitly stopped.

The interval argument may also be expressed in terms of minutes, hours, or days, as described in the PCPIntro(1) man page.

3.3.2. ⁠Time Window Options

The following options may be used with most PCP tools (typically when the source of the performance metrics is a PCP archive log) to tailor the beginning and end points of a display, the sample origin, and the sample time alignment to your convenience.

The -S, -T, -O and -A command line options are used by PCP applications to define a time window of interest.

-S duration

The start option may be used to request that the display start at the nominated time. By default, the first sample of performance data is retrieved immediately in real-time mode, or coincides with the first sample of data of the first archive in a set of PCP archive logs in archive mode. For archive mode, the -S option may be used to specify a later time for the start of sampling. By default, if duration is an integer, the units are assumed to be seconds.

To specify an offset from the beginning of a set of PCP archives (in archive mode) simply specify the offset as the duration. For example, the following entry retrieves the first sample of data at exactly 30 minutes from the beginning of a set of PCP archives:

-S 30min

To specify an offset from the end of a set of PCP archives, prefix the duration with a minus sign. In this case, the first sample time precedes the end of archived data by the given duration. For example, the following entry retrieves the first sample exactly one hour preceding the last sample in a set of PCP archives:

-S -1hour

To specify the calendar date and time (local time in the reporting timezone) for the first sample, use the ctime(3) syntax preceded by an “at” sign (@). For example, the following entry specifies the date and time to be used:

-S '@ Mon Mar 4 13:07:47 2017'

Note that this format corresponds to the output format of the date command for easy “cut and paste.” However, be sure to enclose the string in quotes so it is preserved as a single argument for the PCP tool.

For more complete information on the date and time syntax, see the PCPIntro(1) man page.

-T duration

The terminate option may be used to request that the display stop at the time designated by duration. By default, the PCP tools keep sampling performance data indefinitely (in real-time mode) or until the end of a set of PCP archives (in archive mode). The -T option may be used to specify an earlier time to terminate sampling.

The interpretation for the duration argument in a -T option is the same as for the -S option, except for an unsigned time interval that is interpreted as being an offset from the start of the time window as defined by the default (now for real time, else start of archive set) or by a -S option. For example, these options define a time window that spans 45 minutes, after an initial offset (or delay) of 1 hour:

-S 1hour -T 45mins

-O duration

By default, samples are fetched from the start time (see the description of the -S option) to the terminate time (see the description of the -T option). The offset -O option allows the specification of a time between the start time and the terminate time where the tool should position its initial sample time. This option is useful when initial attention is focused at some point within a larger time window of interest, or when one PCP tool wishes to launch another PCP tool with a common current point of time within a shared time window.

The duration argument accepted by -O conforms to the same syntax and semantics as the duration argument for -T. For example, these options specify that the initial position should be the end of the time window:

-O -0

This is most useful with the pmchart command to display the tail-end of the history up to the end of the time window.

-A alignment

By default, performance data samples do not necessarily happen at any natural unit of measured time. The -A switch may be used to force the initial sample to be on the specified alignment. For example, these three options specify alignment on seconds, half hours, and whole hours:

-A 1sec
-A 30min
-A 1hour

The -A option advances the time to achieve the desired alignment as soon as possible after the start of the time window, whether this is the default window, or one specified with some combination of -A and -O command line options.

Obviously the time window may be overspecified by using multiple options from the set -t, -s, -S, -T, -A, and -O. Similarly, the time window may shrink to nothing by injudicious choice of options.

In all cases, the parsing of these options applies heuristics guided by the principal of “least surprise”; the time window is always well-defined (with the end never earlier than the start), but may shrink to nothing in the extreme.

3.3.3. Timezone Options

All utilities that report time of day use the local timezone by default. The following timezone options are available:

-z

Forces times to be reported in the timezone of the host that provided the metric values (the PCP collector host). When used in conjunction with -a and multiple archives, the convention is to use the timezone from the first named archive.

-Z timezone

Sets the TZ variable to a timezone string, as defined in environ(7), for example, -Z UTC for universal time.

3.4. PCP Environment Variables

When you are using PCP tools and utilities and are calling PCP library functions, a standard set of defined environment variables are available in the ${PCP_DIR}/etc/pcp.conf file. These variables are generally used to specify the location of various PCP pieces in the file system and may be loaded into shell scripts by sourcing the ${PCP_DIR}/etc/pcp.env shell script. They may also be queried by C, C++, perl and python programs using the pmGetConfig library function. If a variable is already defined in the environment, the values in the pcp.conf file do not override those values; that is, the values in pcp.conf serve only as installation defaults. For additional information, see the pcp.conf(5), pcp.env(5), and pmGetConfig(3) man pages.

The following environment variables are recognized by PCP (these definitions are also available on the PCPIntro(1) man page):

PCP_COUNTER_WRAP

Many of the performance metrics exported from PCP agents expect that counters increase monotonically. Under some circumstances, one value of a metric may be smaller than the previously fetched value. This can happen when a counter of finite precision overflows, when the PCP agent has been reset or restarted, or when the PCP agent exports values from an underlying instrumentation that is subject to asynchronous discontinuity.

If set, the PCP_COUNTER_WRAP environment variable indicates that all such cases of a decreasing counter should be treated as a counter overflow; and hence the values are assumed to have wrapped once in the interval between consecutive samples. Counter wrapping was the default in versions before the PCP release 1.3.

PCP_STDERR

Specifies whether pmprintf() error messages are sent to standard error, an pmconfirm dialog box, or to a named file; see the pmprintf(3) man page. Messages go to standard error if PCP_STDERR is unset or set without a value. If this variable is set to DISPLAY, then messages go to an pmconfirm dialog box; see the pmconfirm(1) man page. Otherwise, the value of PCP_STDERR is assumed to be the name of an output file.

PMCD_CONNECT_TIMEOUT

When attempting to connect to a remote PMCD on a system that is booting or at the other end of a slow network link, some PMAPI routines could potentially block for a long time until the remote system responds. These routines abort and return an error if the connection has not been established after some specified interval has elapsed. The default interval is 5 seconds. This may be modified by setting this variable in the environment to a larger number of seconds for the desired time out. This is most useful in cases where the remote host is at the end of a slow network, requiring longer latencies to establish the connection correctly.

PMCD_PORT

This TCP/IP port is used by PMCD to create the socket for incoming connections and requests. The default is port number 44321, which you may override by setting this variable to a different port number. If a non-default port is in effect when PMCD is started, then every monitoring application connecting to that PMCD must also have this variable set in its environment before attempting a connection.

PMCD_LOCAL

This setting indicates that PMCD must only bind to the loopback interface for incoming connections and requests. In this mode, connections from remote hosts are not possible.

PMCD_RECONNECT_TIMEOUT

When a monitor or client application loses its connection to a PMCD, the connection may be reestablished by calling the pmReconnectContext(3) PMAPI function. However, attempts to reconnect are controlled by a back-off strategy to avoid flooding the network with reconnection requests. By default, the back-off delays are 5, 10, 20, 40, and 80 seconds for consecutive reconnection requests from a client (the last delay is repeated for any further attempts after the last delay in the list). Setting this environment variable to a comma-separated list of positive integers redefines the back-off delays. For example, setting the delays to 1,2 will back off for 1 second, then back off every 2 seconds thereafter.

PMCD_REQUEST_TIMEOUT

For monitor or client applications connected to PMCD, there is a possibility of the application hanging on a request for performance metrics or metadata or help text. These delays may become severe if the system running PMCD crashes or the network connection is lost or the network link is very slow. By setting this environment variable to a real number of seconds, requests to PMCD timeout after the specified number of seconds. The default behavior is to wait 10 seconds for a response from every PMCD for all applications.

PMLOGGER_PORT

This environment variable may be used to change the base TCP/IP port number used by pmlogger to create the socket to which pmlc instances try to connect. The default base port number is 4330. If used, this variable should be set in the environment before pmlogger is executed. If pmlc and pmlogger are on different hosts, then obviously PMLOGGER_PORT must be set to the same value in both places.

PMLOGGER_LOCAL

This environment variable indicates that pmlogger must only bind to the loopback interface for pmlc connections and requests. In this mode, pmlc connections from remote hosts are not possible. If used, this variable should be set in the environment before pmlogger is executed.

PMPROXY_PORT This environment variable may be used to change the base TCP/IP port number used by pmproxy to create the socket to which proxied clients connect, on their way to a distant pmcd.

PMPROXY_LOCAL

This setting indicates that pmproxy must only bind to the loopback interface for incoming connections and requests. In this mode, connections from remote hosts are not possible.

3.5. Running PCP Tools through a Firewall

In some production environments, the Performance Co-Pilot (PCP) monitoring hosts are on one side of a TCP/IP firewall, and the PCP collector hosts may be on the other side.

If the firewall service sits between the monitor and collector tools, the pmproxy service may be used to perform both packet forwarding and DNS proxying through the firewall; see the pmproxy(1) man page. Otherwise, it is necessary to arrange for packet forwarding to be enabled for those TCP/IP ports used by PCP, namely 44321 (or the value of the PMCD_PORT environment variable) for connections to PMCD.

3.5.1. ⁠The pmproxy service

The pmproxy service allows PCP clients running on hosts located on one side of a firewall to monitor remote hosts on the other side. The basic connection syntax is as follows, where tool is an arbitrary PCP application, typically a monitoring tool:

pmprobe -h remotehost@proxyhost

This extended host specification syntax is part of a larger set of available extensions to the basic host naming syntax - refer to the PCPIntro(1) man page for further details.

3.6. Transient Problems with Performance Metric Values

Sometimes the values for a performance metric as reported by a PCP tool appear to be incorrect. This is typically caused by transient conditions such as metric wraparound or time skew, described below. These conditions result from design decisions that are biased in favor of lightweight protocols and minimal resource demands for PCP components.

In all cases, these events are expected to occur infrequently, and should not persist beyond a few samples.

3.6.1. Performance Metric Wraparound

Performance metrics are usually expressed as numbers with finite precision. For metrics that are cumulative counters of events or resource consumption, the value of the metric may occasionally overflow the specified range and wraparound to zero.

Because the value of these counter metrics is computed from the rate of change with respect to the previous sample, this may result in a transient condition where the rate of change is an unknown value. If the PCP_COUNTER_WRAP environment variable is set, this condition is treated as an overflow, and speculative rate calculations are made. In either case, the correct rate calculation for the metric returns with the next sample.

3.6.2. Time Dilation and Time Skew

If a PMDA is tardy in returning results, or the PCP monitoring tool is connected to PMCD via a slow or congested network, an error might be introduced in rate calculations due to a difference between the time the metric was sampled and the time PMCD sends the result to the monitoring tool.

In practice, these errors are usually so small as to be insignificant, and the errors are self-correcting (not cumulative) over consecutive samples.

A related problem may occur when the system time is not synchronized between multiple hosts, and the time stamps for the results returned from PMCD reflect the skew in the system times. In this case, it is recommended that NTP (network time protocol) be used to keep the system clocks on the collector systems synchronized; for information on NTP refer to the ntpd(1) man page.