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, e.g. the operating system kernel.
21 PCP Monitors
23 These are the parts of PCP that display data collected from
24 hosts (or archives) that have the PCP Collector installed.
25 Many monitor tools are available as part of the core PCP
26 release, while other (typically graphical) monitoring tools are
27 available separately in the PCP GUI package.
28 This manual entry describes the high-level features and options common
30 to most PCP utilities available on all platforms.
31
33 The PCP architecture is distributed in the sense that any PCP tool may
34 be executing remotely. On the host (or hosts) being monitored, each
35 domain of performance metrics, whether the kernel, a service layer, a
36 database management system, a web server, an application, etc.
37 requires a Performance Metrics Domain Agent (PMDA) which is responsible
38 for collecting performance measurements from that domain. All PMDAs
39 are controlled by the Performance Metrics Collector Daemon (pmcd(1)) on
40 the same host.
41 Client applications (the monitoring tools) connect to pmcd(1), which
43 acts as a router for requests, by forwarding requests to the appropri‐
44 ate PMDA and returning the responses to the clients. Clients may also
45 access performance data from a PCP archive (created using pmlogger(1))
46 for retrospective analysis.
47 Security philosophy
49 PCP redistributes a wealth of performance information within a host and
50 across its networks. The following security philosophy underlies the
51 setting of several defaults that control how much information is sent
52 and received.
53 By default, the information exposed by PMCD about a host is approxi‐
55 mately of the same level of confidentiality as available to a com‐
56 pletely unprivileged user on that host. So, performance data that is
57 available to be read completely freely on a machine may be made avail‐
58 able by PMCD to the network.
59 However, the host running PMCD and its network is not assumed to run
61 only friendly applications. Therefore, write type operations, includ‐
62 ing from the local host, are not permitted by default.
63 These defaults may be overridden (expanded or reduced) in several ways,
65 including by specifying network ACLs in pmcd.conf, activating non-
66 default PMDAs, or by using PMCD connections that pass user credentials.
67 For example, some PMDAs automatically provide greater information for
68 particular credentialed users or groups.
69 Applications
71 The following performance monitoring applications are primarily console
72 based, typically run directly from the command line, and are just a
73 small subset of the tools available as part of the base PCP package.
74 Each tool or command is documented completely in its own reference
76 page.
77 pmstat Outputs an ASCII high-level summary of system performance.
79 pmie An inference engine that can evaluate predicate-action rules to
81 perform alarms and automate system management tasks.
82 pminfo Interrogate specific performance metrics and the metadata that
84 describes them.
85 pmlogger
87 Generates PCP archives of performance metrics suitable for
88 replay by most PCP tools.
89 pmrep Highly customizable performance metrics reporter with support
91 for various different output modes.
92 pmval Simple periodic reporting for some or all instances of a perfor‐
94 mance metric, with optional VCR time control.
95 If the PCP GUI package is installed then the following additional tools
97 are available.
98 pmchart
100 Displays trends over time of arbitrarily selected performance
101 metrics from one or more hosts.
102 pmtime Time control utility for coordinating the time between multiple
104 tools (including pmchart and pmval).
105 pmdumptext
107 Produce ASCII reports for arbitrary combinations of performance
108 metrics.
109
111 There is a set of common command line arguments that are used consis‐
112 tently by most PCP tools.
113 -a archive
115 Performance metric information is retrospectively retrieved from
116 the Performance Co-Pilot (PCP) archive, previously generated by
117 pmlogger(1).See pcp-archive(5)forformatdocumentation. The -a
118 and -h options are mutually exclusive.
119 archive is either the base name common to all of the physical
121 files created by an instance of pmlogger(1), or any one of the
122 physical files, e.g. myarchive (base name) or myarchive.meta
123 (the metadata file) or myarchive.index (the temporal index) or
124 myarchive.0 (the first data volume of archive) or
125 myarchive.0.bz2 or myarchive.0.bz (the first data volume com‐
126 pressed with bzip2(1)) or myarchive.0.gz or myarchive.0.Z or
127 myarchive.0.z (the first data volume compressed with gzip(1)),
128 myarchive.1 or myarchive.3.bz2 or myarchive.42.gz etc.
129 -a archive[,archive,...]
131 An alternate form of -a for applications that are able to handle
132 multiple archives.
133 -h hostname
135 Unless directed to another host by the -h option, or to an ar‐
136 chive by the -a option, the source of performance metrics will
137 be the Performance Metrics Collector Daemon (PMCD) on the local
138 host. Refer to the PMCD HOST SPECIFICATION section later for
139 further details on the many options available when forming the
140 hostname specification, as well as a detailed description of the
141 default local host connection. The -a and -h options are mutu‐
142 ally exclusive.
143 -s samples
145 The argument samples defines the number of samples to be
146 retrieved and reported. If samples is 0 or -s is not specified,
147 the application will sample and report continuously (in real
148 time mode) or until the end of the PCP archive (in archive
149 mode).
150 -z Change the reporting timezone to the local timezone at the host
152 that is the source of the performance metrics, as identified via
153 either the -h or -a options.
154 -Z timezone
156 By default, applications report the time of day according to the
157 local timezone on the system where the application is executed.
158 The -Z option changes the timezone to timezone in the format of
159 the environment variable TZ as described in environ(7).
160
162 Most PCP tools operate with periodic sampling or reporting, and the -t
163 and -A options may be used to control the duration of the sample inter‐
164 val and the alignment of the sample times.
165 -t interval
167 Set the update or reporting interval.
168 The interval argument is specified as a sequence of one or more
170 elements of the form
171 number[units]
172 where number is an integer or floating point constant (parsed
173 using strtod(3)) and the optional units is one of: seconds, sec‐
174 ond, secs, sec, s, minutes, minute, mins, min, m, hours, hour,
175 h, days, day and d. If the unit is empty, second is assumed.
176 In addition, the upper case (or mixed case) version of any of
178 the above is also acceptable.
179 Spaces anywhere in the interval are ignored, so 4 days 6 hours
181 30 minutes, 4day6hour30min, 4d6h30m and 4d6.5h are all equiva‐
182 lent.
183 Multiple specifications are additive, e.g. ``1hour 15mins
185 30secs'' is interpreted as 3600+900+30 seconds.
186 -A align
188 By default samples are not necessarily aligned on any natural
189 unit of time. The -A option may be used to force the initial
190 sample to be aligned on the boundary of a natural time unit.
191 For example -A 1sec, -A 30min and -A 1hour specify alignment on
192 whole seconds, half and whole hours respectively.
193 The align argument follows the syntax for an interval argument
195 described above for the -t option.
196 Note that alignment occurs by advancing the time as required,
198 and that -A acts as a modifier to advance both the start of the
199 time window (see the next section) and the origin time (if the
200 -O option is specified).
201
203 Many PCP tools are designed to operate in some time window of interest,
204 e.g. to define a termination time for real-time monitoring or to define
205 a start and end time within a PCP archive log.
206 In the absence of the -O and -A options to specify an initial sample
208 time origin and time alignment (see above), the PCP application will
209 retrieve the first sample at the start of the time window.
210 The following options may be used to specify a time window of interest.
212 -S starttime
214 By default the time window commences immediately in real-time
215 mode, or coincides with time at the start of the PCP archive log
216 in archive mode. The -S option may be used to specify a later
217 time for the start of the time window.
218 The starttime parameter may be given in one of three forms
220 (interval is the same as for the -t option as described above,
221 datetime is described below):
222 interval
224 To specify an offset from the current time (in real-time
225 mode) or the beginning of a PCP archive (in archive mode)
226 simply specify the interval of time as the argument. For
227 example -S 30min will set the start of the time window to
228 be exactly 30 minutes from now in real-time mode, or
229 exactly 30 minutes from the start of a PCP archive.
230 -interval
232 To specify an offset from the end of a PCP archive log,
233 prefix the interval argument with a minus sign. In this
234 case, the start of the time window precedes the time at
235 the end of archive by the given interval. For example -S
236 -1hour will set the start of the time window to be
237 exactly one hour before the time of the last sample in a
238 PCP archive log.
239 @datetime
241 To specify the calendar date and time (local time in the
242 reporting timezone) for the start of the time window, use
243 the datetime syntax preceded by an at sign. Refer to the
244 datetime description below for detailed information.
245 -T endtime
247 By default the end of the time window is unbounded (in real-time
248 mode) or aligned with the time at the end of a PCP archive log
249 (in archive mode). The -T option may be used to specify an ear‐
250 lier time for the end of the time window.
251 The endtime parameter may be given in one of three forms (inter‐
253 val is the same as for the -t option as described above, date‐
254 time is described below):
255 interval
257 To specify an offset from the start of the time window
258 simply use the interval of time as the argument. For
259 example -T 2h30m will set the end of the time window to
260 be 2 hours and 30 minutes after the start of the time
261 window.
262 -interval
264 To specify an offset back from the time at the end of a
265 PCP archive log, prefix the interval argument with a
266 minus sign. For example -T -90m will set the end of the
267 time window to be 90 minutes before the time of the last
268 sample in a PCP archive log.
269 @datetime
271 To specify the calendar date and time (local time in the
272 reporting timezone) for the end of the time window, use
273 the datetime syntax preceded by an at sign. Refer to the
274 datetime description below for detailed information.
275 -O origin
277 By default samples are fetched from the start of the time window
278 (see description of -S option) to the end of the time window
279 (see description of -T option). The -O option allows the speci‐
280 fication of an origin within the time window to be used as the
281 initial sample time. This is useful for interactive use of a
282 PCP tool with the pmtime(1) VCR replay facility.
283 The origin argument accepted by -O conforms to the same syntax
285 and semantics as the starttime argument for the -T option.
286 For example -O -0 specifies that the initial position should be
288 at the end of the time window; this is most useful when wishing
289 to replay ``backwards'' within the time window.
290 The datetime argument for the -O, -S and -T options consists of:
292 date time zone day relative
293 A date can be one of: YY-MM-DD, MM/DD/YY, DD Month YYYY, or Month DD
294 YYYY. A time can be one of: HH:MM:SS, HH:MM. HH:MM can use either the
295 12 hour (via an am or pm suffix) or 24 hour convention. A day of the
296 week can be a spelled out day of the week, optionally preceded by an
297 ordinal number such as second tuesday. A zone is a time zone value as
298 specified by the tzselect(1) command. A relative time can be a time
299 unit that is: preceded by a cardinal number such as 1 year or 2 months,
300 preceded by one of the time words this or last, or succeeded by the
301 time word ago. A relative time can also be one of the time words: yes‐
302 terday, today, tomorrow, now. Examples of datetime strings are:
303 1996-03-04 13:07:47 EST Mon, 1996-03-05 14:07:47 EST -1hour, Mon Mar 4
304 13:07:47 1996, Mar 4 1996, Mar 4, Mar, 13:07:50 or 13:08.
305 For any missing low order fields, the default value of 0 is assumed for
307 hours, minutes and seconds, 1 for day of the month and Jan for months.
308 Hence, the following are equivalent: -S '@ Mar 1996' and -S '@ Mar 1
309 00:00:00 1996'.
310 If any high order fields are missing, they are filled in by starting
312 with the year, month and day from the current time (real-time mode) or
313 the time at the beginning of the PCP archive log (archive mode) and
314 advancing the time until it matches the fields that are specified. So,
315 for example if the time window starts by default at ``Mon Mar 4
316 13:07:47 1996'', then -S @13:10 corresponds to 13:10:00 on Mon Mar 4,
317 1996, while -S @10:00 corresponds to 10:00:00 on Tue Mar 5, 1996 (note
318 this is the following day).
319 For greater precision than afforded by datetime(3), the seconds compo‐
321 nent may be a floating point number.
322
324 The number of performance metric names supported by PCP on most plat‐
325 forms ranges from many hundreds to several thousand. The PCP libraries
326 and applications use an internal identification scheme that unambigu‐
327 ously associates a single integer with each known performance metric.
328 This integer is known as the Performance Metric Identifier, or PMID.
329 Although not a requirement, PMIDs tend to have global consistency
330 across all systems, so a particular performance metric usually has the
331 same PMID.
332 For all users and most applications, direct use of the PMIDs would be
334 inappropriate (e.g. this would limit the range of accessible metrics,
335 make the code hard to maintain, force the user interface to be particu‐
336 larly baroque, etc.). Hence a Performance Metrics Name Space (PMNS) is
337 used to provide external names and a hierarchic classification for per‐
338 formance metrics. A PMNS is represented as a tree, with each node hav‐
339 ing a label, a pointer to either a PMID (for leaf nodes) or a set of
340 descendent nodes in the PMNS (for non-leaf nodes).
341 A node label must begin with an alphabetic character, followed by zero
343 or more characters drawn from the alphabetics, the digits and character
344 `_´ (underscore). For alphabetic characters in a node label, upper and
345 lower case are distinguished.
346 By convention, the name of a performance metric is constructed by con‐
348 catenation of the node labels on a path through the PMNS from the root
349 node to a leaf node, with a ``.'' as a separator. The root node in the
350 PMNS is unlabeled, so all names begin with the label associated with
351 one of the descendent nodes below the root node of the PMNS, e.g. ker‐
352 nel.percpu.syscall. Typically (although this is not a requirement)
353 there would be at most one name for each PMID in a PMNS. For example
354 kernel.all.cpu.idle and disk.dev.read are the unique names for two dis‐
355 tinct performance metrics, each with a unique PMID.
356 Groups of related PMIDs may be named by naming a non-leaf node in the
358 PMNS tree, e.g. disk.
359 The default local PMNS used by pmcd is located at
361 $PCP_VAR_DIR/pmns/root however the environment variable PMNS_DEFAULT
362 may be set to the full pathname of a different PMNS which will then be
363 used as the default local PMNS.
364 Most applications do not use the local PMNS directly, but rather import
366 parts of the PMNS as required from the same place that performance met‐
367 rics are fetched, i.e. from pmcd(1) for live monitoring or from a PCP
368 archive for retrospective monitoring.
369 To explore the PMNS use pminfo(1), or if the PCP GUI package is
371 installed the New Chart and Metric Search windows within pmchart(1).
372
374 In configuration files and (to a lesser extent) command line options,
375 metric specifications adhere to the following syntax rules.
376 If the source of performance metrics is real-time from pmcd(1) then the
378 accepted syntax is
379 host:metric[instance1,instance2,...]
380 If the source of performance metrics is a PCP archive log then the
382 accepted syntax is
383 archive/metric[instance1,instance2,...]
384 The host:, archive/ and [instance1,instance2,...] components are all
386 optional.
387 The , delimiter in the list of instance names may be replaced by white
389 space.
390 Special characters in instance names may be escaped by surrounding the
392 name in double quotes or preceding the character with a backslash.
393 White space is ignored everywhere except within a quoted instance name.
395 An empty instance is silently ignored, and in particular ``[]'' is the
397 same as no instance, while ``[one,,,two]'' is parsed as specifying just
398 the two instances ``one'' and ``two''.
399 As a special case, if the host is the single character ``@'' then this
401 refers to a PM_CONTEXT_LOCAL source, see pmNewContext(3).
402
404 Since PCP version 3.6.11, a monitor can explicitly request a secure
405 connection to a collector host running pmcd(1) or pmproxy(1) using the
406 PM_CTXFLAG_SECURE context flag. If the PCP Collector host supports
407 this feature - refer to the pmcd.feature.secure metric for confirmation
408 of this - a TLS/SSL (Transport Layer Security or Secure Sockets Layer)
409 connection can be established which uses public key cryptography and
410 related techniques. These features aim to prevent eavesdropping and
411 data tampering from a malicious third party, as well as providing
412 server-side authentication (confident identification of a server by a
413 client) which can be used to guard against man-in-the-middle attacks.
414 A secure pmcd connection requires use of certificate-based authentica‐
416 tion. The security features offered by pmcd and pmproxy are imple‐
417 mented using the Network Security Services (NSS) APIs and utilities.
418 The NSS certutil tool can be used to create certificates suitable for
419 establishing trust between PCP monitor and collector hosts.
420 A complete description is beyond the scope of this document, refer to
422 the PCP ENVIRONMENT, FILES and SEE ALSO sections for detailed informa‐
423 tion. This includes links to tutorials on the steps involved in set‐
424 ting up the available security features.
425
427 In the absence of an explicit host name specification, most tools will
428 default to the local host in live update mode. In PCP releases since
429 3.8.4 onward, this results in an efficient local protocol being
430 selected - typically a Unix domain socket. If this option is used
431 (which can also be explicitly requested via the unix: host specifica‐
432 tion described below), it is important to note that all connections
433 will be automatically authenticated. In other words, the credentials of
434 the user invoking a client tool will automatically be made available to
435 pmcd(1) and all of its PMDAs, on the users behalf, such that results
436 can be customized to the privilege levels of individual users.
437 Names of remote hosts running the pmcd(1) daemon can of course also be
439 provided to request a remote host be used. The most basic form of pmcd
440 host specification is a simple host name, possibly including the domain
441 name if necessary. However, this can be extended in a number of ways
442 to further refine attributes of the connection made to pmcd.
443 The pmcd port number and also optional pmproxy(1) hostname and its port
445 number, can be given as part of the host specification, since PCP ver‐
446 sion 3.0. These supersede (and override) the old-style PMCD_PORT,
447 PMPROXY_HOST and PMPROXY_PORT environment variables.
448 The following are valid hostname specifications that specify connec‐
450 tions to pmcd on host nas1.servers.com with/without a list of ports,
451 with/without a pmproxy(1) connection through a firewall, and with IPv6
452 and IPv4 addresses as shown.
453 $ pcp -h nas1.servers.com:44321,4321@firewall.servers.com:44322
455 $ pcp -h nas1.servers.com:44321@firewall.servers.com:44322
456 $ pcp -h nas1.servers.com:44321@firewall.servers.com
457 $ pcp -h nas1.servers.com@firewall.servers.com
458 $ pcp -h nas1.servers.com:44321
459 $ pcp -h [fe80::2ad2:44ff:fe88:e4f1%p2p1]
460 $ pcp -h 192.168.0.103
461 In addition, ``connection attributes'' can also be specified. These
463 include username, password (can be given interactively and may depend
464 on the authentication mechanism employed), whether to target a specific
465 running container, whether to use secure (encrypted) or native (naked)
466 protocol, and so on. The previous examples all default to native pro‐
467 tocol, and use no authentication. This can be altered, as in the fol‐
468 lowing examples.
469 $ pcp -h pcps://app2.servers.com?container=cae8e6edc0d5
471 $ pcp -h pcps://nas1.servers.com:44321?username=tanya&method=gssapi
472 $ pcp -h pcps://nas2.servers.com@firewalls.r.us?method=plain
473 $ pcp -h pcp://nas3.servers.com
474 $ pcp -h 192.168.0.103?container=cae8e6edc0d5,method=digest-md5
475 $ pcp -h unix:
476 $ pcp -h local:
477 The choice of authentication method, and other resulting parameters
479 like username, optionally password, etc, depends on the SASL2 configu‐
480 ration used by each (remote) pmcd. Tutorials are available specifying
481 various aspects of configuring the authentication module(s) used, these
482 fine details are outside the scope of this document.
483 In all situations, host names can be used interchangeably with IPv4 or
485 IPv6 addressing (directly), as shown above. In the case of an IPv6
486 address, the full address must be enclosed by square brackets and the
487 scope (interface) must also be specified.
488 The final local: example above is now the default for most tools. This
490 connection is an automatically authenticated local host connection on
491 all platforms that support Unix domain sockets. No password is
492 required and authentication is automatic. This is also the most effi‐
493 cient (lowest overhead) communication channel available.
494 The difference between unix: and local: is that the former is a strict
496 Unix domain socket specification (connection fails if it cannot connect
497 that way), whereas the latter has a more forgiving fallback to using
498 localhost (i.e. a regular Inet socket connection is used when Unix
499 domain socket connections are unavailable).
500
502 In addition to the PCP run-time environment and configuration variables
503 described in the PCP ENVIRONMENT section below, the following environ‐
504 ment variables apply to all installations.
505 PCP_CONSOLE
507 When set, this changes the default console from /dev/tty (on
508 Unix) or CON: (on Windows) to be the specified console. The
509 special value of none can be used to indicate no console is
510 available for use. This is used in places where console-based
511 tools need to interact with the user, and in particular is used
512 when authentication is being performed.
513 PCP_DEBUG
515 When set, this variable provides an alternate way to initialize
516 the value used to control diagnostic and debug output (the
517 default value is 0 to suppress this output). The value for
518 $PCP_DEBUG should be a decimal integer, see pmdbg(1) for a
519 description of the supported values.
520 PCP_DERIVED_CONFIG
522 When set, this variable defines a colon separated list of files
523 and/or directories (the syntax is the same as for the $PATH
524 variable for sh(1)). The components are expanded into a list of
525 files as follows: if a component of $PCP_DERIVED_CONFIG is a
526 file, then that file is added to the list, else if a component
527 is a directory then recursive descent is used to enumerate all
528 files below that directory and these are added to the list.
529 Each file in the resulting list is assumed to contain defini‐
531 tions of derived metrics as per the syntax described in pmLoad‐
532 DerivedConfig(3), and these are loaded in order.
533 Derived metrics may be used to extend the available metrics with
535 new (derived) metrics using simple arithmetic expressions.
536 If PCP_DERIVED_CONFIG is set, the derived metric definitions are
538 processed automatically as each new source of performance met‐
539 rics is established (i.e. each time a pmNewContext(3) is called)
540 or when requests are made against the PMNS.
541 Any component in the $PCP_DERIVED_CONFIG list or the expanded
543 list of files that is not a file, or is not a directory or is
544 not accessible (due to permissions or a bad symbolic link) will
545 be silently ignored.
546 PCP_SECURE_SOCKETS
548 When set, this variable forces any monitor tool connections to
549 be established using the certificate-based secure sockets fea‐
550 ture. If the connections cannot be established securely, they
551 will fail.
552 PCP_SECURE_DB_METHOD
554 With secure socket connections, the certificate and key database
555 is stored using the sql: method by default. Use
556 PCP_SECURE_DB_METHOD to override the default, most usually set‐
557 ting the value to the empty string (for the older database meth‐
558 ods).
559 PCP_STDERR
561 Many PCP tools support the environment variable PCP_STDERR,
562 which can be used to control where error messages are sent.
563 When unset, the default behavior is that ``usage'' messages and
564 option parsing errors are reported on standard error, other mes‐
565 sages after initial startup are sent to the default destination
566 for the tool, i.e. standard error for ASCII tools, or a dialog
567 for GUI tools.
568 If PCP_STDERR is set to the literal value DISPLAY then all mes‐
570 sages will be displayed in a dialog. This is used for any tools
571 launched from the a Desktop environment.
572 If PCP_STDERR is set to any other value, the value is assumed to
574 be a filename, and all messages will be written there.
575 PMCD_CONNECT_TIMEOUT
577 When attempting to connect to a remote pmcd(1) on a machine that
578 is booting, the connection attempt could potentially block for a
579 long time until the remote machine finishes its initialization.
580 Most PCP applications and some of the PCP library routines will
581 abort and return an error if the connection has not been estab‐
582 lished after some specified interval has elapsed. The default
583 interval is 5 seconds. This may be modified by setting
584 PMCD_CONNECT_TIMEOUT in the environment to a real number of sec‐
585 onds for the desired timeout. This is most useful in cases
586 where the remote host is at the end of a slow network, requiring
587 longer latencies to establish the connection correctly.
588 PMCD_RECONNECT_TIMEOUT
590 When a monitor or client application loses a connection to a
591 pmcd(1), the connection may be re-established by calling a ser‐
592 vice routine in the PCP library. However, attempts to reconnect
593 are controlled by a back-off strategy to avoid flooding the net‐
594 work with reconnection requests. By default, the back-off
595 delays are 5, 10, 20, 40 and 80 seconds for consecutive recon‐
596 nection requests from a client (the last delay will be repeated
597 for any further attempts after the fifth). Setting the environ‐
598 ment variable PMCD_RECONNECT_TIMEOUT to a comma separated list
599 of positive integers will re-define the back-off delays, e.g.
600 setting PMCD_RECONNECT_TIMEOUT to ``1,2'' will back-off for 1
601 second, then attempt another connection request every 2 seconds
602 thereafter.
603 PMCD_REQUEST_TIMEOUT
605 For monitor or client applications connected to pmcd(1), there
606 is a possibility of the application "hanging" on a request for
607 performance metrics or metadata or help text. These delays may
608 become severe if the system running pmcd crashes, or the network
609 connection is lost. By setting the environment variable
610 PMCD_REQUEST_TIMEOUT to a number of seconds, requests to pmcd
611 will timeout after this number of seconds. The default behavior
612 is to be willing to wait 10 seconds for a response from every
613 pmcd for all applications.
614 PMCD_WAIT_TIMEOUT
616 When pmcd(1) is started from $PCP_RC_DIR/pcp then the primary
617 instance of pmlogger(1) will be started if the configuration
618 flag pmlogger is chkconfig(8) enabled and pmcd is running and
619 accepting connections.
620 The check on pmcd's readiness will wait up to PMCD_WAIT_TIMEOUT
622 seconds. If pmcd has a long startup time (such as on a very
623 large system), then PMCD_WAIT_TIMEOUT can be set to provide a
624 maximum wait longer than the default 60 seconds.
625 PMNS_DEFAULT
627 If set, then interpreted as the full pathname to be used as the
628 default local PMNS for pmLoadNameSpace(3). Otherwise, the
629 default local PMNS is located at $PCP_VAR_DIR/pcp/pmns/root for
630 base PCP installations.
631 PCP_COUNTER_WRAP
633 Many of the performance metrics exported from PCP agents have
634 the semantics of counter meaning they are expected to be mono‐
635 tonically increasing. Under some circumstances, one value of
636 these metrics may smaller than the previously fetched value.
637 This can happen when a counter of finite precision overflows, or
638 when the PCP agent has been reset or restarted, or when the PCP
639 agent is exporting values from some underlying instrumentation
640 that is subject to some asynchronous discontinuity.
641 The environment variable PCP_COUNTER_WRAP may be set to indicate
643 that all such cases of a decreasing ``counter'' should be
644 treated as a counter overflow, and hence the values are assumed
645 to have wrapped once in the interval between consecutive sam‐
646 ples. This ``wrapping'' behavior was the default in earlier PCP
647 versions, but by default has been disabled in PCP release from
648 version 1.3 on.
649 PMDA_PATH
651 The PMDA_PATH environment variable may be used to modify the
652 search path used by pmcd(1) and pmNewContext(3) (for PM_CON‐
653 TEXT_LOCAL contexts) when searching for a daemon or DSO PMDA.
654 The syntax follows that for PATH in sh(1), i.e. a colon sepa‐
655 rated list of directories, and the default search path is
656 ``/var/pcp/lib:/usr/pcp/lib'', (or ``/var/lib/pcp/lib'' on
657 Linux, depending on the value of the $PCP_VAR_DIR environment
658 variable).
659 PMCD_PORT
661 The TPC/IP port(s) used by pmcd(1) to create the socket for
662 incoming connections and requests, was historically 4321 and
663 more recently the officially registered port 44321; in the cur‐
664 rent release, both port numbers are used by default as a transi‐
665 tional arrangement. This may be over-ridden by setting
666 PMCD_PORT to a different port number, or a comma-separated list
667 of port numbers. If a non-default port is used when pmcd is
668 started, then every monitoring application connecting to that
669 pmcd must also have PMCD_PORT set in their environment before
670 attempting a connection.
671 The following environment variables are relevant to installations in
673 which pmlogger(1), the PCP archive logger, is used.
674 PMLOGGER_PORT
676 The environment variable PMLOGGER_PORT may be used to change the
677 base TCP/IP port number used by pmlogger(1) to create the socket
678 to which pmlc(1) instances will try and connect. The default
679 base port number is 4330. When used, PMLOGGER_PORT should be
680 set in the environment before pmlogger is executed.
681 PMLOGGER_REQUEST_TIMEOUT
683 When pmlc(1) connects to pmlogger(1), there is a remote possi‐
684 bility of pmlc "hanging" on a request for information as a con‐
685 sequence of a failure of the network or pmlogger. By setting
686 the environment variable PMLOGGER_REQUEST_TIMEOUT to a number of
687 seconds, requests to pmlogger will timeout after this number of
688 seconds. The default behavior is to be willing to wait forever
689 for a response from each request to a pmlogger. When used,
690 PMLOGGER_REQUEST_TIMEOUT should be set in the environment before
691 pmlc is executed.
692 If you have the PCP product installed, then the following environment
694 variables are relevant to the Performance Metrics Domain Agents
695 (PMDAs).
696 PMDA_LOCAL_PROC
698 Use this variable has been deprecated and it is now ignored. If
699 the ``proc'' PMDA is configured as a DSO for use with pmcd(1) on
700 the local host then all of the ``proc'' metrics will be avail‐
701 able to applications using a PM_CONTEXT_LOCAL context.
702 The previous behaviour was that if this variable was set, then a
704 context established with the type of PM_CONTEXT_LOCAL will have
705 access to the ``proc'' PMDA to retrieve performance metrics
706 about individual processes.
707 PMDA_LOCAL_SAMPLE
709 Use this variable has been deprecated and it is now ignored. If
710 the ``sample'' PMDA is configured as a DSO for use with pmcd(1)
711 on the local host then all of the ``sample'' metrics will be
712 available to applications using a PM_CONTEXT_LOCAL context.
713 The previous behaviour was that if this variable was set, then a
715 context established with the type of PM_CONTEXT_LOCAL will have
716 access to the ``sample'' PMDA if this optional PMDA has been
717 installed locally.
718 PMIECONF_PATH
720 If set, pmieconf(1) will form its pmieconf(5) specification (set
721 of parameterized pmie(1) rules) using all valid pmieconf files
722 found below each subdirectory in this colon-separated list of
723 subdirectories. If not set, the default is $PCP_VAR_DIR/con‐
724 fig/pmieconf.
725
727 /etc/pcp.conf
728 Configuration file for the PCP runtime environment, see
729 pcp.conf(5).
730 /etc/pki/nssdb
731 Optionally contains a Network Security Services database with
732 a "PCP Collector" certificate providing trusted identifica‐
733 tion for the collector host.
734 $HOME/.pcp
735 User-specific directories containing configuration files for
736 customisation of the various monitor tools, such as
737 pmchart(1).
738 $HOME/.pki/nssdb
739 A shared Network Security Services (NSS) database directory
740 containing per-user certificates identifying known valid
741 remote pmcd collector hosts. The NSS certutil tool is one of
742 several that can be used to maintain this database.
743 $PCP_RC_DIR/pcp
744 Script for starting and stopping pmcd(1).
745 $PCP_PMCDCONF_PATH
746 Control file for pmcd(1).
747 $PCP_PMCDOPTIONS_PATH
748 Command line options passed to pmcd(1) when it is started
749 from $PCP_RC_DIR/pcp. All the command line option lines
750 should start with a hyphen as the first character. This file
751 can also contain environment variable settings of the form
752 "VARIABLE=value".
753 $PCP_BINADM_DIR
754 Location of PCP utilities for collecting and maintaining PCP
755 archives, PMDA help text, PMNS files etc.
756 $PCP_PMDAS_DIR
757 Parent directory of the installation directory for Dynamic
758 Shared Object (DSO) PMDAs.
759 $PCP_RUN_DIR/pmcd.pid
760 If pmcd is running, this file contains an ascii decimal rep‐
761 resentation of its process ID.
762 $PCP_LOG_DIR/pmcd
763 Default location of log files for pmcd(1), current directory
764 for running PMDAs. Archives generated by pmlogger(1) are
765 generally below $PCP_LOG_DIR/pmlogger.
766 $PCP_LOG_DIR/pmcd/pmcd.log
767 Diagnostic and status log for the current running pmcd(1)
768 process. The first place to look when there are problems
769 associated with pmcd.
770 $PCP_LOG_DIR/pmcd/pmcd.log.prev
771 Diagnostic and status log for the previous pmcd(1) instance.
772 $PCP_LOG_DIR/NOTICES
773 Log of pmcd(1) and PMDA starts, stops, additions and
774 removals.
775 $PCP_VAR_DIR/config
776 Contains directories of configuration files for several PCP
777 tools.
778 $PCP_SYSCONF_DIR/pmcd/rc.local
779 Local script for controlling PCP boot, shutdown and restart
780 actions.
781 $PCP_VAR_DIR/pmns
782 Directory containing the set of PMNS files for all installed
783 PMDAs.
784 $PCP_VAR_DIR/pmns/root
785 The ASCII pmns(5) exported by pmcd(1) by default. This PMNS
786 is be the super set of all other PMNS files installed in
787 $PCP_VAR_DIR/pmns.
788 In addition, if the PCP product is installed the following files and
789 directories are relevant.
790 $PCP_LOG_DIR/NOTICES
791 In addition to the pmcd(1) and PMDA activity, may be used to log
792 alarms and notices from pmie(1) via pmpost(1).
793 $PCP_PMLOGGERCONTROL_PATH
794 Control file for pmlogger(1) instances launched from
795 $PCP_RC_DIR/pcp and/or managed by pmlogger_check(1) and pmlog‐
796 ger_daily(1) as part of a production PCP archive collection set‐
797 up.
798
800 Environment variables with the prefix PCP_ are used to parameterize the
801 file and directory names used by PCP. On each installation, the file
802 /etc/pcp.conf contains the local values for these variables. The
803 $PCP_CONF variable may be used to specify an alternative configuration
804 file, as described in pcp.conf(5).
805
807 pmcd(1), pmie(1), pmie_daily(1), pminfo(1), pmlc(1), pmlogger(1),
808 pmlogger_daily(1), pmrep(1), pmstat(1), pmval(1), pcp(1), pcp.conf(5),
809 pcp.env(5), pmns(5) and chkconfig(8).
810 If the PCP GUI package is installed, then the following entries are
812 also relevant:
813 pmchart(1), pmtime(1), and pmdumptext(1).
814 If the secure sockets extensions have been enabled, then the following
816 references are also relevant:
817 http://www.pcp.io/documentation.html
818 http://www.mozilla.org/projects/security/pki/nss/#documentation
819 http://www.mozilla.org/projects/security/pki/nss/tools/certutil.html
820 Also refer to the books Performance Co-Pilot User's and Administrator's
822 Guide and Performance Co-Pilot Programmer's Guide which can be found at
823 http://www.pcp.io/
824Performance Co-Pilot PCP PCPINTRO(1)