1PCPINTRO(1) General Commands Manual PCPINTRO(1)
2
6 PCPIntro - introduction to the Performance Co-Pilot (PCP)
7
9 The Performance Co-Pilot (PCP) is a toolkit designed for monitoring and
10 managing system-level performance. These services are distributed and
11 scalable to accommodate the most complex system configurations and per‐
12 formance problems.
13 PCP supports many different platforms, including (but not limited to)
15 Linux, MacOSX, Solaris and Windows. From a high-level PCP can be con‐
16 sidered to contain two classes of software utility:
17 PCP Collectors
19 These are the parts of PCP that collect and extract performance
20 data from various sources, for example the operating system
21 kernel.
22 PCP Monitors
24 These are the parts of PCP that display data collected from
25 hosts (or archives) that have the PCP Collector installed.
26 Many monitor tools are available as part of the core PCP re‐
27 lease, while other (typically graphical) monitoring tools are
28 available separately in the PCP GUI package.
29 This manual entry describes the high-level features and options common
31 to most PCP utilities available on all platforms.
32
34 The PCP architecture is distributed in the sense that any PCP tool may
35 be executing remotely. On the host (or hosts) being monitored, each
36 domain of performance metrics, whether the kernel, a service layer, a
37 database management system, a web server, an application, etc. re‐
38 quires a Performance Metrics Domain Agent (PMDA) which is responsible
39 for collecting performance measurements from that domain. All PMDAs
40 are controlled by the Performance Metrics Collector Daemon (pmcd(1)) on
41 the same host.
42 Client applications (the monitoring tools) connect to pmcd(1), which
44 acts as a router for requests, by forwarding requests to the appropri‐
45 ate PMDA and returning the responses to the clients. Clients may also
46 access performance data from sets of PCP archives (created using pmlog‐
47 ger(1)) for retrospective analysis.
48 Security philosophy
50 PCP redistributes a wealth of performance information within a host and
51 across its networks. The following security philosophy underlies the
52 setting of several defaults that control how much information is sent
53 and received.
54 By default, the information exposed by PMCD about a host is approxi‐
56 mately of the same level of confidentiality as available to a com‐
57 pletely unprivileged user on that host. So, performance data that is
58 available to be read completely freely on a machine may be made avail‐
59 able by PMCD to the network.
60 However, the host running PMCD and its network is not assumed to run
62 only friendly applications. Therefore, write type operations, includ‐
63 ing from the local host, are not permitted by default.
64 These defaults may be overridden (expanded or reduced) in several ways,
66 including by specifying network ACLs in pmcd.conf, activating non-de‐
67 fault PMDAs, or by using PMCD connections that pass user credentials.
68 For example, some PMDAs automatically provide greater information for
69 particular credentialed users or groups.
70 Applications
72 The following performance monitoring applications are primarily console
73 based, typically run directly from the command line, and are just a
74 small subset of the tools available as part of the base PCP package.
75 Each tool or command is documented completely in its own reference
77 page.
78 pmstat Outputs an ASCII high-level summary of system performance.
80 pmie An inference engine that can evaluate predicate-action rules to
82 perform alarms and automate system management tasks.
83 pminfo Interrogate specific performance metrics and the metadata that
85 describes them.
86 pmlogger
88 Generates PCP archives of performance metrics suitable for re‐
89 play by most PCP tools.
90 pmrep Highly customizable performance metrics reporter with support
92 for various different output modes.
93 pmval Simple periodic reporting for some or all instances of a perfor‐
95 mance metric, with optional VCR time control.
96 If the PCP GUI package is installed then the following additional tools
98 are available.
99 pmchart
101 Displays trends over time of arbitrarily selected performance
102 metrics from one or more hosts.
103 pmtime Time control utility for coordinating the time between multiple
105 tools (including pmchart and pmval).
106 pmdumptext
108 Produce ASCII reports for arbitrary combinations of performance
109 metrics.
110
112 There is a set of common command line arguments that are used consis‐
113 tently by most PCP tools.
114 -a archive, --archive=archive
116 Performance metric information is retrospectively retrieved from
117 the set of Performance Co-Pilot (PCP) archives identified by ar‐
118 chive previously generated by pmlogger(1). See LOGIMPORT(3) and
119 LOGARCHIVE(5) for archive creation interfaces and format docu‐
120 mentation.
121 archive is a comma-separated list of names, each of which may be
123 the name of a directory containing one or more archives, the
124 base name common to all of the physical files created by an in‐
125 stance of pmlogger(1), or any one of the physical files, e.g.
126 /path/to/myarchives (directory) or myarchive (base name) or
127 myarchive.meta (the metadata file) or myarchive.index (the tem‐
128 poral index) or myarchive.0 (the first data volume of archive)
129 or myarchive.0.bz2 or myarchive.0.bz (the first data volume com‐
130 pressed with bzip2(1)) or myarchive.0.gz or myarchive.0.Z or
131 myarchive.0.z (the first data volume compressed with gzip(1)),
132 myarchive.1 or myarchive.3.bz2 or myarchive.42.gz etc.
133 -h host, --host=host
135 Unless directed to another host by the -h (or --host) option, or
136 to a set of archives by the -a (or --archive) option, the source
137 of performance metrics will be the Performance Metrics Collector
138 Daemon (PMCD) on the local host. Refer to the PMCD HOST SPECI‐
139 FICATION section later for further details on the many options
140 available when forming the host specification, as well as a de‐
141 tailed description of the default local host connection. The -a
142 (or --archive), and -h (or --host) options are mutually exclu‐
143 sive.
144 -s samples, --samples=samples
146 The argument samples defines the number of samples to be re‐
147 trieved and reported. If samples is 0 or -s (or --samples) is
148 not specified, the application will sample and report continu‐
149 ously (in real time mode) or until the end of the set of PCP ar‐
150 chives (in archive mode).
151 -z, --hostzone
153 Change the reporting timezone to the local timezone at the host
154 that is the source of the performance metrics, as identified via
155 either the -h (or --host) or -a (or --archive) options.
156 -Z timezone, --timezone=timezone
158 By default, applications report the time of day according to the
159 local timezone on the system where the application is executed.
160 The -Z (or --timezone) option changes the timezone to timezone
161 in the format of the environment variable TZ as described in en‐
162 viron(7).
163 -D debugspec, --debug=debugspec
165 Sets the PCP debugging options to debugspec to enable diagnos‐
166 tics and tracing that is most helpful for developers or when
167 trying to diagnose the misbehaviour of a PCP application. de‐
168 bugspec should be a comma-separated list of debugging option
169 name(s) and/or decimal integers, see pmdbg(1) for a description
170 of the supported option names and values.
171 In the absence of a live or archive source of metrics, a heuristic
173 search for archive logs for the local host can be invoked via the -O
174 (or --origin) option. When using this option without an explicit
175 source of metrics, monitor tools attempt to use archives from a system
176 archive location such as $PCP_LOG_DIR/pmlogger/`hostname`. Refer to
177 the TIME WINDOW SPECIFICATION section below for details on the accept‐
178 able syntax for the origin option, but a typical invocation in this
179 mode would be -O today or --origin yesterday.
180
182 Most PCP tools operate with periodic sampling or reporting, and the -t
183 (or --interval) and -A (or --align) options may be used to control the
184 duration of the sample interval and the alignment of the sample times.
185 -t interval, --interval=interval
187 Set the update or reporting interval.
188 The interval argument is specified as a sequence of one or more
190 elements of the form
191 number[units]
192 where number is an integer or floating point constant (parsed
193 using strtod(3)) and the optional units is one of: seconds, sec‐
194 ond, secs, sec, s, minutes, minute, mins, min, m, hours, hour,
195 h, days, day and d. If the unit is empty, second is assumed.
196 In addition, the upper case (or mixed case) version of any of
198 the above is also acceptable.
199 Spaces anywhere in the interval are ignored, so 4 days 6 hours
201 30 minutes, 4day6hour30min, 4d6h30m and 4d6.5h are all equiva‐
202 lent.
203 Multiple specifications are additive, for example ``1hour 15mins
205 30secs'' is interpreted as 3600+900+30 seconds.
206 -A align, --align=align
208 By default samples are not necessarily aligned on any natural
209 unit of time. The -A or --align option may be used to force the
210 initial sample to be aligned on the boundary of a natural time
211 unit. For example -A 1sec, -A 30min and --align 1hour specify
212 alignment on whole seconds, half and whole hours respectively.
213 The align argument follows the syntax for an interval argument
215 described above for the -t or --interval option.
216 Note that alignment occurs by advancing the time as required,
218 and that -A (or --align) acts as a modifier to advance both the
219 start of the time window (see the next section) and the origin
220 time (if the -O or --origin option is specified).
221
223 Many PCP tools are designed to operate in some time window of interest,
224 for example to define a termination time for real-time monitoring or to
225 define a start and end time within a set of PCP archive logs.
226 In the absence of the -O (or --origin) and -A (or --align) options to
228 specify an initial sample time origin and time alignment (see above),
229 the PCP application will retrieve the first sample at the start of the
230 time window.
231 The following options may be used to specify a time window of interest.
233 -S starttime, --start=starttime
235 By default the time window commences immediately in real-time
236 mode, or coincides with time at the start of the set of PCP ar‐
237 chive logs in archive mode. The -S or --start option may be
238 used to specify a later time for the start of the time window.
239 The starttime parameter may be given in one of three forms (in‐
241 terval is the same as for the -t or --interval option as de‐
242 scribed above, datetime is described below):
243 interval
245 To specify an offset from the current time (in real-time
246 mode) or the beginning of a set of PCP archives (in ar‐
247 chive mode) simply specify the interval of time as the
248 argument. For example -S 30min will set the start of the
249 time window to be exactly 30 minutes from now in real-
250 time mode, or exactly 30 minutes from the start of a set
251 of PCP archives.
252 -interval
254 To specify an offset from the end of a set of PCP archive
255 logs, prefix the interval argument with a minus sign. In
256 this case, the start of the time window precedes the time
257 at the end of the set of archives by the given interval.
258 For example -S -1hour will set the start of the time win‐
259 dow to be exactly one hour before the time of the last
260 sample in a set of PCP archive logs.
261 @datetime
263 To specify the calendar date and time (local time in the
264 reporting timezone) for the start of the time window, use
265 the datetime syntax preceded by an at sign. Refer to the
266 datetime description below for detailed information.
267 -T endtime, --finish=endtime
269 By default the end of the time window is unbounded (in real-time
270 mode) or aligned with the time at the end of a set of PCP ar‐
271 chive logs (in archive mode). The -T or --finish option may be
272 used to specify an earlier time for the end of the time window.
273 The endtime parameter may be given in one of three forms (inter‐
275 val is the same as for the -t or --interval option as described
276 above, datetime is described below):
277 interval
279 To specify an offset from the start of the time window
280 simply use the interval of time as the argument. For ex‐
281 ample -T 2h30m will set the end of the time window to be
282 2 hours and 30 minutes after the start of the time win‐
283 dow.
284 -interval
286 To specify an offset back from the time at the end of a
287 set of PCP archive logs, prefix the interval argument
288 with a minus sign. For example -T -90m will set the end
289 of the time window to be 90 minutes before the time of
290 the last sample in a set of PCP archive logs.
291 @datetime
293 To specify the calendar date and time (local time in the
294 reporting timezone) for the end of the time window, use
295 the datetime syntax preceded by an at sign. Refer to the
296 datetime description below for detailed information.
297 -O origin, --origin=origin
299 By default samples are fetched from the start of the time window
300 (see description of -S or --start option) to the end of the time
301 window (see description of -T or --finish option). The -O or
302 --origin option allows the specification of an origin within the
303 time window to be used as the initial sample time. This is use‐
304 ful for interactive use of a PCP tool with the pmtime(1) VCR re‐
305 play facility.
306 The origin argument accepted by -O (or --origin) conforms to the
308 same syntax and semantics as the starttime argument for the -T
309 (or --finish) option.
310 For example --origin -0 specifies that the initial position
312 should be at the end of the time window; this is most useful
313 when wishing to replay ``backwards'' within the time window.
314 The datetime argument for the -O (or --origin), -S (or --start) and -T
316 (or --finish) options consists of:
317 date time zone day relative
318 A date can be one of: YY-MM-DD, MM/DD/YY, DD Month YYYY, or Month DD
319 YYYY. A time can be one of: HH:MM:SS, HH:MM. HH:MM can use either the
320 12 hour (via an am or pm suffix) or 24 hour convention. A day of the
321 week can be a spelled out day of the week, optionally preceded by an
322 ordinal number such as second Tuesday. A zone is a time zone value as
323 specified by the tzselect(8) command. A relative time can be a time
324 unit that is: preceded by a cardinal number such as 1 year or 2 months,
325 preceded by one of the time words this or last, or succeeded by the
326 time word ago. A relative time can also be one of the time words: yes‐
327 terday, today, tomorrow, now. Examples of datetime strings are:
328 1996-03-04 13:07:47 EST Mon, 1996-03-05 14:07:47 EST -1hour, Mon Mar 4
329 13:07:47 1996, Mar 4 1996, Mar 4, Mar, 13:07:50 or 13:08.
330 For any missing low order fields, the default value of 0 is assumed for
332 hours, minutes and seconds, 1 for day of the month and Jan for months.
333 Hence, the following are equivalent: --start '@ Mar 1996' and --start
334 '@ Mar 1 00:00:00 1996'.
335 If any high order fields are missing, they are filled in by starting
337 with the year, month and day from the current time (real-time mode) or
338 the time at the beginning of the set of PCP archive logs (archive mode)
339 and advancing the time until it matches the fields that are specified.
340 So, for example if the time window starts by default at ``Mon Mar 4
341 13:07:47 1996'', then --start @13:10 corresponds to 13:10:00 on Mon Mar
342 4, 1996, while --start @10:00 corresponds to 10:00:00 on Tue Mar 5,
343 1996 (note this is the following day).
344 For greater precision than afforded by datetime(3), the seconds compo‐
346 nent may be a floating point number.
347 If a timezone is not included in a datetime then there ares several in‐
349 terpretations available depending on the other command line options
350 used. The default is to use the local timezone on the system where the
351 PCP tool is being run. A -Z or --timezone option specifies an explicit
352 timezone, else a -z or --hostzone option changes the timezone to the
353 local timezone at the host that is the source of the performance met‐
354 rics.
355
357 The number of performance metric names supported by PCP on most plat‐
358 forms ranges from many hundreds to several thousand. The PCP libraries
359 and applications use an internal identification scheme that unambigu‐
360 ously associates a single integer with each known performance metric.
361 This integer is known as the Performance Metric Identifier, or PMID.
362 Although not a requirement, PMIDs tend to have global consistency
363 across all systems, so a particular performance metric usually has the
364 same PMID.
365 For all users and most applications, direct use of the PMIDs would be
367 inappropriate (this would limit the range of accessible metrics, make
368 the code hard to maintain, force the user interface to be particularly
369 baroque, and so on). Hence a Performance Metrics Name Space (PMNS) is
370 used to provide external names and a hierarchic classification for per‐
371 formance metrics. A PMNS is represented as a tree, with each node hav‐
372 ing a label, a pointer to either a PMID (for leaf nodes) or a set of
373 descendent nodes in the PMNS (for non-leaf nodes).
374 A node label must begin with an alphabetic character, followed by zero
376 or more characters drawn from the alphabetics, the digits and character
377 ``_'' (underscore). For alphabetic characters in a node label, upper
378 and lower case are distinguished.
379 By convention, the name of a performance metric is constructed by con‐
381 catenation of the node labels on a path through the PMNS from the root
382 node to a leaf node, with a ``.'' as a separator. The root node in the
383 PMNS is unlabeled, so all names begin with the label associated with
384 one of the descendent nodes below the root node of the PMNS, for exam‐
385 ple kernel.percpu.syscall. Typically (although this is not a require‐
386 ment) there would be at most one name for each PMID in a PMNS. For ex‐
387 ample kernel.all.cpu.idle and disk.dev.read are the unique names for
388 two distinct performance metrics, each with a unique PMID.
389 Groups of related PMIDs may be named by naming a non-leaf node in the
391 PMNS tree, for example disk.
392 The default local PMNS used by pmcd is located at
394 $PCP_VAR_DIR/pmns/root however the environment variable PMNS_DEFAULT
395 may be set to the full pathname of a different PMNS which will then be
396 used as the default local PMNS.
397 Most applications do not use the local PMNS directly, but rather import
399 parts of the PMNS as required from the same place that performance met‐
400 rics are fetched, i.e. from pmcd(1) for live monitoring or from a set
401 of PCP archives for retrospective monitoring.
402 To explore the PMNS use pminfo(1), or if the PCP GUI package is in‐
404 stalled the New Chart and Metric Search windows within pmchart(1).
405 Some performance metrics have a singular value. For example, the
407 available memory or number of context switches have one value per per‐
408 formance metric source, that is, one value per host. The metric de‐
409 scriptor (metadata) for each metric makes this fact known to applica‐
410 tions that process values for these single-valued metrics.
411 Some performance metrics have a set of values or instances in each im‐
413 plementing performance metric domain. For example, one value for each
414 disk, one value for each process, one value for each CPU, or one value
415 for each activation of a given application. When a metric has multiple
416 instances, the PMNS does not represent this in metric names; rather, a
417 single metric may have an associated set of values. Multiple values
418 are associated with the members of an instance domain, such that each
419 instance has a unique instance identifier within the associated in‐
420 stance domain. For example, the ''per CPU´´ instance domain may use
421 the instance identifiers 0, 1, 2, 3, and so on to identify the config‐
422 ured processors in the system. Internally, instance identifiers are
423 encoded as binary values, but each performance metric domain also sup‐
424 ports corresponding strings as external names for the instance identi‐
425 fiers, and these names are used at the user interface to the PCP utili‐
426 ties.
427 Multiple performance metrics may be associated with a single instance
429 domain. For example, per-process metrics under proc all share the same
430 instance domain.
431 PCP arranges for information describing instance domains to be exported
433 from the performance metric domains to the applications that require
434 this information. Applications may also choose to retrieve values for
435 all instances of a performance metric, or some arbitrary subset of the
436 available instances.
437 Metric names and the instance domain concept provides two-dimensions
439 for the modelling of performance metrics. This is a clear and simple
440 model, however on some occasions it does not suffice. For example, a
441 metric may wish to represent higher dimensional data such as ``per
442 CPU'' counters for each running process. In these cases it is common
443 to create a compound instance, where the name is composed of each com‐
444 ponent with a separator in-between (for example, ``87245::cpu7'' might
445 be used to separate process ID from CPU ID) to create flattened in‐
446 stance names. Additionally, such cases benefit from the use of metric
447 instances labels to explicitly show the separate components (continuing
448 the example from above, labels ``{"pid":87245,"cpu":7}'' might be
449 used).
450
452 In configuration files and (to a lesser extent) command line options,
453 metric specifications adhere to the following syntax rules by most
454 tools. See the tool specific manual pages for the exact syntax sup‐
455 ported.
456 If the source of performance metrics is real-time from pmcd(1) then the
458 accepted syntax is
459 host:metric[instance1,instance2,...]
460 If the source of performance metrics is a set of PCP archive logs then
462 the accepted syntax is
463 archive/metric[instance1,instance2,...]
464 The host:, archive/ and [instance1,instance2,...] components are all
466 optional.
467 The , delimiter in the list of instance names may be replaced by white
469 space.
470 Special characters in instance names may be escaped by surrounding the
472 name in double quotes or preceding the character with a backslash.
473 White space is ignored everywhere except within a quoted instance name.
475 An empty instance is silently ignored, and in particular ``[]'' is the
477 same as no instance, while ``[one,,,two]'' is parsed as specifying just
478 the two instances ``one'' and ``two''.
479 As a special case, if the host is the single character ``@'' then this
481 refers to a PM_CONTEXT_LOCAL source, see pmNewContext(3).
482
484 Since PCP version 3.6.11, a monitor can explicitly request a secure
485 connection to a collector host running pmcd(1) or pmproxy(1) using the
486 PM_CTXFLAG_SECURE context flag. If the PCP Collector host supports
487 this feature - refer to the pmcd.feature.secure metric for confirmation
488 of this - a TLS/SSL (Transport Layer Security or Secure Sockets Layer)
489 connection can be established which uses public key cryptography and
490 related techniques. These features aim to prevent eavesdropping and
491 data tampering from a malicious third party, as well as providing
492 server-side authentication (confident identification of a server by a
493 client) which can be used to guard against man-in-the-middle attacks.
494 A secure pmcd connection requires use of certificate-based authentica‐
496 tion. The security features offered by pmcd and pmproxy are imple‐
497 mented using the Network Security Services (NSS) APIs and utilities.
498 The NSS certutil tool can be used to create certificates suitable for
499 establishing trust between PCP monitor and collector hosts.
500 A complete description is beyond the scope of this document, refer to
502 the PCP ENVIRONMENT, FILES and SEE ALSO sections for detailed informa‐
503 tion. This includes links to tutorials on the steps involved in set‐
504 ting up the available security features.
505
507 In the absence of an explicit hostname specification, most tools will
508 default to the local host in live update mode. In PCP releases since
509 3.8.4 onward, this results in an efficient local protocol being se‐
510 lected - typically a Unix domain socket. If this option is used (which
511 can also be explicitly requested via the unix: host specification de‐
512 scribed below), it is important to note that all connections will be
513 automatically authenticated. In other words, the credentials of the
514 user invoking a client tool will automatically be made available to
515 pmcd(1) and all of its PMDAs, on the users behalf, such that results
516 can be customized to the privilege levels of individual users.
517 Names of remote hosts running the pmcd(1) daemon can of course also be
519 provided to request a remote host be used. The most basic form of pmcd
520 host specification is a simple host name, possibly including the domain
521 name if necessary. However, this can be extended in a number of ways
522 to further refine attributes of the connection made to pmcd.
523 The pmcd port number and also optional pmproxy(1) hostname and its port
525 number, can be given as part of the host specification, since PCP ver‐
526 sion 3.0. These supersede (and override) the old-style PMCD_PORT, PM‐
527 PROXY_HOST and PMPROXY_PORT environment variables.
528 The following are valid hostname specifications that specify connec‐
530 tions to pmcd on host nas1.acme.com with/without a list of ports,
531 with/without a pmproxy(1) connection through a firewall, and with IPv6
532 and IPv4 addresses as shown.
533 $ pcp --host nas1.acme.com:44321,4321@firewall.acme.com:44322
535 $ pcp --host nas1.acme.com:44321@firewall.acme.com:44322
536 $ pcp --host nas1.acme.com:44321@firewall.acme.com
537 $ pcp --host nas1.acme.com@firewall.acme.com
538 $ pcp --host nas1.acme.com:44321
539 $ pcp --host [fe80::2ad2:44ff:fe88:e4f1%p2p1]
540 $ pcp --host 192.168.0.103
541 In addition, ``connection attributes'' can also be specified. These
543 include username, password (can be given interactively and may depend
544 on the authentication mechanism employed), whether to target a specific
545 running container, whether to use secure (encrypted) or native (naked)
546 protocol, and so on. The previous examples all default to native pro‐
547 tocol, and use no authentication. This can be altered, as in the fol‐
548 lowing examples.
549 $ pcp --host pcps://app2.acme.com?container=cae8e6edc0d5
551 $ pcp --host pcps://nas1.acme.com:44321?username=tanya&method=gssapi
552 $ pcp --host pcps://nas2.acme.com@firewalls.r.us?method=plain
553 $ pcp --host pcp://nas3.acme.com
554 $ pcp --host 192.168.0.103?container=cae8e6edc0d5,method=scram-sha-256
555 $ pcp --host unix:
556 $ pcp --host local:
557 The choice of authentication method, and other resulting parameters
559 like username, optionally password, etc, depends on the SASL2 configu‐
560 ration used by each (remote) pmcd. Tutorials are available specifying
561 various aspects of configuring the authentication module(s) used, these
562 fine details are outside the scope of this document.
563 In all situations, host names can be used interchangeably with IPv4 or
565 IPv6 addressing (directly), as shown above. In the case of an IPv6 ad‐
566 dress, the full address must be enclosed by square brackets and the
567 scope (interface) must also be specified.
568 The final local: example above is now the default for most tools. This
570 connection is an automatically authenticated local host connection on
571 all platforms that support Unix domain sockets. No password is re‐
572 quired and authentication is automatic. This is also the most effi‐
573 cient (lowest overhead) communication channel.
574 The difference between unix: and local: is that the former is a strict
576 Unix domain socket specification (connection fails if it cannot connect
577 that way), whereas the latter has a more forgiving fallback to using
578 localhost (i.e. a regular Inet socket connection is used when Unix do‐
579 main socket connections are unavailable).
580
582 /etc/pcp.conf
583 Configuration file for the PCP runtime environment, see
584 pcp.conf(5).
585 /etc/pki/nssdb
587 Optionally contains a Network Security Services database with a
588 "PCP Collector" certificate providing trusted identification for
589 the collector host.
590 $HOME/.pcp
592 User-specific directories containing configuration files for cus‐
593 tomisation of the various monitor tools, such as pmchart(1).
594 $HOME/.pki/nssdb
596 A shared Network Security Services (NSS) database directory con‐
597 taining per-user certificates identifying known valid remote pmcd
598 collector hosts. The NSS certutil tool is one of several that can
599 be used to maintain this database.
600 $PCP_RC_DIR/pcp
602 Script for starting and stopping pmcd(1).
603 $PCP_PMCDCONF_PATH
605 Control file for pmcd(1).
606 $PCP_PMCDOPTIONS_PATH
608 Command line options passed to pmcd(1) when it is started from
609 $PCP_RC_DIR/pcp. All the command line option lines should start
610 with a hyphen as the first character. This file can also contain
611 environment variable settings of the form "VARIABLE=value".
612 $PCP_BINADM_DIR
614 Location of PCP utilities for collecting and maintaining PCP ar‐
615 chives, PMDA help text, PMNS files etc.
616 $PCP_PMDAS_DIR
618 Parent directory of the installation directory for Dynamic Shared
619 Object (DSO) PMDAs.
620 $PCP_RUN_DIR/pmcd.pid
622 If pmcd is running, this file contains an ascii decimal represen‐
623 tation of its process ID.
624 $PCP_LOG_DIR/pmcd
626 Default location of log files for pmcd(1), current directory for
627 running PMDAs. Archives generated by pmlogger(1) are generally
628 below $PCP_LOG_DIR/pmlogger.
629 $PCP_LOG_DIR/pmcd/pmcd.log
631 Diagnostic and status log for the current running pmcd(1) process.
632 The first place to look when there are problems associated with
633 pmcd.
634 $PCP_LOG_DIR/pmcd/pmcd.log.prev
636 Diagnostic and status log for the previous pmcd(1) instance.
637 $PCP_LOG_DIR/NOTICES
639 Log of pmcd(1) and PMDA starts, stops, additions and removals.
640 $PCP_VAR_DIR/config
642 Contains directories of configuration files for several PCP tools.
643 $PCP_SYSCONF_DIR/pmcd/rc.local
645 Local script for controlling PCP boot, shutdown and restart ac‐
646 tions.
647 $PCP_VAR_DIR/pmns
649 Directory containing the set of PMNS files for all installed PM‐
650 DAs.
651 $PCP_VAR_DIR/pmns/root
653 The ASCII PMNS(5) exported by pmcd(1) by default. This PMNS is be
654 the super set of all other PMNS files installed in
655 $PCP_VAR_DIR/pmns.
656 In addition, if the PCP product is installed the following files and
658 directories are relevant.
659 $PCP_LOG_DIR/NOTICES
661 In addition to the pmcd(1) and PMDA activity, may be used to log
662 alarms and notices from pmie(1) via pmpost(1).
663 $PCP_PMLOGGERCONTROL_PATH
665 Control file for pmlogger(1) instances launched from
666 $PCP_RC_DIR/pcp and/or managed by pmlogger_check(1) and pmlog‐
667 ger_daily(1) as part of a production PCP archive collection
668 setup.
669
671 In addition to the PCP run-time environment and configuration variables
672 described in the PCP ENVIRONMENT section below, the following environ‐
673 ment variables apply to all installations.
674 Note that most uses of these environment variables are optimized to
676 check the environment only the first time the variable might be used.
677 As the environment usually is not checked again, the only safe strategy
678 is to ensure all PCP-related environment variables are set before the
679 first call into any of the PCP libraries.
680 PCP_ALLOW_BAD_CERT_DOMAIN
682 When set, allow clients to accept certificates with mismatched
683 domain names with no prompt when they are sent by pmcd or other
684 server components. See PCP_SECURE_SOCKETS.
685 PCP_ALLOW_SERVER_SELF_CERT
687 When set, allow clients to accept self-signed certificates with
688 no prompt when they are sent by pmcd or other server components.
689 See PCP_SECURE_SOCKETS.
690 PCP_CONSOLE
692 When set, this changes the default console from /dev/tty (on
693 Unix) or CON: (on Windows) to be the specified console. The
694 special value of none can be used to indicate no console is
695 available for use. This is used in places where console-based
696 tools need to interact with the user, and in particular is used
697 when authentication is being performed.
698 PCP_DEBUG
700 When set, this variable provides an alternate to the -D command
701 line option described above to initialize the diagnostic and de‐
702 bug options. The value for $PCP_DEBUG is the same as for the -D
703 command line option, namely a comma-separated list of debugging
704 option name(s), and/or decimal integers, see pmdbg(1) for a de‐
705 scription of the supported option names and values.
706 PCP_DERIVED_CONFIG
708 When set, this variable defines a colon separated list of files
709 and/or directories (the syntax is the same as for the $PATH
710 variable for sh(1)). The components are expanded into a list of
711 files as follows: if a component of $PCP_DERIVED_CONFIG is a
712 file, then that file is added to the list, else if a component
713 is a directory then recursive descent is used to enumerate all
714 files below that directory and these are added to the list.
715 Each file in the resulting list is assumed to contain defini‐
717 tions of derived metrics as per the syntax described in pmLoad‐
718 DerivedConfig(3), and these are loaded in order.
719 Derived metrics may be used to extend the available metrics with
721 new (derived) metrics using simple arithmetic expressions.
722 If PCP_DERIVED_CONFIG is set, the derived metric definitions are
724 processed automatically as each new source of performance met‐
725 rics is established (i.e. each time a pmNewContext(3) is called)
726 or when requests are made against the PMNS.
727 Any component in the $PCP_DERIVED_CONFIG list or the expanded
729 list of files that is not a file, or is not a directory or is
730 not accessible (due to permissions or a bad symbolic link) will
731 be silently ignored.
732 PCP_IGNORE_MARK_RECORDS
734 When PCP archives logs are created there may be temporal gaps
735 associated with discontinuities in the time series of logged
736 data, for example when pmcd(1) is restarted or when multiple ar‐
737 chive logs are concatenated with pmlogextract(1). These discon‐
738 tinuities are internally noted with a <mark> record in the PCP
739 archive logs, and value interpolation as described in pmSet‐
740 Mode(3) is not supported across <mark> records (because the val‐
741 ues before and after a <mark> record are not necessarily from a
742 continuous time series). Sometimes the user knows the data se‐
743 mantics are sound in the region of the <mark> records, and
744 $PCP_IGNORE_MARK_RECORDS may be used to suppress the default be‐
745 haviour.
746 If PCP_IGNORE_MARK_RECORDS is set (but has no value) then all
748 <mark> records will be ignored. Otherwise the value $PCP_IG‐
749 NORE_MARK_RECORDS follows the syntax for an interval argument
750 described above for the -t option, and <mark> records will be
751 ignored if the time gap between the last record before the
752 <mark> and the first record after the <mark> is not more than
753 interval.
754 PCP_SECURE_SOCKETS
756 When set, this variable forces any monitor tool connections to
757 be established using the certificate-based secure sockets fea‐
758 ture. If the connections cannot be established securely, they
759 will fail.
760 PCP_SECURE_DB_METHOD
762 With secure socket connections, the certificate and key database
763 is stored using the sql: method by default. Use PCP_SE‐
764 CURE_DB_METHOD to override the default, most usually setting the
765 value to the empty string (for the older database methods).
766 PCP_SECURE_DB_PATH
768 When set, this variable specifies an alternate certificate data‐
769 base path for client tools. Similar to the action of the -C op‐
770 tion for pmcd(1) and pmproxy(1).
771 PCP_NSS_INIT_MODE
773 Mode to use to initialize the NSS certificate database when us‐
774 ing secure connections. This variable may be set to either
775 readonly or readwrite. If unset, the default is readwrite.
776 PCP_STDERR
778 Many PCP tools support the environment variable PCP_STDERR,
779 which can be used to control where error messages are sent.
780 When unset, the default behavior is that ``usage'' messages and
781 option parsing errors are reported on standard error, other mes‐
782 sages after initial startup are sent to the default destination
783 for the tool, i.e. standard error for ASCII tools, or a dialog
784 for GUI tools.
785 If PCP_STDERR is set to the literal value DISPLAY then all mes‐
787 sages will be displayed in a dialog. This is used for any tools
788 launched from a Desktop environment.
789 If PCP_STDERR is set to any other value, the value is assumed to
791 be a filename, and all messages will be written there.
792 PMCD_CONNECT_TIMEOUT
794 When attempting to connect to a remote pmcd(1) on a machine that
795 is booting, the connection attempt could potentially block for a
796 long time until the remote machine finishes its initialization.
797 Most PCP applications and some of the PCP library routines will
798 abort and return an error if the connection has not been estab‐
799 lished after some specified interval has elapsed. The default
800 interval is 5 seconds. This may be modified by setting
801 PMCD_CONNECT_TIMEOUT in the environment to a real number of sec‐
802 onds for the desired timeout. This is most useful in cases
803 where the remote host is at the end of a slow network, requiring
804 longer latencies to establish the connection correctly.
805 PMCD_RECONNECT_TIMEOUT
807 When a monitor or client application loses a connection to a
808 pmcd(1), the connection may be re-established by calling a ser‐
809 vice routine in the PCP library. However, attempts to reconnect
810 are controlled by a back-off strategy to avoid flooding the net‐
811 work with reconnection requests. By default, the back-off de‐
812 lays are 5, 10, 20, 40 and 80 seconds for consecutive reconnec‐
813 tion requests from a client (the last delay will be repeated for
814 any further attempts after the fifth). Setting the environment
815 variable PMCD_RECONNECT_TIMEOUT to a comma separated list of
816 positive integers will re-define the back-off delays, for exam‐
817 ple setting PMCD_RECONNECT_TIMEOUT to ``1,2'' will back-off for
818 1 second, then attempt another connection request every 2 sec‐
819 onds thereafter.
820 PMCD_REQUEST_TIMEOUT
822 For monitor or client applications connected to pmcd(1), there
823 is a possibility of the application "hanging" on a request for
824 performance metrics or metadata or help text. These delays may
825 become severe if the system running pmcd crashes, or the network
826 connection is lost. By setting the environment variable
827 PMCD_REQUEST_TIMEOUT to a number of seconds, requests to pmcd
828 will timeout after this number of seconds. The default behavior
829 is to be willing to wait 10 seconds for a response from every
830 pmcd for all applications.
831 PMCD_WAIT_TIMEOUT
833 When pmcd(1) is started from $PCP_RC_DIR/pcp then the primary
834 instance of pmlogger(1) will be started if the configuration
835 flag pmlogger is chkconfig(8) or systemctl(1) enabled and pmcd
836 is running and accepting connections.
837 The check on pmcd's readiness will wait up to PMCD_WAIT_TIMEOUT
839 seconds. If pmcd has a long startup time (such as on a very
840 large system), then PMCD_WAIT_TIMEOUT can be set to provide a
841 maximum wait longer than the default 60 seconds.
842 PMNS_DEFAULT
844 If set, then interpreted as the full pathname to be used as the
845 default local PMNS for pmLoadNameSpace(3). Otherwise, the de‐
846 fault local PMNS is located at $PCP_VAR_DIR/pcp/pmns/root for
847 base PCP installations.
848 PCP_COUNTER_WRAP
850 Many of the performance metrics exported from PCP agents have
851 the semantics of counter meaning they are expected to be mono‐
852 tonically increasing. Under some circumstances, one value of
853 these metrics may smaller than the previously fetched value.
854 This can happen when a counter of finite precision overflows, or
855 when the PCP agent has been reset or restarted, or when the PCP
856 agent is exporting values from some underlying instrumentation
857 that is subject to some asynchronous discontinuity.
858 The environment variable PCP_COUNTER_WRAP may be set to indicate
860 that all such cases of a decreasing ``counter'' should be
861 treated as a counter overflow, and hence the values are assumed
862 to have wrapped once in the interval between consecutive sam‐
863 ples. This ``wrapping'' behavior was the default in earlier PCP
864 versions, but by default has been disabled in PCP release from
865 version 1.3 on.
866 PMDA_PATH
868 The PMDA_PATH environment variable may be used to modify the
869 search path used by pmcd(1) and pmNewContext(3) (for PM_CON‐
870 TEXT_LOCAL contexts) when searching for a daemon or DSO PMDA.
871 The syntax follows that for PATH in sh(1), i.e. a colon sepa‐
872 rated list of directories, and the default search path is
873 ``/var/pcp/lib:/usr/pcp/lib'', (or ``/var/lib/pcp/lib'' on
874 Linux, depending on the value of the $PCP_VAR_DIR environment
875 variable).
876 PMCD_PORT
878 The TCP/IP port(s) used by pmcd(1) to create the socket for in‐
879 coming connections and requests, was historically 4321 and more
880 recently the officially registered port 44321; in the current
881 release, both port numbers are used by default as a transitional
882 arrangement. This may be over-ridden by setting PMCD_PORT to a
883 different port number, or a comma-separated list of port num‐
884 bers. If a non-default port is used when pmcd is started, then
885 every monitoring application connecting to that pmcd must also
886 have PMCD_PORT set in their environment before attempting a con‐
887 nection.
888 The following environment variables are relevant to installations in
890 which pmlogger(1), the PCP archive logger, is used.
891 PMLOGGER_PORT
893 The environment variable PMLOGGER_PORT may be used to change the
894 base TCP/IP port number used by pmlogger(1) to create the socket
895 to which pmlc(1) instances will try and connect. The default
896 base port number is 4330. When used, PMLOGGER_PORT should be
897 set in the environment before pmlogger is executed.
898 PMLOGGER_REQUEST_TIMEOUT
900 When pmlc(1) connects to pmlogger(1), there is a remote possi‐
901 bility of pmlc "hanging" on a request for information as a con‐
902 sequence of a failure of the network or pmlogger. By setting
903 the environment variable PMLOGGER_REQUEST_TIMEOUT to a number of
904 seconds, requests to pmlogger will timeout after this number of
905 seconds. The default behavior is to be willing to wait forever
906 for a response from each request to a pmlogger. When used, PM‐
907 LOGGER_REQUEST_TIMEOUT should be set in the environment before
908 pmlc is executed.
909 If you have the PCP product installed, then the following environment
911 variables are relevant to the Performance Metrics Domain Agents (PM‐
912 DAs).
913 PMDA_LOCAL_PROC
915 Use this variable has been deprecated and it is now ignored. If
916 the ``proc'' PMDA is configured as a DSO for use with pmcd(1) on
917 the local host then all of the ``proc'' metrics will be avail‐
918 able to applications using a PM_CONTEXT_LOCAL context.
919 The previous behaviour was that if this variable was set, then a
921 context established with the type of PM_CONTEXT_LOCAL will have
922 access to the ``proc'' PMDA to retrieve performance metrics
923 about individual processes.
924 PMDA_LOCAL_SAMPLE
926 Use this variable has been deprecated and it is now ignored. If
927 the ``sample'' PMDA is configured as a DSO for use with pmcd(1)
928 on the local host then all of the ``sample'' metrics will be
929 available to applications using a PM_CONTEXT_LOCAL context.
930 The previous behaviour was that if this variable was set, then a
932 context established with the type of PM_CONTEXT_LOCAL will have
933 access to the ``sample'' PMDA if this optional PMDA has been in‐
934 stalled locally.
935 PMIECONF_PATH
937 If set, pmieconf(1) will form its pmieconf(5) specification (set
938 of parameterized pmie(1) rules) using all valid pmieconf files
939 found below each subdirectory in this colon-separated list of
940 subdirectories. If not set, the default is $PCP_VAR_DIR/con‐
941 fig/pmieconf.
942
944 Environment variables with the prefix PCP_ are used to parameterize the
945 file and directory names used by PCP. On each installation, the file
946 /etc/pcp.conf contains the local values for these variables. The
947 $PCP_CONF variable may be used to specify an alternative configuration
948 file, as described in pcp.conf(5).
949 For environment variables affecting PCP tools, see pmGetOptions(3).
951
953 pcp(1), pmcd(1), pmie(1), pmie_daily(1), pminfo(1), pmlc(1), pmlog‐
954 ger(1), pmlogger_daily(1), pmrep(1), pmstat(1), pmval(1), systemctl(1),
955 LOGIMPORT(3), LOGARCHIVE(5), pcp.conf(5), pcp.env(5), PMNS(5) and chk‐
956 config(8).
957 If the PCP GUI package is installed, then the following entries are
959 also relevant:
960 pmchart(1), pmtime(1), and pmdumptext(1).
961 If the secure sockets extensions have been enabled, then the following
963 references are also relevant:
964 https://pcp.io/documentation.html
965 http://www.mozilla.org/projects/security/pki/nss/#documentation
966 http://www.mozilla.org/projects/security/pki/nss/tools/certutil.html
967 Also refer to the books Performance Co-Pilot User's and Administrator's
969 Guide and Performance Co-Pilot Programmer's Guide which can be found at
970 https://pcp.io/.
971Performance Co-Pilot PCP PCPINTRO(1)