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
27 release, 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.
38 requires 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-
67 default 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
89 replay 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
125 instance 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
141 detailed description of the default local host connection. The
142 -a (or --archive), and -h (or --host) options are mutually
143 exclusive.
144 -s samples, --samples=samples
146 The argument samples defines the number of samples to be
147 retrieved 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
162 environ(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.
168 debugspec 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 absense 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
241 (interval is the same as for the -t or --interval option as
242 described 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
281 example -T 2h30m will set the end of the time window to
282 be 2 hours and 30 minutes after the start of the time
283 window.
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
305 replay 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
349 interpretations 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
387 example 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
404 installed 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
409 descriptor (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
413 implementing performance metric domain. For example, one value for
414 each disk, one value for each process, one value for each CPU, or one
415 value for each activation of a given application. When a metric has
416 multiple instances, the PMNS does not represent this in metric names;
417 rather, a single metric may have an associated set of values. Multiple
418 values are associated with the members of an instance domain, such that
419 each instance has a unique instance identifier within the associated
420 instance 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.
430 PCP arranges for information describing instance domains to be exported
432 from the performance metric domains to the applications that require
433 this information. Applications may also choose to retrieve values for
434 all instances of a performance metric, or some arbitrary subset of the
435 available instances.
436 Metric names and the instance domain concept provides two-dimensions
438 for the modelling of performance metrics. This is a clear and simple
439 model, however on some occassions it does not suffice. For example, a
440 metric may wish to represent higher dimensional data such as ``per
441 CPU'' counters for each running process. In these cases it is common
442 to create a compound instance, where the name is composed of each com‐
443 ponent with a separator in-between (for example, ``87245::cpu7'' might
444 be used to separate process ID from CPU ID) to create flattened
445 instance names. Additionally, such cases benefit from the use of met‐
446 ric instances labels to explicitly show the separate components (con‐
447 tinuing the example from above, labels ``{"pid":87245,"cpu":7}'' might
448 be used).
449
451 In configuration files and (to a lesser extent) command line options,
452 metric specifications adhere to the following syntax rules by most
453 tools.
454 If the source of performance metrics is real-time from pmcd(1) then the
456 accepted syntax is
457 host:metric[instance1,instance2,...]
458 If the source of performance metrics is a set of PCP archive logs then
460 the accepted syntax is
461 archive/metric[instance1,instance2,...]
462 The host:, archive/ and [instance1,instance2,...] components are all
464 optional.
465 The , delimiter in the list of instance names may be replaced by white
467 space.
468 Special characters in instance names may be escaped by surrounding the
470 name in double quotes or preceding the character with a backslash.
471 White space is ignored everywhere except within a quoted instance name.
473 An empty instance is silently ignored, and in particular ``[]'' is the
475 same as no instance, while ``[one,,,two]'' is parsed as specifying just
476 the two instances ``one'' and ``two''.
477 As a special case, if the host is the single character ``@'' then this
479 refers to a PM_CONTEXT_LOCAL source, see pmNewContext(3).
480
482 Since PCP version 3.6.11, a monitor can explicitly request a secure
483 connection to a collector host running pmcd(1) or pmproxy(1) using the
484 PM_CTXFLAG_SECURE context flag. If the PCP Collector host supports
485 this feature - refer to the pmcd.feature.secure metric for confirmation
486 of this - a TLS/SSL (Transport Layer Security or Secure Sockets Layer)
487 connection can be established which uses public key cryptography and
488 related techniques. These features aim to prevent eavesdropping and
489 data tampering from a malicious third party, as well as providing
490 server-side authentication (confident identification of a server by a
491 client) which can be used to guard against man-in-the-middle attacks.
492 A secure pmcd connection requires use of certificate-based authentica‐
494 tion. The security features offered by pmcd and pmproxy are imple‐
495 mented using the Network Security Services (NSS) APIs and utilities.
496 The NSS certutil tool can be used to create certificates suitable for
497 establishing trust between PCP monitor and collector hosts.
498 A complete description is beyond the scope of this document, refer to
500 the PCP ENVIRONMENT, FILES and SEE ALSO sections for detailed informa‐
501 tion. This includes links to tutorials on the steps involved in set‐
502 ting up the available security features.
503
505 In the absence of an explicit hostname specification, most tools will
506 default to the local host in live update mode. In PCP releases since
507 3.8.4 onward, this results in an efficient local protocol being
508 selected - typically a Unix domain socket. If this option is used
509 (which can also be explicitly requested via the unix: host specifica‐
510 tion described below), it is important to note that all connections
511 will be automatically authenticated. In other words, the credentials
512 of the user invoking a client tool will automatically be made available
513 to pmcd(1) and all of its PMDAs, on the users behalf, such that results
514 can be customized to the privilege levels of individual users.
515 Names of remote hosts running the pmcd(1) daemon can of course also be
517 provided to request a remote host be used. The most basic form of pmcd
518 host specification is a simple host name, possibly including the domain
519 name if necessary. However, this can be extended in a number of ways
520 to further refine attributes of the connection made to pmcd.
521 The pmcd port number and also optional pmproxy(1) hostname and its port
523 number, can be given as part of the host specification, since PCP ver‐
524 sion 3.0. These supersede (and override) the old-style PMCD_PORT,
525 PMPROXY_HOST and PMPROXY_PORT environment variables.
526 The following are valid hostname specifications that specify connec‐
528 tions to pmcd on host nas1.acme.com with/without a list of ports,
529 with/without a pmproxy(1) connection through a firewall, and with IPv6
530 and IPv4 addresses as shown.
531 $ pcp --host nas1.acme.com:44321,4321@firewall.acme.com:44322
533 $ pcp --host nas1.acme.com:44321@firewall.acme.com:44322
534 $ pcp --host nas1.acme.com:44321@firewall.acme.com
535 $ pcp --host nas1.acme.com@firewall.acme.com
536 $ pcp --host nas1.acme.com:44321
537 $ pcp --host [fe80::2ad2:44ff:fe88:e4f1%p2p1]
538 $ pcp --host 192.168.0.103
539 In addition, ``connection attributes'' can also be specified. These
541 include username, password (can be given interactively and may depend
542 on the authentication mechanism employed), whether to target a specific
543 running container, whether to use secure (encrypted) or native (naked)
544 protocol, and so on. The previous examples all default to native pro‐
545 tocol, and use no authentication. This can be altered, as in the fol‐
546 lowing examples.
547 $ pcp --host pcps://app2.acme.com?container=cae8e6edc0d5
549 $ pcp --host pcps://nas1.acme.com:44321?username=tanya&method=gssapi
550 $ pcp --host pcps://nas2.acme.com@firewalls.r.us?method=plain
551 $ pcp --host pcp://nas3.acme.com
552 $ pcp --host 192.168.0.103?container=cae8e6edc0d5,method=digest-md5
553 $ pcp --host unix:
554 $ pcp --host local:
555 The choice of authentication method, and other resulting parameters
557 like username, optionally password, etc, depends on the SASL2 configu‐
558 ration used by each (remote) pmcd. Tutorials are available specifying
559 various aspects of configuring the authentication module(s) used, these
560 fine details are outside the scope of this document.
561 In all situations, host names can be used interchangeably with IPv4 or
563 IPv6 addressing (directly), as shown above. In the case of an IPv6
564 address, the full address must be enclosed by square brackets and the
565 scope (interface) must also be specified.
566 The final local: example above is now the default for most tools. This
568 connection is an automatically authenticated local host connection on
569 all platforms that support Unix domain sockets. No password is
570 required and authentication is automatic. This is also the most effi‐
571 cient (lowest overhead) communication channel.
572 The difference between unix: and local: is that the former is a strict
574 Unix domain socket specification (connection fails if it cannot connect
575 that way), whereas the latter has a more forgiving fallback to using
576 localhost (i.e. a regular Inet socket connection is used when Unix
577 domain socket connections are unavailable).
578
580 In addition to the PCP run-time environment and configuration variables
581 described in the PCP ENVIRONMENT section below, the following environ‐
582 ment variables apply to all installations.
583 Note that most uses of these environment variables are optimized to
585 check the environment only the first time the variable might be used.
586 As the environment usually is not checked again, the only safe strategy
587 is to ensure all PCP-related environment variables are set before the
588 first call into any of the PCP libraries.
589 PCP_ALLOW_BAD_CERT_DOMAIN
591 When set, allow clients to accept certificates with mismatched
592 domain names with no prompt when they are sent by pmcd or other
593 server components. See PCP_SECURE_SOCKETS.
594 PCP_ALLOW_SERVER_SELF_CERT
596 When set, allow clients to accept self-signed certificates with
597 no prompt when they are sent by pmcd or other server components.
598 See PCP_SECURE_SOCKETS.
599 PCP_CONSOLE
601 When set, this changes the default console from /dev/tty (on
602 Unix) or CON: (on Windows) to be the specified console. The
603 special value of none can be used to indicate no console is
604 available for use. This is used in places where console-based
605 tools need to interact with the user, and in particular is used
606 when authentication is being performed.
607 PCP_DEBUG
609 When set, this variable provides an alternate to the -D command
610 line option described above to initialize the diagnostic and
611 debug options. The value for $PCP_DEBUG is the same as for the
612 -D command line option, namely a comma-separated list of debug‐
613 ging option name(s), and/or decimal integers, see pmdbg(1) for a
614 description of the supported option names and values.
615 PCP_DERIVED_CONFIG
617 When set, this variable defines a colon separated list of files
618 and/or directories (the syntax is the same as for the $PATH
619 variable for sh(1)). The components are expanded into a list of
620 files as follows: if a component of $PCP_DERIVED_CONFIG is a
621 file, then that file is added to the list, else if a component
622 is a directory then recursive descent is used to enumerate all
623 files below that directory and these are added to the list.
624 Each file in the resulting list is assumed to contain defini‐
626 tions of derived metrics as per the syntax described in pmLoad‐
627 DerivedConfig(3), and these are loaded in order.
628 Derived metrics may be used to extend the available metrics with
630 new (derived) metrics using simple arithmetic expressions.
631 If PCP_DERIVED_CONFIG is set, the derived metric definitions are
633 processed automatically as each new source of performance met‐
634 rics is established (i.e. each time a pmNewContext(3) is called)
635 or when requests are made against the PMNS.
636 Any component in the $PCP_DERIVED_CONFIG list or the expanded
638 list of files that is not a file, or is not a directory or is
639 not accessible (due to permissions or a bad symbolic link) will
640 be silently ignored.
641 PCP_IGNORE_MARK_RECORDS
643 When PCP archives logs are created there may be temporal gaps
644 associated with discontinuities in the time series of logged
645 data, for example when pmcd(1) is restarted or when multiple ar‐
646 chive logs are concatenated with pmlogextract(1). These discon‐
647 tinuities are internally noted with a <mark> record in the PCP
648 archive logs, and value interpolation as described in pmSet‐
649 Mode(3) is not supported across <mark> records (because the val‐
650 ues before and after a <mark> record are not necessarily from a
651 continuous time series). Sometimes the user knows the data
652 semantics are sound in the region of the <mark> records, and
653 $PCP_IGNORE_MARK_RECORDS may be used to suppress the default be‐
654 haviour.
655 If PCP_IGNORE_MARK_RECORDS is set (but has no value) then all
657 <mark> records will be ignored. Otherwise the value
658 $PCP_IGNORE_MARK_RECORDS follows the syntax for an interval
659 argument described above for the -t option, and <mark> records
660 will be ignored if the time gap between the last record before
661 the <mark> and the first record after the <mark> is not more
662 than interval.
663 PCP_SECURE_SOCKETS
665 When set, this variable forces any monitor tool connections to
666 be established using the certificate-based secure sockets fea‐
667 ture. If the connections cannot be established securely, they
668 will fail.
669 PCP_SECURE_DB_METHOD
671 With secure socket connections, the certificate and key database
672 is stored using the sql: method by default. Use
673 PCP_SECURE_DB_METHOD to override the default, most usually set‐
674 ting the value to the empty string (for the older database meth‐
675 ods).
676 PCP_SECURE_DB_PATH
678 When set, this variable specifies an alternate certficate data‐
679 base path for client tools. Similar to the action of the -C
680 option for pmcd(1) and pmproxy(1).
681 PCP_STDERR
683 Many PCP tools support the environment variable PCP_STDERR,
684 which can be used to control where error messages are sent.
685 When unset, the default behavior is that ``usage'' messages and
686 option parsing errors are reported on standard error, other mes‐
687 sages after initial startup are sent to the default destination
688 for the tool, i.e. standard error for ASCII tools, or a dialog
689 for GUI tools.
690 If PCP_STDERR is set to the literal value DISPLAY then all mes‐
692 sages will be displayed in a dialog. This is used for any tools
693 launched from the a Desktop environment.
694 If PCP_STDERR is set to any other value, the value is assumed to
696 be a filename, and all messages will be written there.
697 PMCD_CONNECT_TIMEOUT
699 When attempting to connect to a remote pmcd(1) on a machine that
700 is booting, the connection attempt could potentially block for a
701 long time until the remote machine finishes its initialization.
702 Most PCP applications and some of the PCP library routines will
703 abort and return an error if the connection has not been estab‐
704 lished after some specified interval has elapsed. The default
705 interval is 5 seconds. This may be modified by setting
706 PMCD_CONNECT_TIMEOUT in the environment to a real number of sec‐
707 onds for the desired timeout. This is most useful in cases
708 where the remote host is at the end of a slow network, requiring
709 longer latencies to establish the connection correctly.
710 PMCD_RECONNECT_TIMEOUT
712 When a monitor or client application loses a connection to a
713 pmcd(1), the connection may be re-established by calling a ser‐
714 vice routine in the PCP library. However, attempts to reconnect
715 are controlled by a back-off strategy to avoid flooding the net‐
716 work with reconnection requests. By default, the back-off
717 delays are 5, 10, 20, 40 and 80 seconds for consecutive recon‐
718 nection requests from a client (the last delay will be repeated
719 for any further attempts after the fifth). Setting the environ‐
720 ment variable PMCD_RECONNECT_TIMEOUT to a comma separated list
721 of positive integers will re-define the back-off delays, for
722 example setting PMCD_RECONNECT_TIMEOUT to ``1,2'' will back-off
723 for 1 second, then attempt another connection request every 2
724 seconds thereafter.
725 PMCD_REQUEST_TIMEOUT
727 For monitor or client applications connected to pmcd(1), there
728 is a possibility of the application "hanging" on a request for
729 performance metrics or metadata or help text. These delays may
730 become severe if the system running pmcd crashes, or the network
731 connection is lost. By setting the environment variable
732 PMCD_REQUEST_TIMEOUT to a number of seconds, requests to pmcd
733 will timeout after this number of seconds. The default behavior
734 is to be willing to wait 10 seconds for a response from every
735 pmcd for all applications.
736 PMCD_WAIT_TIMEOUT
738 When pmcd(1) is started from $PCP_RC_DIR/pcp then the primary
739 instance of pmlogger(1) will be started if the configuration
740 flag pmlogger is chkconfig(8) or systemctl(1) enabled and pmcd
741 is running and accepting connections.
742 The check on pmcd's readiness will wait up to PMCD_WAIT_TIMEOUT
744 seconds. If pmcd has a long startup time (such as on a very
745 large system), then PMCD_WAIT_TIMEOUT can be set to provide a
746 maximum wait longer than the default 60 seconds.
747 PMNS_DEFAULT
749 If set, then interpreted as the full pathname to be used as the
750 default local PMNS for pmLoadNameSpace(3). Otherwise, the
751 default local PMNS is located at $PCP_VAR_DIR/pcp/pmns/root for
752 base PCP installations.
753 PCP_COUNTER_WRAP
755 Many of the performance metrics exported from PCP agents have
756 the semantics of counter meaning they are expected to be mono‐
757 tonically increasing. Under some circumstances, one value of
758 these metrics may smaller than the previously fetched value.
759 This can happen when a counter of finite precision overflows, or
760 when the PCP agent has been reset or restarted, or when the PCP
761 agent is exporting values from some underlying instrumentation
762 that is subject to some asynchronous discontinuity.
763 The environment variable PCP_COUNTER_WRAP may be set to indicate
765 that all such cases of a decreasing ``counter'' should be
766 treated as a counter overflow, and hence the values are assumed
767 to have wrapped once in the interval between consecutive sam‐
768 ples. This ``wrapping'' behavior was the default in earlier PCP
769 versions, but by default has been disabled in PCP release from
770 version 1.3 on.
771 PMDA_PATH
773 The PMDA_PATH environment variable may be used to modify the
774 search path used by pmcd(1) and pmNewContext(3) (for PM_CON‐
775 TEXT_LOCAL contexts) when searching for a daemon or DSO PMDA.
776 The syntax follows that for PATH in sh(1), i.e. a colon sepa‐
777 rated list of directories, and the default search path is
778 ``/var/pcp/lib:/usr/pcp/lib'', (or ``/var/lib/pcp/lib'' on
779 Linux, depending on the value of the $PCP_VAR_DIR environment
780 variable).
781 PMCD_PORT
783 The TPC/IP port(s) used by pmcd(1) to create the socket for
784 incoming connections and requests, was historically 4321 and
785 more recently the officially registered port 44321; in the cur‐
786 rent release, both port numbers are used by default as a transi‐
787 tional arrangement. This may be over-ridden by setting
788 PMCD_PORT to a different port number, or a comma-separated list
789 of port numbers. If a non-default port is used when pmcd is
790 started, then every monitoring application connecting to that
791 pmcd must also have PMCD_PORT set in their environment before
792 attempting a connection.
793 The following environment variables are relevant to installations in
795 which pmlogger(1), the PCP archive logger, is used.
796 PMLOGGER_PORT
798 The environment variable PMLOGGER_PORT may be used to change the
799 base TCP/IP port number used by pmlogger(1) to create the socket
800 to which pmlc(1) instances will try and connect. The default
801 base port number is 4330. When used, PMLOGGER_PORT should be
802 set in the environment before pmlogger is executed.
803 PMLOGGER_REQUEST_TIMEOUT
805 When pmlc(1) connects to pmlogger(1), there is a remote possi‐
806 bility of pmlc "hanging" on a request for information as a con‐
807 sequence of a failure of the network or pmlogger. By setting
808 the environment variable PMLOGGER_REQUEST_TIMEOUT to a number of
809 seconds, requests to pmlogger will timeout after this number of
810 seconds. The default behavior is to be willing to wait forever
811 for a response from each request to a pmlogger. When used,
812 PMLOGGER_REQUEST_TIMEOUT should be set in the environment before
813 pmlc is executed.
814 If you have the PCP product installed, then the following environment
816 variables are relevant to the Performance Metrics Domain Agents
817 (PMDAs).
818 PMDA_LOCAL_PROC
820 Use this variable has been deprecated and it is now ignored. If
821 the ``proc'' PMDA is configured as a DSO for use with pmcd(1) on
822 the local host then all of the ``proc'' metrics will be avail‐
823 able to applications using a PM_CONTEXT_LOCAL context.
824 The previous behaviour was that if this variable was set, then a
826 context established with the type of PM_CONTEXT_LOCAL will have
827 access to the ``proc'' PMDA to retrieve performance metrics
828 about individual processes.
829 PMDA_LOCAL_SAMPLE
831 Use this variable has been deprecated and it is now ignored. If
832 the ``sample'' PMDA is configured as a DSO for use with pmcd(1)
833 on the local host then all of the ``sample'' metrics will be
834 available to applications using a PM_CONTEXT_LOCAL context.
835 The previous behaviour was that if this variable was set, then a
837 context established with the type of PM_CONTEXT_LOCAL will have
838 access to the ``sample'' PMDA if this optional PMDA has been
839 installed locally.
840 PMIECONF_PATH
842 If set, pmieconf(1) will form its pmieconf(5) specification (set
843 of parameterized pmie(1) rules) using all valid pmieconf files
844 found below each subdirectory in this colon-separated list of
845 subdirectories. If not set, the default is $PCP_VAR_DIR/con‐
846 fig/pmieconf.
847
849 /etc/pcp.conf
850 Configuration file for the PCP runtime environment, see
851 pcp.conf(5).
852 /etc/pki/nssdb
853 Optionally contains a Network Security Services database with
854 a "PCP Collector" certificate providing trusted identifica‐
855 tion for the collector host.
856 $HOME/.pcp
857 User-specific directories containing configuration files for
858 customisation of the various monitor tools, such as
859 pmchart(1).
860 $HOME/.pki/nssdb
861 A shared Network Security Services (NSS) database directory
862 containing per-user certificates identifying known valid
863 remote pmcd collector hosts. The NSS certutil tool is one of
864 several that can be used to maintain this database.
865 $PCP_RC_DIR/pcp
866 Script for starting and stopping pmcd(1).
867 $PCP_PMCDCONF_PATH
868 Control file for pmcd(1).
869 $PCP_PMCDOPTIONS_PATH
870 Command line options passed to pmcd(1) when it is started
871 from $PCP_RC_DIR/pcp. All the command line option lines
872 should start with a hyphen as the first character. This file
873 can also contain environment variable settings of the form
874 "VARIABLE=value".
875 $PCP_BINADM_DIR
876 Location of PCP utilities for collecting and maintaining PCP
877 archives, PMDA help text, PMNS files etc.
878 $PCP_PMDAS_DIR
879 Parent directory of the installation directory for Dynamic
880 Shared Object (DSO) PMDAs.
881 $PCP_RUN_DIR/pmcd.pid
882 If pmcd is running, this file contains an ascii decimal rep‐
883 resentation of its process ID.
884 $PCP_LOG_DIR/pmcd
885 Default location of log files for pmcd(1), current directory
886 for running PMDAs. Archives generated by pmlogger(1) are
887 generally below $PCP_LOG_DIR/pmlogger.
888 $PCP_LOG_DIR/pmcd/pmcd.log
889 Diagnostic and status log for the current running pmcd(1)
890 process. The first place to look when there are problems
891 associated with pmcd.
892 $PCP_LOG_DIR/pmcd/pmcd.log.prev
893 Diagnostic and status log for the previous pmcd(1) instance.
894 $PCP_LOG_DIR/NOTICES
895 Log of pmcd(1) and PMDA starts, stops, additions and
896 removals.
897 $PCP_VAR_DIR/config
898 Contains directories of configuration files for several PCP
899 tools.
900 $PCP_SYSCONF_DIR/pmcd/rc.local
901 Local script for controlling PCP boot, shutdown and restart
902 actions.
903 $PCP_VAR_DIR/pmns
904 Directory containing the set of PMNS files for all installed
905 PMDAs.
906 $PCP_VAR_DIR/pmns/root
907 The ASCII PMNS(5) exported by pmcd(1) by default. This PMNS
908 is be the super set of all other PMNS files installed in
909 $PCP_VAR_DIR/pmns.
910 In addition, if the PCP product is installed the following files and
911 directories are relevant.
912 $PCP_LOG_DIR/NOTICES
913 In addition to the pmcd(1) and PMDA activity, may be used to log
914 alarms and notices from pmie(1) via pmpost(1).
915 $PCP_PMLOGGERCONTROL_PATH
916 Control file for pmlogger(1) instances launched from
917 $PCP_RC_DIR/pcp and/or managed by pmlogger_check(1) and pmlog‐
918 ger_daily(1) as part of a production PCP archive collection set‐
919 up.
920
922 Environment variables with the prefix PCP_ are used to parameterize the
923 file and directory names used by PCP. On each installation, the file
924 /etc/pcp.conf contains the local values for these variables. The
925 $PCP_CONF variable may be used to specify an alternative configuration
926 file, as described in pcp.conf(5).
927
929 pcp(1), pmcd(1), pmie(1), pmie_daily(1), pminfo(1), pmlc(1), pmlog‐
930 ger(1), pmlogger_daily(1), pmrep(1), pmstat(1), pmval(1), systemctl(1),
931 LOGIMPORT(3), LOGARCHIVE(5), pcp.conf(5), pcp.env(5), PMNS(5) and chk‐
932 config(8).
933 If the PCP GUI package is installed, then the following entries are
935 also relevant:
936 pmchart(1), pmtime(1), and pmdumptext(1).
937 If the secure sockets extensions have been enabled, then the following
939 references are also relevant:
940 https://pcp.io/documentation.html
941 http://www.mozilla.org/projects/security/pki/nss/#documentation
942 http://www.mozilla.org/projects/security/pki/nss/tools/certutil.html
943 Also refer to the books Performance Co-Pilot User's and Administrator's
945 Guide and Performance Co-Pilot Programmer's Guide which can be found at
946 https://pcp.io/
947Performance Co-Pilot PCP PCPINTRO(1)