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.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 pmtime PCP Live Time Control dialog, shown in Figure 3-2, 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 three-dimensional (3D) performance scene displayed with the pmview or oview tools.

For more information on the “time control state” button, see the pmview(1), pmchart(1), oview(1), or pmtime(1) man page.

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.

Figure 3-2. pmtime PCP Live Time Control Dialog

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 Options menu (labelled Seconds in Figure 3-2).

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 using the File -> Record option from the menu bar. See “Creating a PCP Archive from a pmchart Session” in Chapter 4, 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, “Archive Logging”.

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

Figure 3-3. pmtime PCP 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 Archive Time Control provide the following additional features:

Options Menu

The Options menu supports three options:

Timezone	Selects an alternative timezone for all displayed dates and times; all PCP tools attached to the pmtime control are notified of the new timezone. Because the UTC timezone 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 timezone at that source of metrics is added to the list in the Options menu. The default timezone is that of the local host where the tool is being run.
Show Bounds...	Exposes the Archive Time Bounds dialog, shown in Figure 3-4. This dialog 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	For output fields, selectively includes or excludes 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 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 either timeslave or timed be used to keep the system clocks on the collector systems synchronized; see the timed(1M) man page.