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 OpenSSL APIs and utilities. The openssl(1) tool can
498 be used to create certificates suitable for establishing trust between
499 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/pcp/tls.conf
587 Optionally contains OpenSSL configuration information, including
588 locations of certificates providing trusted identification for
589 collector and monitor hosts.
590 $HOME/.pcp
592 User-specific directories containing configuration files for cus‐
593 tomisation of the various monitor tools, such as pmchart(1).
594 $PCP_RC_DIR/pcp
596 Script for starting and stopping pmcd(1).
597 $PCP_PMCDCONF_PATH
599 Control file for pmcd(1).
600 $PCP_PMCDOPTIONS_PATH
602 Command line options passed to pmcd(1) when it is started from
603 $PCP_RC_DIR/pcp. All the command line option lines should start
604 with a hyphen as the first character. This file can also contain
605 environment variable settings of the form "VARIABLE=value".
606 $PCP_BINADM_DIR
608 Location of PCP utilities for collecting and maintaining PCP ar‐
609 chives, PMDA help text, PMNS files etc.
610 $PCP_PMDAS_DIR
612 Parent directory of the installation directory for Dynamic Shared
613 Object (DSO) PMDAs.
614 $PCP_RUN_DIR/pmcd.pid
616 If pmcd is running, this file contains an ascii decimal represen‐
617 tation of its process ID.
618 $PCP_LOG_DIR/pmcd
620 Default location of log files for pmcd(1), current directory for
621 running PMDAs. Archives generated by pmlogger(1) are generally
622 below $PCP_LOG_DIR/pmlogger.
623 $PCP_LOG_DIR/pmcd/pmcd.log
625 Diagnostic and status log for the current running pmcd(1) process.
626 The first place to look when there are problems associated with
627 pmcd.
628 $PCP_LOG_DIR/pmcd/pmcd.log.prev
630 Diagnostic and status log for the previous pmcd(1) instance.
631 $PCP_LOG_DIR/NOTICES
633 Log of pmcd(1) and PMDA starts, stops, additions and removals.
634 $PCP_VAR_DIR/config
636 Contains directories of configuration files for several PCP tools.
637 $PCP_SYSCONF_DIR/pmcd/rc.local
639 Local script for controlling PCP boot, shutdown and restart ac‐
640 tions.
641 $PCP_VAR_DIR/pmns
643 Directory containing the set of PMNS files for all installed PM‐
644 DAs.
645 $PCP_VAR_DIR/pmns/root
647 The ASCII PMNS(5) exported by pmcd(1) by default. This PMNS is be
648 the super set of all other PMNS files installed in
649 $PCP_VAR_DIR/pmns.
650 In addition, if the PCP product is installed the following files and
652 directories are relevant.
653 $PCP_LOG_DIR/NOTICES
655 In addition to the pmcd(1) and PMDA activity, may be used to log
656 alarms and notices from pmie(1) via pmpost(1).
657 $PCP_PMLOGGERCONTROL_PATH
659 Control file for pmlogger(1) instances launched from
660 $PCP_RC_DIR/pcp and/or managed by pmlogger_check(1) and pmlog‐
661 ger_daily(1) as part of a production PCP archive collection
662 setup.
663
665 In addition to the PCP run-time environment and configuration variables
666 described in the PCP ENVIRONMENT section below, the following environ‐
667 ment variables apply to all installations.
668 Note that most uses of these environment variables are optimized to
670 check the environment only the first time the variable might be used.
671 As the environment usually is not checked again, the only safe strategy
672 is to ensure all PCP-related environment variables are set before the
673 first call into any of the PCP libraries.
674 PCP_ALLOW_BAD_CERT_DOMAIN
676 When set, allow clients to accept certificates with mismatched
677 domain names with no prompt when they are sent by pmcd or other
678 server components. See PCP_SECURE_SOCKETS.
679 PCP_ALLOW_SERVER_SELF_CERT
681 When set, allow clients to accept self-signed certificates with
682 no prompt when they are sent by pmcd or other server components.
683 See PCP_SECURE_SOCKETS.
684 PCP_CONSOLE
686 When set, this changes the default console from /dev/tty (on
687 Unix) or CON: (on Windows) to be the specified console. The
688 special value of none can be used to indicate no console is
689 available for use. This is used in places where console-based
690 tools need to interact with the user, and in particular is used
691 when authentication is being performed.
692 PCP_DEBUG
694 When set, this variable provides an alternate to the -D command
695 line option described above to initialize the diagnostic and de‐
696 bug options. The value for $PCP_DEBUG is the same as for the -D
697 command line option, namely a comma-separated list of debugging
698 option name(s), and/or decimal integers, see pmdbg(1) for a de‐
699 scription of the supported option names and values.
700 PCP_DERIVED_CONFIG
702 When set, this variable defines a colon separated list of files
703 and/or directories (the syntax is the same as for the $PATH
704 variable for sh(1)). The components are expanded into a list of
705 files as follows: if a component of $PCP_DERIVED_CONFIG is a
706 file, then that file is added to the list, else if a component
707 is a directory then recursive descent is used to enumerate all
708 files below that directory and these are added to the list.
709 Each file in the resulting list is assumed to contain defini‐
711 tions of derived metrics as per the syntax described in pmLoad‐
712 DerivedConfig(3), and these are loaded in order.
713 Derived metrics may be used to extend the available metrics with
715 new (derived) metrics using simple arithmetic expressions.
716 If PCP_DERIVED_CONFIG is set, the derived metric definitions are
718 processed automatically as each new source of performance met‐
719 rics is established (i.e. each time a pmNewContext(3) is called)
720 or when requests are made against the PMNS.
721 Any component in the $PCP_DERIVED_CONFIG list or the expanded
723 list of files that is not a file, or is not a directory or is
724 not accessible (due to permissions or a bad symbolic link) will
725 be silently ignored.
726 PCP_IGNORE_MARK_RECORDS
728 When PCP archives logs are created there may be temporal gaps
729 associated with discontinuities in the time series of logged
730 data, for example when pmcd(1) is restarted or when multiple ar‐
731 chive logs are concatenated with pmlogextract(1). These discon‐
732 tinuities are internally noted with a <mark> record in the PCP
733 archive logs, and value interpolation as described in pmSet‐
734 Mode(3) is not supported across <mark> records (because the val‐
735 ues before and after a <mark> record are not necessarily from a
736 continuous time series). Sometimes the user knows the data se‐
737 mantics are sound in the region of the <mark> records, and
738 $PCP_IGNORE_MARK_RECORDS may be used to suppress the default be‐
739 haviour.
740 If PCP_IGNORE_MARK_RECORDS is set (but has no value) then all
742 <mark> records will be ignored. Otherwise the value $PCP_IG‐
743 NORE_MARK_RECORDS follows the syntax for an interval argument
744 described above for the -t option, and <mark> records will be
745 ignored if the time gap between the last record before the
746 <mark> and the first record after the <mark> is not more than
747 interval.
748 PCP_SECURE_SOCKETS
750 When set, this variable forces any monitor tool connections to
751 be established using the certificate-based secure sockets fea‐
752 ture. If the connections cannot be established securely, they
753 will fail.
754 PCP_TLSCONF_PATH
756 Specifies the location from which TLS (Transport Layer Security)
757 configuration settings will be read. These settings are used by
758 PCP client tools, pmcd and pmproxy whenever secure (encrypted)
759 communication is requested.
760 PCP_STDERR
762 Many PCP tools support the environment variable PCP_STDERR,
763 which can be used to control where error messages are sent.
764 When unset, the default behavior is that ``usage'' messages and
765 option parsing errors are reported on standard error, other mes‐
766 sages after initial startup are sent to the default destination
767 for the tool, i.e. standard error for ASCII tools, or a dialog
768 for GUI tools.
769 If PCP_STDERR is set to the literal value DISPLAY then all mes‐
771 sages will be displayed in a dialog. This is used for any tools
772 launched from a Desktop environment.
773 If PCP_STDERR is set to any other value, the value is assumed to
775 be a filename, and all messages will be written there.
776 PMCD_CONNECT_TIMEOUT
778 When attempting to connect to a remote pmcd(1) on a machine that
779 is booting, the connection attempt could potentially block for a
780 long time until the remote machine finishes its initialization.
781 Most PCP applications and some of the PCP library routines will
782 abort and return an error if the connection has not been estab‐
783 lished after some specified interval has elapsed. The default
784 interval is 5 seconds. This may be modified by setting
785 PMCD_CONNECT_TIMEOUT in the environment to a real number of sec‐
786 onds for the desired timeout. This is most useful in cases
787 where the remote host is at the end of a slow network, requiring
788 longer latencies to establish the connection correctly.
789 PMCD_RECONNECT_TIMEOUT
791 When a monitor or client application loses a connection to a
792 pmcd(1), the connection may be re-established by calling a ser‐
793 vice routine in the PCP library. However, attempts to reconnect
794 are controlled by a back-off strategy to avoid flooding the net‐
795 work with reconnection requests. By default, the back-off de‐
796 lays are 5, 10, 20, 40 and 80 seconds for consecutive reconnec‐
797 tion requests from a client (the last delay will be repeated for
798 any further attempts after the fifth). Setting the environment
799 variable PMCD_RECONNECT_TIMEOUT to a comma separated list of
800 positive integers will re-define the back-off delays, for exam‐
801 ple setting PMCD_RECONNECT_TIMEOUT to ``1,2'' will back-off for
802 1 second, then attempt another connection request every 2 sec‐
803 onds thereafter.
804 PMCD_REQUEST_TIMEOUT
806 For monitor or client applications connected to pmcd(1), there
807 is a possibility of the application "hanging" on a request for
808 performance metrics or metadata or help text. These delays may
809 become severe if the system running pmcd crashes, or the network
810 connection is lost. By setting the environment variable
811 PMCD_REQUEST_TIMEOUT to a number of seconds, requests to pmcd
812 will timeout after this number of seconds. The default behavior
813 is to be willing to wait 10 seconds for a response from every
814 pmcd for all applications.
815 PMCD_WAIT_TIMEOUT
817 When pmcd(1) is started from $PCP_RC_DIR/pcp then the primary
818 instance of pmlogger(1) will be started if the configuration
819 flag pmlogger is chkconfig(8) or systemctl(1) enabled and pmcd
820 is running and accepting connections.
821 The check on pmcd's readiness will wait up to PMCD_WAIT_TIMEOUT
823 seconds. If pmcd has a long startup time (such as on a very
824 large system), then PMCD_WAIT_TIMEOUT can be set to provide a
825 maximum wait longer than the default 60 seconds.
826 PMNS_DEFAULT
828 If set, then interpreted as the full pathname to be used as the
829 default local PMNS for pmLoadNameSpace(3). Otherwise, the de‐
830 fault local PMNS is located at $PCP_VAR_DIR/pcp/pmns/root for
831 base PCP installations.
832 PCP_COUNTER_WRAP
834 Many of the performance metrics exported from PCP agents have
835 the semantics of counter meaning they are expected to be mono‐
836 tonically increasing. Under some circumstances, one value of
837 these metrics may smaller than the previously fetched value.
838 This can happen when a counter of finite precision overflows, or
839 when the PCP agent has been reset or restarted, or when the PCP
840 agent is exporting values from some underlying instrumentation
841 that is subject to some asynchronous discontinuity.
842 The environment variable PCP_COUNTER_WRAP may be set to indicate
844 that all such cases of a decreasing ``counter'' should be
845 treated as a counter overflow, and hence the values are assumed
846 to have wrapped once in the interval between consecutive sam‐
847 ples. This ``wrapping'' behavior was the default in earlier PCP
848 versions, but by default has been disabled in PCP release from
849 version 1.3 on.
850 PMDA_PATH
852 The PMDA_PATH environment variable may be used to modify the
853 search path used by pmcd(1) and pmNewContext(3) (for PM_CON‐
854 TEXT_LOCAL contexts) when searching for a daemon or DSO PMDA.
855 The syntax follows that for PATH in sh(1), i.e. a colon sepa‐
856 rated list of directories, and the default search path is
857 ``/var/pcp/lib:/usr/pcp/lib'', (or ``/var/lib/pcp/lib'' on
858 Linux, depending on the value of the $PCP_VAR_DIR environment
859 variable).
860 PMCD_PORT
862 The TCP/IP port(s) used by pmcd(1) to create the socket for in‐
863 coming connections and requests, was historically 4321 and more
864 recently the officially registered port 44321; in the current
865 release, both port numbers are used by default as a transitional
866 arrangement. This may be over-ridden by setting PMCD_PORT to a
867 different port number, or a comma-separated list of port num‐
868 bers. If a non-default port is used when pmcd is started, then
869 every monitoring application connecting to that pmcd must also
870 have PMCD_PORT set in their environment before attempting a con‐
871 nection.
872 The following environment variables are relevant to installations in
874 which pmlogger(1), the PCP archive logger, is used.
875 PMLOGGER_PORT
877 The environment variable PMLOGGER_PORT may be used to change the
878 base TCP/IP port number used by pmlogger(1) to create the socket
879 to which pmlc(1) instances will try and connect. The default
880 base port number is 4330. When used, PMLOGGER_PORT should be
881 set in the environment before pmlogger is executed.
882 PMLOGGER_REQUEST_TIMEOUT
884 When pmlc(1) connects to pmlogger(1), there is a remote possi‐
885 bility of pmlc "hanging" on a request for information as a con‐
886 sequence of a failure of the network or pmlogger. By setting
887 the environment variable PMLOGGER_REQUEST_TIMEOUT to a number of
888 seconds, requests to pmlogger will timeout after this number of
889 seconds. The default behavior is to be willing to wait forever
890 for a response from each request to a pmlogger. When used, PM‐
891 LOGGER_REQUEST_TIMEOUT should be set in the environment before
892 pmlc is executed.
893 If you have the PCP product installed, then the following environment
895 variables are relevant to the Performance Metrics Domain Agents (PM‐
896 DAs).
897 PMDA_LOCAL_PROC
899 Use this variable has been deprecated and it is now ignored. If
900 the ``proc'' PMDA is configured as a DSO for use with pmcd(1) on
901 the local host then all of the ``proc'' metrics will be avail‐
902 able to applications using a PM_CONTEXT_LOCAL context.
903 The previous behaviour was that if this variable was set, then a
905 context established with the type of PM_CONTEXT_LOCAL will have
906 access to the ``proc'' PMDA to retrieve performance metrics
907 about individual processes.
908 PMDA_LOCAL_SAMPLE
910 Use this variable has been deprecated and it is now ignored. If
911 the ``sample'' PMDA is configured as a DSO for use with pmcd(1)
912 on the local host then all of the ``sample'' metrics will be
913 available to applications using a PM_CONTEXT_LOCAL context.
914 The previous behaviour was that if this variable was set, then a
916 context established with the type of PM_CONTEXT_LOCAL will have
917 access to the ``sample'' PMDA if this optional PMDA has been in‐
918 stalled locally.
919 PMIECONF_PATH
921 If set, pmieconf(1) will form its pmieconf(5) specification (set
922 of parameterized pmie(1) rules) using all valid pmieconf files
923 found below each subdirectory in this colon-separated list of
924 subdirectories. If not set, the default is $PCP_VAR_DIR/con‐
925 fig/pmieconf.
926
928 Environment variables with the prefix PCP_ are used to parameterize the
929 file and directory names used by PCP. On each installation, the file
930 /etc/pcp.conf contains the local values for these variables. The
931 $PCP_CONF variable may be used to specify an alternative configuration
932 file, as described in pcp.conf(5).
933 For environment variables affecting PCP tools, see pmGetOptions(3).
935
937 pcp(1), pmcd(1), pmie(1), pmie_daily(1), pminfo(1), pmlc(1), pmlog‐
938 ger(1), pmlogger_daily(1), pmrep(1), pmstat(1), pmval(1), systemctl(1),
939 LOGIMPORT(3), LOGARCHIVE(5), pcp.conf(5), pcp.env(5), PMNS(5) and chk‐
940 config(8).
941 If the PCP GUI package is installed, then the following entries are
943 also relevant:
944 pmchart(1), pmtime(1), and pmdumptext(1).
945 If the secure sockets extensions have been enabled, then the following
947 references are also relevant:
948 https://pcp.io/documentation.html
949 https://pcp.readthedocs.io/en/latest/QG/EncryptedConnections.html
950 https://pcp.readthedocs.io/en/latest/QG/AuthenticatedConnections.html
951 Also refer to the books Performance Co-Pilot User's and Administrator's
953 Guide and Performance Co-Pilot Programmer's Guide which can be found at
954 https://pcp.readthedocs.io/en/latest/.
955Performance Co-Pilot PCP PCPINTRO(1)