Provided by: pcp_3.5.6ubuntu1_i386 bug

NAME

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

INTRODUCTION

       The   Performance  Co-Pilot  (PCP)  is  an  SGI  toolkit  designed  for
       monitoring and managing system-level performance.  These  services  are
       distributed  and  scalable  to  accommodate  the  most  complex  system
       configurations and performance problems.

       PCP supports many different platforms, including (but not  limited  to)
       Linux,  MacOSX,  IRIX, AIX, Solaris and Windows.  From a high-level PCP
       can be considered to contain two classes of software utility:

       PCP Collectors
               These are the parts of PCP that collect and extract performance
               data   from  various  sources,  e.g.  the  Linux  /proc  pseudo
               filesystem.   These   are   available   under   GPL/LPGL   from
               http://oss.sgi.com/projects/pcp.

       PCP Monitors
               These  are  the  parts  of PCP that display data collected from
               hosts (or archives) that  have  the  PCP  Collector  installed.
               Many  monitor tools are available as part of PCP under GPL/LPGL
               from   http://oss.sgi.com/projects/pcp.     Other    (typically
               graphical) monitoring tools are available separately in the PCP
               GUI package.

       This manual entry describes the high-level features and options  common
       to most PCP utilities available on all platforms.

OVERVIEW

       The  PCP architecture is distributed in the sense that any PCP tool may
       be executing remotely.  On the host (or hosts)  being  monitored,  each
       domain  of  performance metrics, whether the kernel, a service layer, a
       database  management  system,  a  web  server,  an  application,   etc.
       requires a Performance Metrics Domain Agent (PMDA) which is responsible
       for collecting performance measurements from that  domain.   All  PMDAs
       are controlled by the Performance Metrics Collector Daemon (pmcd(1)) on
       the same host.

       Client applications (the monitoring tools) connect  to  pmcd(1),  which
       acts   as  a  router  for  requests,  by  forwarding  requests  to  the
       appropriate PMDA and returning the responses to the  clients.   Clients
       may  also  access  performance  data  from a PCP archive (created using
       pmlogger(1)) for retrospective analysis.

       The following performance monitoring applications are primarily console
       based,  are  typically  run directly from the command line, and are all
       part of the base PCP package.

       Each tool or command is documented  completely  in  its  own  reference
       page.

       pmstat Outputs an ASCII high-level summary of system performance.

       pmie   An  inference engine that can evaluate predicate-action rules to
              perform alarms and automate system management tasks.

       pminfo Interrogate specific performance metrics and the  metadata  that
              describes them.

       pmlogger
              Generates  PCP  archives  of  performance  metrics  suitable for
              replay by most PCP tools.

       pmval  Simple periodic  reporting  for  some  or  all  instances  of  a
              performance metric, with optional VCR time control.

       If the PCP GUI package is installed then the following additional tools
       are available.

       pmchart
              Displays trends over time of  arbitrarily  selected  performance
              metrics from one or more hosts.

       pmtime Time  control utility for coordinating the time between multiple
              tools (including pmchart and pmval).

       pmdumptext
              Produce ASCII reports for arbitrary combinations of  performance
              metrics.

COMMON COMMAND LINE ARGUMENTS

       There  is  a  set  of  common  command  line  arguments  that  are used
       consistently by most PCP tools.

       -a archive
              Performance metric information is retrospectively retrieved from
              the  Performance Co-Pilot (PCP) archive, previously generated by
              pmlogger(1).  The -a and -h options are mutually exclusive.

              archive is either the base name common to all  of  the  physical
              files  created  by an instance of pmlogger(1), or any one of the
              physical files, e.g.  myarchive (base  name)  or  myarchive.meta
              (the  metadata  file) or myarchive.index (the temporal index) or
              myarchive.0   (the   first   data   volume   of   archive)    or
              myarchive.0.bz2   or   myarchive.0.bz  (the  first  data  volume
              compressed with bzip2(1)) or myarchive.0.gz or myarchive.0.Z  or
              myarchive.0.z  (the  first data volume compressed with gzip(1)),
              myarchive.1 or myarchive.3.bz2 or myarchive.42.gz etc.

       -a archive[,archive,...]
              An alternate form of -a for applications that are able to handle
              multiple archives.

       -h hostname
              Unless  directed  to  another  host  by  the -h option, or to an
              archive by the -a option, the source of performance metrics will
              be  the Performance Metrics Collector Daemon (PMCD) on the local
              host.  The -a and -h options are mutually exclusive.

       -n pmnsfile
              Normally the distributed Performance Metrics Name  Space  (PMNS)
              is  used,  however  if the -n option is specified an alternative
              local PMNS is loaded from the file pmnsfile.

       -s samples
              The argument  samples  defines  the  number  of  samples  to  be
              retrieved and reported.  If samples is 0 or -s is not specified,
              the application will sample and  report  continuously  (in  real
              time  mode)  or  until  the  end  of the PCP archive (in archive
              mode).

       -z     Change the reporting timezone to the local timezone at the  host
              that is the source of the performance metrics, as identified via
              either the -h or -a options.

       -Z timezone
              By default, applications report the time of day according to the
              local  timezone on the system where the application is executed.
              The -Z option changes the timezone to timezone in the format  of
              the environment variable TZ as described in environ(5).

INTERVAL SPECIFICATION AND ALIGNMENT

       Most  PCP tools operate with periodic sampling or reporting, and the -t
       and -A options may be used  to  control  the  duration  of  the  sample
       interval and the alignment of the sample times.

       -t interval
              Set the update or reporting interval.

              The  interval argument is specified as a sequence of one or more
              elements of the form
                        number[units]
              where number is an integer or floating  point  constant  (parsed
              using  strtod(3C))  and  the  optional units is one of: seconds,
              second, secs, sec, s, minutes,  minute,  mins,  min,  m,  hours,
              hour,  h,  days,  day  and  d.   If the unit is empty, second is
              assumed.

              In addition, the upper case (or mixed case) version  of  any  of
              the above is also acceptable.

              Spaces  anywhere  in the interval are ignored, so 4 days 6 hours
              30  minutes,  4day6hour30min,  4d6h30m  and   4d6.5h   are   all
              equivalent.

              Multiple   specifications  are  additive,  e.g.  ``1hour  15mins
              30secs'' is interpreted as 3600+900+30 seconds.

       -A align
              By default samples are not necessarily aligned  on  any  natural
              unit  of  time.   The -A option may be used to force the initial
              sample to be aligned on the boundary of  a  natural  time  unit.
              For  example -A 1sec, -A 30min and -A 1hour specify alignment on
              whole seconds, half and whole hours respectively.

              The align argument follows the syntax for an  interval  argument
              described above for the -t option.

              Note  that  alignment  occurs by advancing the time as required,
              and that -A acts as a modifier to advance both the start of  the
              time  window  (see the next section) and the origin time (if the
              -O option is specified).

TIME WINDOW SPECIFICATION

       Many PCP tools are designed to operate in some time window of interest,
       e.g. to define a termination time for real-time monitoring or to define
       a start and end time within a PCP archive log.

       In the absence of the -O and -A options to specify  an  initial  sample
       time  origin  and  time alignment (see above), the PCP application will
       retrieve the first sample at the start of the time window.

       The following options may be used to specify a time window of interest.

       -S starttime
              By default the time window commences  immediately  in  real-time
              mode, or coincides with time at the start of the PCP archive log
              in archive mode.  The -S option may be used to specify  a  later
              time for the start of the time window.

              The  starttime  parameter  may  be  given  in one of three forms
              (interval is the same as for the -t option as  described  above,
              ctime is described below):

              interval
                     To  specify an offset from the current time (in real-time
                     mode) or the beginning of a PCP archive (in archive mode)
                     simply specify the interval of time as the argument.  For
                     example -S 30min will set the start of the time window to
                     be  exactly  30  minutes  from  now in real-time mode, or
                     exactly 30 minutes from the start of a PCP archive.

              -interval
                     To specify an offset from the end of a PCP  archive  log,
                     prefix  the interval argument with a minus sign.  In this
                     case, the start of the time window precedes the  time  at
                     the end of archive by the given interval.  For example -S
                     -1hour will set the  start  of  the  time  window  to  be
                     exactly  one hour before the time of the last sample in a
                     PCP archive log.

              @ctime To specify the calendar date and time (local time in  the
                     reporting timezone) for the start of the time window, use
                     the ctime(3C) syntax preceded by an at sign.  For example
                     -S '@ Mon Mar 4 13:07:47 1996'

       -T endtime
              By default the end of the time window is unbounded (in real-time
              mode) or aligned with the time at the end of a PCP  archive  log
              (in  archive  mode).   The  -T  option may be used to specify an
              earlier time for the end of the time window.

              The endtime parameter  may  be  given  in  one  of  three  forms
              (interval  is  the same as for the -t option as described above,
              ctime is described below):

              interval
                     To specify an offset from the start of  the  time  window
                     simply  use  the  interval  of time as the argument.  For
                     example -T 2h30m will set the end of the time  window  to
                     be  2  hours  and  30 minutes after the start of the time
                     window.

              -interval
                     To specify an offset back from the time at the end  of  a
                     PCP  archive  log,  prefix  the  interval argument with a
                     minus sign.  For example -T -90m will set the end of  the
                     time  window to be 90 minutes before the time of the last
                     sample in a PCP archive log.

              @ctime To specify the calendar date and time (local time in  the
                     reporting  timezone)  for the end of the time window, use
                     the ctime(3C) syntax preceded by an at sign.  For example
                     -T '@ Mon Mar 4 13:07:47 1996'

       -O origin
              By default samples are fetched from the start of the time window
              (see description of -S option) to the end  of  the  time  window
              (see  description  of  -T  option).   The  -O  option allows the
              specification of an origin within the time window to be used  as
              the  initial sample time.  This is useful for interactive use of
              a PCP tool with the pmtime(1) VCR replay facility.

              The origin argument accepted by -O conforms to the  same  syntax
              and semantics as the starttime argument for the -T option.

              For  example -O -0 specifies that the initial position should be
              at the end of the time window; this is most useful when  wishing
              to replay ``backwards'' within the time window.

       The  ctime  argument  for  the  -O, -S and -T options is based upon the
       calendar date and  time  format  of  ctime(3C),  but  may  be  a  fully
       specified  time  string  like  Mon  Mar  4 13:07:47 1996 or a partially
       specified time like Mar 4 1996, Mar 4, Mar, 13:07:50 or 13:08.

       For any missing low order fields, the default value of 0 is assumed for
       hours,  minutes and seconds, 1 for day of the month and Jan for months.
       Hence, the following are equivalent: -S '@ Mar 1996' and -S  '@  Mar  1
       00:00:00 1996'.

       If  any  high  order fields are missing, they are filled in by starting
       with the year, month and day from the current time (real-time mode)  or
       the  time  at  the  beginning of the PCP archive log (archive mode) and
       advancing the time until it matches the fields that are specified.  So,
       for  example  if  the  time  window  starts  by  default at ``Mon Mar 4
       13:07:47 1996'', then -S @13:10 corresponds to 13:10:00 on Mon  Mar  4,
       1996,  while -S @10:00 corresponds to 10:00:00 on Tue Mar 5, 1996 (note
       this is the following day).

       For greater precision than afforded by ctime(3C), the seconds component
       may be a floating point number.

       Also  the  12  hour clock (am/pm notation) is supported, so for example
       13:07 and 1:07 pm are equivalent.

PERFORMANCE METRICS - NAMES AND IDENTIFIERS

       The number of performance metric names supported by PCP in IRIX  is  of
       the  order  of  a  few  thousand. There are fewer metrics on Linux, but
       still a considerable number.  The PCP libraries and applications use an
       internal  identification  scheme that unambiguously associates a single
       integer with each known performance metric.  This integer is  known  as
       the   Performance   Metric   Identifier,   or  PMID.   Although  not  a
       requirement, PMIDs tend to have global consistency across all  systems,
       so a particular performance metric usually has the same PMID.

       For  all  users and most applications, direct use of the PMIDs would be
       inappropriate (e.g. this would limit the range of  accessible  metrics,
       make  the  code  hard  to  maintain,  force  the  user  interface to be
       particularly baroque, etc.).  Hence a Performance  Metrics  Name  Space
       (PMNS)   is   used   to   provide   external  names  and  a  hierarchic
       classification for performance metrics.  A PMNS  is  represented  as  a
       tree,  with  each  node having a label, a pointer to either a PMID (for
       leaf nodes) or a set of descendent nodes  in  the  PMNS  (for  non-leaf
       nodes).

       A  node label must begin with an alphabetic character, followed by zero
       or more characters drawn from the alphabetics, the digits and character
       `_ยด (underscore).  For alphabetic characters in a node label, upper and
       lower case are distinguished.

       By convention, the name of  a  performance  metric  is  constructed  by
       concatenation  of  the  node labels on a path through the PMNS from the
       root node to a leaf node, with a ``.'' as a separator.  The  root  node
       in  the PMNS is unlabeled, so all names begin with the label associated
       with one of the descendent nodes below the root node of the PMNS,  e.g.
       kernel.percpu.syscall.   Typically (although this is not a requirement)
       there would be at most one name for each PMID in a PMNS.   For  example
       kernel.all.cpu.idle  and  disk.dev.read  are  the  unique names for two
       distinct performance metrics, each with a unique PMID.

       Groups of related PMIDs may be named by naming a non-leaf node  in  the
       PMNS tree, e.g. disk.

       There  may  be  PMIDs  with  no associated name in a PMNS; this is most
       likely to occur when specific PMIDs are not available in  all  systems,
       e.g. if ORACLE is not installed on a system, there is no good reason to
       pollute the PMNS with names for all of the ORACLE performance metrics.

       Note also that there is no requirement for the PMNS to be the  same  on
       all  systems,  however in practice most applications would be developed
       against a stable PMNS that was assumed to be a subset of  the  PMNS  on
       all systems.  Indeed the PCP distribution includes a default local PMNS
       for just this purpose.

       The default local PMNS is located at $PCP_VAR_DIR/pmns/root however the
       environment  variable PMNS_DEFAULT may be set to the full pathname of a
       different PMNS which will then be used as the default local PMNS.

       Most applications do not use the local PMNS, but rather import parts of
       the  PMNS  as required from the same place that performance metrics are
       fetched, i.e. from pmcd(1) for live monitoring or from  a  PCP  archive
       for retrospective monitoring.

       To  explore  the  PMNS  use  pminfo(1),  or  if  the PCP GUI package is
       installed the New Chart and Metric Search windows within pmchart(1).

PERFORMANCE METRIC SPECIFICATIONS

       In configuration files and (to a lesser extent) command  line  options,
       metric specifications adhere to the following syntax rules.

       If the source of performance metrics is real-time from pmcd(1) then the
       accepted syntax is
                 host:metric[instance1,instance2,...]

       If the source of performance metrics is a  PCP  archive  log  then  the
       accepted syntax is
                 archive/metric[instance1,instance2,...]

       The  host:,  archive/ and [instance1,instance2,...]  components are all
       optional.

       The , delimiter in the list of instance names may be replaced by  white
       space.

       Special  characters in instance names may be escaped by surrounding the
       name in double quotes or preceding the character with a backslash.

       White space is ignored everywhere except within a quoted instance name.

       An empty instance is silently ignored, and in particular ``[]'' is  the
       same as no instance, while ``[one,,,two]'' is parsed as specifying just
       the two instances ``one'' and ``two''.

       As a special case, if the host is the single character ``@'' then  this
       refers to a PM_CONTEXT_LOCAL source, see pmNewContext(3).

PMCD AND ARCHIVE VERSIONS

       Since  PCP  version  2,  version  information  has been associated with
       pmcd(1) and PCP archives. The version number is used  in  a  number  of
       ways,  but most noticeably for the distributed pmns(4).  In PCP version
       1, the client applications would load the PMNS from  the  default  PMNS
       file  but  in  PCP  version 2, the client applications extract the PMNS
       information from pmcd(1) or a PCP archive.  Thus in PCP version 2,  the
       version  number  is  used  to  determine if the PMNS to use is from the
       default local file or from the actual current source of the metrics.

PMCD HOSTNAME SPECIFICATION

       Since PCP version  3,  the  pmcd(1)  hostname  specification  has  been
       extended  to  allow  an  optional  pmcd  port number, and also optional
       pmproxy(1) hostname and port number.  These  supercede  (and  override)
       the  old-style  PMCD_PORT,  PMPROXY_HOST  and  PMPROXY_PORT environment
       variables.

       The  following  are  valid   hostname   specifications   that   specify
       connections  to  pmcd  on  host nas1.servers.com with/without a list of
       ports and with/without a pmproxy(1) connection through a firewall.

            $ pcp -h nas1.servers.com:44321,4321@firewall.servers.com:44322
            $ pcp -h nas1.servers.com:44321@firewall.servers.com:44322
            $ pcp -h nas1.servers.com:44321@firewall.servers.com
            $ pcp -h nas1.servers.com@firewall.servers.com
            $ pcp -h nas1.servers.com:44321

ENVIRONMENT

       In addition to the PCP run-time environment and configuration variables
       described   in   the  PCP  ENVIRONMENT  section  below,  the  following
       environment variables apply to all installations.

       PCP_DERIVED_CONFIG
              When set, this variable defines the path to a file that contains
              definitions  of  derived  metrics as per the syntax described in
              pmLoadDerivedConfig(3).  Derived metrics may be used  to  extend
              the  available  metrics  with new (derived) metrics using simple
              arithmetic expressions.

              If PCP_DERIVED_CONFIG is set, the derived metric definitions are
              processed  automatically  as  each  new  source  of  performance
              metrics is established (i.e.  each  time  a  pmNewContext(3)  is
              called) or when requests are made against the PMNS.

       PCP_STDERR
              Many  PCP  tools  support  the  environment variable PCP_STDERR,
              which can be used to control  where  error  messages  are  sent.
              When  unset, the default behavior is that ``usage'' messages and
              option parsing errors are  reported  on  standard  error,  other
              messages   after   initial  startup  are  sent  to  the  default
              destination for the tool, i.e. standard error for  ASCII  tools,
              or a dialog for GUI tools.

              If  PCP_STDERR  is  set  to  the  literal value DISPLAY then all
              messages will be displayed in a dialog.  This is  used  for  any
              tools launched from the a Desktop environment.

              If PCP_STDERR is set to any other value, the value is assumed to
              be a filename, and all messages will be written there.

       PCP_USE_STDERR
              This  environment  variable,  previously  used  by  pmlaunch(5),
              pmgsys(1),  pmview(1)  and the pmview(1) front-end scripts (such
              as mpvis(1)), has been  deprecated  from  the  PCP  2.0  release
              onward and replaced by PCP_STDERR.

       PMCD_CONNECT_TIMEOUT
              When attempting to connect to a remote pmcd(1) on a machine that
              is booting, the connection attempt could potentially block for a
              long  time until the remote machine finishes its initialization.
              Most PCP applications and some of the PCP library routines  will
              abort  and  return  an  error  if  the  connection  has not been
              established after some  specified  interval  has  elapsed.   The
              default  interval is 5 seconds.  This may be modified by setting
              PMCD_CONNECT_TIMEOUT in the environment  to  a  real  number  of
              seconds  for  the desired timeout.  This is most useful in cases
              where the remote host is at the end of a slow network, requiring
              longer latencies to establish the connection correctly.

       PMCD_RECONNECT_TIMEOUT
              When  a  monitor  or  client application loses a connection to a
              pmcd(1), the connection  may  be  re-established  by  calling  a
              service  routine  in  the  PCP  library.   However,  attempts to
              reconnect  are  controlled  by  a  back-off  strategy  to  avoid
              flooding  the  network  with reconnection requests.  By default,
              the back-off delays are  5,  10,  20,  40  and  80  seconds  for
              consecutive  reconnection requests from a client (the last delay
              will be repeated for any  further  attempts  after  the  fifth).
              Setting  the  environment  variable  PMCD_RECONNECT_TIMEOUT to a
              comma separated list of positive  integers  will  re-define  the
              back-off  delays, e.g. setting PMCD_RECONNECT_TIMEOUT to ``1,2''
              will back-off for 1  second,  then  attempt  another  connection
              request every 2 seconds thereafter.

       PMCD_REQUEST_TIMEOUT
              For  monitor  or client applications connected to pmcd(1), there
              is a possibility of the application "hanging" on a  request  for
              performance  metrics or metadata or help text.  These delays may
              become severe if the system running pmcd crashes, or the network
              connection   is  lost.   By  setting  the  environment  variable
              PMCD_REQUEST_TIMEOUT to a number of seconds,  requests  to  pmcd
              will timeout after this number of seconds.  The default behavior
              is to be willing to wait 10 seconds for a  response  from  every
              pmcd for all applications.

       PMCD_WAIT_TIMEOUT
              When  pmcd(1)  is  started from $PCP_RC_DIR/pcp then the primary
              instance of pmlogger(1) will be  started  if  the  configuration
              flag pmlogger is chkconfig'ed on, some key applications from the
              pcp.sw.base subsystem are installed  and  pmcd  is  running  and
              accepting connections.

              The  check on pmcd's readiness will wait up to PMCD_WAIT_TIMEOUT
              seconds.  If pmcd has a long startup time (such  as  on  a  very
              large  system),  then  PMCD_WAIT_TIMEOUT can be set to provide a
              maximum wait longer than the default 60 seconds.

       PMNS_DEFAULT
              If set, then interpreted as the the full pathname to be used  as
              the  default  local PMNS for pmLoadNameSpace(3).  Otherwise, the
              default local PMNS is located at $PCP_VAR_DIR/pcp/pmns/root  for
              base PCP installations.

       PCP_COUNTER_WRAP
              Many  of  the  performance metrics exported from PCP agents have
              the semantics  of  counter  meaning  they  are  expected  to  be
              monotonically  increasing.   Under some circumstances, one value
              of these metrics may smaller than the previously fetched  value.
              This can happen when a counter of finite precision overflows, or
              when the PCP agent has been reset or restarted, or when the  PCP
              agent  is  exporting values from some underlying instrumentation
              that is subject to some asynchronous discontinuity.

              The environment variable PCP_COUNTER_WRAP may be set to indicate
              that  all  such  cases  of  a  decreasing  ``counter'' should be
              treated as a counter overflow, and hence the values are  assumed
              to  have  wrapped  once  in  the  interval  between  consecutive
              samples.  This ``wrapping'' behavior was the default in  earlier
              PCP  versions,  but  by default has been disabled in PCP release
              from version 1.3 on.

       PMDA_PATH
              The PMDA_PATH environment variable may be  used  to  modify  the
              search   path   used   by   pmcd(1)   and  pmNewContext(3)  (for
              PM_CONTEXT_LOCAL contexts) when searching for a  daemon  or  DSO
              PMDA.   The  syntax follows that for PATH in sh(1), i.e. a colon
              separated list of directories, and the default  search  path  is
              ``/var/pcp/lib:/usr/pcp/lib'',   (or   ``/var/lib/pcp/lib''   on
              Linux, depending on the value of  the  $PCP_VAR_DIR  environment
              variable).

       PMCD_PORT
              The  TPC/IP  port(s)  used  by  pmcd(1) to create the socket for
              incoming connections and requests,  was  historically  4321  and
              more  recently  the  officially  registered  port  44321; in the
              current release, both port numbers are  used  by  default  as  a
              transitional  arrangement.   This  may be over-ridden by setting
              PMCD_PORT to a different port number, or a comma-separated  list
              of  port  numbers.   If  a non-default port is used when pmcd is
              started, then every monitoring application  connecting  to  that
              pmcd  must  also  have PMCD_PORT set in their environment before
              attempting a connection.

       The following environment variables are relevant  to  installations  in
       which pmlogger(1), the PCP archive logger, is used.

       PMLOGGER_PORT
              The environment variable PMLOGGER_PORT may be used to change the
              base TCP/IP port number used by pmlogger(1) to create the socket
              to  which  pmlc(1)  instances will try and connect.  The default
              base port number is 4330.  When used,  PMLOGGER_PORT  should  be
              set in the environment before pmlogger is executed.

       PMLOGGER_REQUEST_TIMEOUT
              When   pmlc(1)  connects  to  pmlogger(1),  there  is  a  remote
              possibility of pmlc "hanging" on a request for information as  a
              consequence of a failure of the network or pmlogger.  By setting
              the environment variable PMLOGGER_REQUEST_TIMEOUT to a number of
              seconds,  requests to pmlogger will timeout after this number of
              seconds.  The default behavior is to be willing to wait  forever
              for  a  response  from  each  request to a pmlogger.  When used,
              PMLOGGER_REQUEST_TIMEOUT should be set in the environment before
              pmlc is executed.

       If  you  have the PCP product installed, then the following environment
       variables  are  relevant  to  the  Performance  Metrics  Domain  Agents
       (PMDAs).

       PMDA_LOCAL_PROC
              Use this variable has been deprecated and it is now ignored.  If
              the ``proc'' PMDA is configured as a DSO for use with pmcd(1) on
              the  local  host  then  all  of  the  ``proc''  metrics  will be
              available to applications using a PM_CONTEXT_LOCAL context.

              The previous behaviour was that if this variable was set, then a
              context  established with the type of PM_CONTEXT_LOCAL will have
              access to the ``proc''  PMDA  to  retrieve  performance  metrics
              about individual processes.

       PMDA_LOCAL_SAMPLE
              Use this variable has been deprecated and it is now ignored.  If
              the ``sample'' PMDA is configured as a DSO for use with  pmcd(1)
              on  the  local  host  then all of the ``sample'' metrics will be
              available to applications using a PM_CONTEXT_LOCAL context.

              The previous behaviour was that if this variable was set, then a
              context  established with the type of PM_CONTEXT_LOCAL will have
              access to the ``sample'' PMDA if this  optional  PMDA  has  been
              installed locally.

       PMIECONF_PATH
              If set, pmieconf(1) will form its pmieconf(4) specification (set
              of parameterized pmie(1) rules) using all valid  pmieconf  files
              found  below  each  subdirectory in this colon-separated list of
              subdirectories.     If    not    set,     the     default     is
              $PCP_VAR_DIR/config/pmieconf.

FILES

       /etc/pcp.conf
                 Configuration  file  for  the  PCP  runtime  environment, see
                 pcp.conf(4).
       $PCP_RC_DIR/pcp
                 Script for starting and stopping pmcd(1).
       $PCP_PMCDCONF_PATH
                 Control file for pmcd(1).
       $PCP_PMCDOPTIONS_PATH
                 Command line options passed to pmcd(1)  when  it  is  started
                 from  $PCP_RC_DIR/pcp.   All  the  command  line option lines
                 should start with a hyphen as the first character.  This file
                 can  also  contain  environment variable settings of the form
                 "VARIABLE=value".
       $PCP_BINADM_DIR
                 Location of PCP utilities for collecting and maintaining  PCP
                 archives, PMDA help text, PMNS files etc.
       $PCP_PMDAS_DIR
                 Parent  directory  of  the installation directory for Dynamic
                 Shared Object (DSO) PMDAs.
       $PCP_RUN_DIR/pmcd.pid
                 If pmcd is running,  this  file  contains  an  ascii  decimal
                 representation of its process ID.
       $PCP_LOG_DIR/pmcd
                 Default  location of log files for pmcd(1), current directory
                 for running PMDAs.  Archives  generated  by  pmlogger(1)  are
                 generally below $PCP_LOG_DIR/pmlogger.
       $PCP_LOG_DIR/pmcd/pmcd.log
                 Diagnostic  and  status  log  for the current running pmcd(1)
                 process.  The first place to look  when  there  are  problems
                 associated with pmcd.
       $PCP_LOG_DIR/pmcd/pmcd.log.prev
                 Diagnostic and status log for the previous pmcd(1) instance.
       $PCP_LOG_DIR/NOTICES
                 Log   of  pmcd(1)  and  PMDA  starts,  stops,  additions  and
                 removals.
       $PCP_VAR_DIR/config
                 Contains directories of configuration files for  several  PCP
                 tools.
       $PCP_VAR_DIR/config/pmcd/rc.local
                 Local  script  for controlling PCP boot, shutdown and restart
                 actions.
       $PCP_VAR_DIR/pmns
                 Directory containing the set of PMNS files for all  installed
                 PMDAs.
       $PCP_VAR_DIR/pmns/root
                 The  ASCII pmns(4) exported by pmcd(1) by default.  This PMNS
                 is be the super set of all  other  PMNS  files  installed  in
                 $PCP_VAR_DIR/pmns.
       In  addition,  if  the PCP product is installed the following files and
       directories are relevant.
       $PCP_LOG_DIR/NOTICES
              In addition to the pmcd(1) and PMDA activity, may be used to log
              alarms and notices from pmie(1) via pmpost(1).
       $PCP_PMLOGGERCONTROL_PATH
              Control   file   for   pmlogger(1)   instances   launched   from
              $PCP_RC_DIR/pcp  and/or   managed   by   pmlogger_check(1)   and
              pmlogger_daily(1) as part of a production PCP archive collection
              setup.

PCP ENVIRONMENT

       Environment variables with the prefix PCP_ are used to parameterize the
       file  and  directory names used by PCP.  On each installation, the file
       /etc/pcp.conf contains the  local  values  for  these  variables.   The
       $PCP_CONF  variable may be used to specify an alternative configuration
       file, as described in pcp.conf(4).

SEE ALSO

       pmcd(1),  pmie(1),  pmie_daily(1),  pminfo(1),  pmlc(1),   pmlogger(1),
       pmlogger_daily(1),    pmstat(1),    pmval(1),    pcp(1),   pcp.conf(4),
       pcp.env(4), and pmns(4).

       If the PCP GUI package is installed, then  the  following  entries  are
       also relevant:
       pmchart(1), pmtime(1), and pmdumptext(1).

       Also refer to the books Performance Co-Pilot User's and Administrator's
       Guide and Performance Co-Pilot Programmer's Guide which can be found at
       http://techpubs.sgi.com.