1PCPINTRO(1)                 General Commands Manual                PCPINTRO(1)
2
3
4

NAME

6       PCPIntro - introduction to the Performance Co-Pilot (PCP)
7

INTRODUCTION

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
14       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
18       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
23       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
30       This manual entry describes the high-level features and options  common
31       to most PCP utilities available on all platforms.
32

OVERVIEW

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
43       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
49   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
55       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
61       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
65       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
71   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
76       Each  tool  or  command  is  documented completely in its own reference
77       page.
78
79       pmstat Outputs an ASCII high-level summary of system performance.
80
81       pmie   An inference engine that can evaluate predicate-action rules  to
82              perform alarms and automate system management tasks.
83
84       pminfo Interrogate  specific  performance metrics and the metadata that
85              describes them.
86
87       pmlogger
88              Generates PCP  archives  of  performance  metrics  suitable  for
89              replay by most PCP tools.
90
91       pmrep  Highly  customizable  performance  metrics reporter with support
92              for various different output modes.
93
94       pmval  Simple periodic reporting for some or all instances of a perfor‐
95              mance metric, with optional VCR time control.
96
97       If the PCP GUI package is installed then the following additional tools
98       are available.
99
100       pmchart
101              Displays trends over time of  arbitrarily  selected  performance
102              metrics from one or more hosts.
103
104       pmtime Time  control utility for coordinating the time between multiple
105              tools (including pmchart and pmval).
106
107       pmdumptext
108              Produce ASCII reports for arbitrary combinations of  performance
109              metrics.
110

COMMON COMMAND LINE ARGUMENTS

112       There  is  a set of common command line arguments that are used consis‐
113       tently by most PCP tools.
114
115       -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
122              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
134       -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
145       -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
152       -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
157       -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
164       -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
172       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

INTERVAL SPECIFICATION AND ALIGNMENT

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
186       -t interval, --interval=interval
187              Set the update or reporting interval.
188
189              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
197              In addition, the upper case (or mixed case) version  of  any  of
198              the above is also acceptable.
199
200              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
204              Multiple specifications are additive, for example ``1hour 15mins
205              30secs'' is interpreted as 3600+900+30 seconds.
206
207       -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
214              The align argument follows the syntax for an  interval  argument
215              described above for the -t or --interval option.
216
217              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

TIME WINDOW SPECIFICATION

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
227       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
232       The following options may be used to specify a time window of interest.
233
234       -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
240              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
244              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
253              -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
262              @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
268       -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
274              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
278              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
285              -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
292              @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
298       -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
307              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
311              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
315       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
331       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
336       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
345       For  greater precision than afforded by datetime(3), the seconds compo‐
346       nent may be a floating point number.
347
348       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

PERFORMANCE METRICS - IDENTIFIERS, NAMES, VALUES

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
366       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
375       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
380       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
390       Groups  of  related PMIDs may be named by naming a non-leaf node in the
391       PMNS tree, for example disk.
392
393       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
398       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
403       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
406       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
412       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
428       Multiple  performance  metrics may be associated with a single instance
429       domain.
430
431       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
437       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 occasions 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

PERFORMANCE METRIC SPECIFICATIONS

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
455       If the source of performance metrics is real-time from pmcd(1) then the
456       accepted syntax is
457                 host:metric[instance1,instance2,...]
458
459       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
463       The  host:,  archive/ and [instance1,instance2,...]  components are all
464       optional.
465
466       The , delimiter in the list of instance names may be replaced by  white
467       space.
468
469       Special  characters in instance names may be escaped by surrounding the
470       name in double quotes or preceding the character with a backslash.
471
472       White space is ignored everywhere except within a quoted instance name.
473
474       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
478       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

SECURE PMCD CONNECTIONS

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
493       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
499       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

PMCD HOST SPECIFICATION

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
516       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
522       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
527       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
532            $ 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
540       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
548            $ 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
556       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
562       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
567       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
573       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

ENVIRONMENT

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
584       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
590       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
595       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
600       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
608       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
616       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
625              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
629              Derived metrics may be used to extend the available metrics with
630              new (derived) metrics using simple arithmetic expressions.
631
632              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
637              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
642       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
656              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
664       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
670       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
677       PCP_SECURE_DB_PATH
678              When set, this variable specifies an alternate certificate data‐
679              base  path  for  client  tools.  Similar to the action of the -C
680              option for pmcd(1) and pmproxy(1).
681
682       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
691              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 a Desktop environment.
694
695              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
698       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
711       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
726       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
737       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
743              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
748       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
754       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
764              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
772       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
782       PMCD_PORT
783              The TCP/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
794       The  following  environment  variables are relevant to installations in
795       which pmlogger(1), the PCP archive logger, is used.
796
797       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
804       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
815       If you have the PCP product installed, then the  following  environment
816       variables  are  relevant  to  the  Performance  Metrics  Domain  Agents
817       (PMDAs).
818
819       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
825              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
830       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
836              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
841       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

FILES

849       /etc/pcp.conf
850            Configuration  file  for  the   PCP   runtime   environment,   see
851            pcp.conf(5).
852
853       /etc/pki/nssdb
854            Optionally  contains  a  Network Security Services database with a
855            "PCP Collector" certificate providing trusted  identification  for
856            the collector host.
857
858       $HOME/.pcp
859            User-specific  directories containing configuration files for cus‐
860            tomisation of the various monitor tools, such as pmchart(1).
861
862       $HOME/.pki/nssdb
863            A shared Network Security Services (NSS) database  directory  con‐
864            taining  per-user certificates identifying known valid remote pmcd
865            collector hosts.  The NSS certutil tool is one of several that can
866            be used to maintain this database.
867
868       $PCP_RC_DIR/pcp
869            Script for starting and stopping pmcd(1).
870
871       $PCP_PMCDCONF_PATH
872            Control file for pmcd(1).
873
874       $PCP_PMCDOPTIONS_PATH
875            Command  line  options  passed  to pmcd(1) when it is started from
876            $PCP_RC_DIR/pcp.  All the command line option lines  should  start
877            with  a hyphen as the first character.  This file can also contain
878            environment variable settings of the form "VARIABLE=value".
879
880       $PCP_BINADM_DIR
881            Location of PCP utilities for collecting and maintaining  PCP  ar‐
882            chives, PMDA help text, PMNS files etc.
883
884       $PCP_PMDAS_DIR
885            Parent  directory of the installation directory for Dynamic Shared
886            Object (DSO) PMDAs.
887
888       $PCP_RUN_DIR/pmcd.pid
889            If pmcd is running, this file contains an ascii decimal  represen‐
890            tation of its process ID.
891
892       $PCP_LOG_DIR/pmcd
893            Default  location  of log files for pmcd(1), current directory for
894            running PMDAs.  Archives generated by  pmlogger(1)  are  generally
895            below $PCP_LOG_DIR/pmlogger.
896
897       $PCP_LOG_DIR/pmcd/pmcd.log
898            Diagnostic and status log for the current running pmcd(1) process.
899            The first place to look when there are  problems  associated  with
900            pmcd.
901
902       $PCP_LOG_DIR/pmcd/pmcd.log.prev
903            Diagnostic and status log for the previous pmcd(1) instance.
904
905       $PCP_LOG_DIR/NOTICES
906            Log of pmcd(1) and PMDA starts, stops, additions and removals.
907
908       $PCP_VAR_DIR/config
909            Contains directories of configuration files for several PCP tools.
910
911       $PCP_SYSCONF_DIR/pmcd/rc.local
912            Local  script  for  controlling  PCP  boot,  shutdown  and restart
913            actions.
914
915       $PCP_VAR_DIR/pmns
916            Directory containing the set  of  PMNS  files  for  all  installed
917            PMDAs.
918
919       $PCP_VAR_DIR/pmns/root
920            The ASCII PMNS(5) exported by pmcd(1) by default.  This PMNS is be
921            the  super  set   of   all   other   PMNS   files   installed   in
922            $PCP_VAR_DIR/pmns.
923
924       In  addition,  if  the PCP product is installed the following files and
925       directories are relevant.
926
927       $PCP_LOG_DIR/NOTICES
928              In addition to the pmcd(1) and PMDA activity, may be used to log
929              alarms and notices from pmie(1) via pmpost(1).
930
931       $PCP_PMLOGGERCONTROL_PATH
932              Control   file   for   pmlogger(1)   instances   launched   from
933              $PCP_RC_DIR/pcp and/or managed by pmlogger_check(1)  and  pmlog‐
934              ger_daily(1) as part of a production PCP archive collection set‐
935              up.
936

PCP ENVIRONMENT

938       Environment variables with the prefix PCP_ are used to parameterize the
939       file  and  directory names used by PCP.  On each installation, the file
940       /etc/pcp.conf contains the  local  values  for  these  variables.   The
941       $PCP_CONF  variable may be used to specify an alternative configuration
942       file, as described in pcp.conf(5).
943
944       For environment variables affecting PCP tools, see pmGetOptions(3).
945

SEE ALSO

947       pcp(1), pmcd(1), pmie(1),  pmie_daily(1),  pminfo(1),  pmlc(1),  pmlog‐
948       ger(1), pmlogger_daily(1), pmrep(1), pmstat(1), pmval(1), systemctl(1),
949       LOGIMPORT(3), LOGARCHIVE(5), pcp.conf(5), pcp.env(5), PMNS(5) and  chk‐
950       config(8).
951
952       If  the  PCP  GUI  package is installed, then the following entries are
953       also relevant:
954       pmchart(1), pmtime(1), and pmdumptext(1).
955
956       If the secure sockets extensions have been enabled, then the  following
957       references are also relevant:
958       https://pcp.io/documentation.html
959       http://www.mozilla.org/projects/security/pki/nss/#documentation
960       http://www.mozilla.org/projects/security/pki/nss/tools/certutil.html
961
962       Also refer to the books Performance Co-Pilot User's and Administrator's
963       Guide and Performance Co-Pilot Programmer's Guide which can be found at
964       https://pcp.io/.
965
966
967
968Performance Co-Pilot                  PCP                          PCPINTRO(1)
Impressum