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 7, “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.0 avoids most requirements for an alternate PMNS, because clients' PMNS operations are supported at the 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) reference 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) reference 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 time zone by default.

The pmtime dialog is invoked through the PCP tools when you select the Show Time Control option from the Options menu of most PCP tools. The dialog may also be exposed by selecting the “time control state” button at the bottom left-hand corner of the pmchart display or the top left-hand corner of a 3D performance scene displayed with the pmview or oview tools. For more information on the “time control state” button, see the reference pages for pmview(1), pmchart(1), oview(1), or pmtime(1).

If the PCP tool is displaying performance metrics from a real-time source, the pmtime dialog looks similar to that shown in Figure 3-2.

This dialog can be used to set the sample interval and units; the latter may be in milliseconds, seconds, minutes, hours, days, or weeks.

To change the units, select the measurement of time you want from the option menu (labelled Seconds in Figure 3-2).

Figure 3-2. pmtime Live Time Control Dialog

To change the interval, enter the new value in the Interval text box, and press Enter. All PCP tools attached to the pmtime control dialog are notified of the new interval, and will update their displays immediately to reflect the new sampling rate.

The ability to start and stop recording of performance activity is available from the pmchart, pmview, and oview windows. See “Creating a PCP Archive From a pmchart Session” for information about the pmchart interface.

Alternatively use pmlogger directly, as described in Chapter 7, “Archive Logging.”

The ability to provide retrospective performance analysis in the PCP framework is provided by making the monitor tools able to deal interchangeably with real-time sources of performance metrics and PCP archive logs. For more information on archive logging, see Chapter 7.

When a PCP tool is displaying performance metrics from a PCP archive log, and the pmtime dialog is exposed, it looks similar to that shown in Figure 3-3.

Figure 3-3. pmtime Archive Time Control Dialog

As with the live pmtime dialog, the user may change the update interval; however, a number of other controls are available:

The menus of pmtime ArchiveTime Control provide the following additional features:

Options Menu

Timezone option		Select an alternative time zone for all displayed dates and times; all PCP tools attached to the pmtime control are notified of the new time zone. Because the UTC time zone is universal, it is useful when several archives or live sources of data are being displayed in multiple instances of the tools, and comparisons between performance metrics are required to be temporally correlated. Whenever a new source of metrics is opened, whether an archive or live, the time zone at that source of metrics is added to the list in the option menu. The default time zone is that of the local host where the tool is being run.
Show Bounds... option		Expose the Archive Time Bounds dialog, which shows the current time window that defines the earliest and latest time for which performance may be displayed from the current archives. Figure 3-4. pmtime Archive Time Bounds Dialog
Detail option		For output fields, selectively include or exclude the year in the date or milliseconds in time. The year is shown by default, milliseconds are not.

The pmsocks command and its related files and scripts allow Performance Co-Pilot (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 this is the file where the network-specific information must be set to correspond with your network. Complete information on this customization can be found in the pmsocks(1) reference 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 wrap around 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 timestamps for the results returned from pmcd reflect the skew in the system times. In this case, it is recommended that either timeslave or timed be used to keep the system clocks on the collector systems synchronized; see timed(1M).