The option -h host directs any PCP utility (such as pmchart or dkvis) 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 option -a archive directs the utility to treat the PCP archive logs with base name archive as the principal source of performance metrics and metadata.

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 PCP archive log. For more information on archive logs and their use, see Chapter 6, “Archive Logging”.

The base name (archive ) of the PCP archive log used with the -a option implies the existence of the files created automatically by pmlogger, as listed in Table 3-1.

Some 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 mutually exclusive in all cases.

---

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

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

The distributed PMNS used in PCP 2.x 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 /var/pcp/pmns directory.

Refer to the pmns(4) and pmnscomp(1) man pages for details of PMNS structure and creation.

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.

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 30min 

-S -1hour 

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

-S 1hour -T 45mins

-O -0 

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

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.

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

The pmsocks command and its related files and scripts allow PCP clients running on hosts located on the internal side of a TCP/IP sockd firewall system to monitor remote hosts on the other side of the firewall system. The basic syntax is as follows, where tool is an arbitrary PCP application, typically a monitoring tool:

pmsocks tool args

The pmsocks script prepares the necessary environment variables and then executes the PCP tool specified in tool across the firewall. For example, this command runs dkvis with metrics fetched from remotehost on the other side of the firewall:

pmsocks dkvis -h remotehost 

The configuration file is /etc/pcp_socks.conf, and the network-specific information in this file is set to correspond with your network. Complete information on this customization can be found in the pmsocks(1) man page.

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.

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 be used to keep the system clocks on the collector systems synchronized; for information on ntp(1) see /usr/share/doc/ntp-4.1.1 .