Provided by: pcp_6.0.3-1_amd64 bug

NAME

       pmlc - configure active Performance Co-Pilot pmlogger(s) interactively

SYNOPSIS

       pmlc [-eiPz?]  [-h host] [-n pmnsfile] [-p port] [-Z timezone] [pid]

DESCRIPTION

       pmlc  may  be  used  to change those metrics and instances which a pmlogger(1) writes to a
       Performance Co-Pilot archive (see PCPIntro(1)), the frequency with which the  metrics  are
       collected  and whether the logging is mandatory, advisory, on or off.  It also reports the
       current logging status of metrics and instances.  pmlc may be  used  to  control  pmlogger
       instances on remote hosts as well as those on the local host.

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

       If the -P option is specified, pmlc will attempt to start with a connection to the primary
       pmlogger  on  the  local  host.   If the -p option is specified, then pmlc will attempt to
       start with a connection to the pmlogger on this TCP/IP port.   Alternatively,  if  pid  is
       specified, a connection to the pmlogger instance with that process id will be attempted on
       startup.  The -h option may only be used if -P, -p port or a pid is  also  specified.   In
       that  case pmlc will initially connect to the specified (remote) pmlogger instance on host
       rather than the local host.  If the connection to the specified pmlogger  instance  cannot
       be  established,  pmlc  will  start with no connection.  These options typically allow the
       same file of pmlc commands to be directed to multiple pmlogger instances  by  varying  the
       command  line  arguments.   Note that -P, -p port, pid and -h are used only when making an
       initial connection to a pmlogger instance.  They are not used as  defaults  if  subsequent
       connections are made interactively (see the connect command below).

       By  default,  pmlc  reports  the time of day according to the local timezone on the system
       where pmlc is run.  The -Z option changes the timezone to timezone in the  format  of  the
       environment variable TZ as described in environ(7).  The -z option changes the timezone to
       the timezone of the pmlogger instance from which information is being obtained.  Only  one
       of -z or -Z may be specified.

       If  standard  input  is from a tty, pmlc is interactive, with prompts.  The -i flag may be
       used to force interactive behavior, and is typically used in conjunction with -e  to  echo
       all command input on standard output.

COMMANDS

       The following commands may be used:

       show [ loggers ] [ @host ]
           Displays  the  process  identities of all pmlogger instances running on the local host
           (or host, if specified).  The primary pmlogger pid is parenthesized because it can  be
           referred to as "primary" as well as by its pid.

       connect pid [ @host ]
       connect primary [ @host ]
           Connects  pmlc  to  the  specified  pmlogger  process.   Any  existing connection to a
           pmlogger instance is closed first.  Each pmlogger instance will  accept  at  most  one
           connection at a time, so if the connection is successfully established, your pmlc will
           be the only one controlling the pmlogger instance it is connected to.

       new volume
           This command works only while a connection to a pmlogger instance is established.   It
           tells  the  pmlogger  to  close  the  current volume of the log and open a new volume.
           Closed volumes may be archived, e.g. as part of a regular log management procedure  to
           control the size of the physical log files.

       status
           This  command works only while a connection to a pmlogger instance is established.  It
           prints information about the state of the pmlogger instance and its associated log.

       timezone local | logger | "timezone"
           This command sets the time zone used when times are printed.  local means use the time
           zone  of  the  machine that pmlc is running on.  logger means use the time zone of the
           machine where the pmlogger instance is running.  Alternatively  an  explicit  timezone
           enclosed  in  quotes  may  be  supplied  (refer to TZ in environ(7) for details).  The
           default time zone is local unless one of the -z or -Z options has been supplied on the
           command line.

       flush
           This  command works only while a connection to a pmlogger instance is established, and
           requests the pmlogger instance to flush  to  disk  all  buffers  associated  with  the
           current archive.  For old-timers, sync is a synonym for flush.  In current versions of
           pmlogger(1) all writes are unbuffered and aligned with  the  logical  records  in  the
           external  files,  so  this  command  achieves  nothing,  but is retained for backwards
           compatibility.

       disconnect
           Disconnect pmlc from the current pmlogger instance, if any.

       sleep delay
           Pause pmlc for delay milliseconds.  This may be helpful in scripted uses  of  pmlc  to
           allow  the  current  pmlogger  instance  to  make  progress  on recent requests before
           interrogating the status.

       help
           Displays a summary of the available commands.
           h and ? are synonyms for help.

       quit
           Exits from pmlc.

       The remaining commands query and change the logging state of metrics and instances.   They
       will  work only if pmlc has a connection to a pmlogger instance.  Metrics may be specified
       as fully qualified names (e.g. hinv.ncpu) or subtrees of the PMNS (e.g.  hinv)  which  are
       expanded  to  include  all  metrics  in the subtree (e.g. hinv.ncpu, hinv.cpuclock, etc.).
       Lists of metrics may be specified by enclosing them in  braces  with  spaces  or  a  comma
       between  metrics  (e.g.  {hinv.ncpu  hinv.ndisk}).  Subtrees of metrics may be included in
       such lists.

       Each individual metric specification may be  further  qualified  with  a  space  or  comma
       separated  list  of  instances  in  square  brackets  (e.g. kernel.all.load["1 minute", "5
       minute"]).  External instance names or numeric internal instance identifiers or  both  may
       be   used   in   the  same  list  (e.g.  sample.colour.[red,1,"blue"]).   If  an  instance
       qualification is applied to a subtree of the PMNS all of the metrics in the  subtree  must
       have the same instance domain.  Instance qualifications may not be applied to entire lists
       of metrics but may appear inside such lists.

       If no instances are specified for a metric, all instances are used.  All  instances  means
       all  instances available at the time the pmlogger instance in question fetches the metrics
       for logging.  If an instance domain changes over time this is not always the same  as  the
       set  of  instances  displayed  by  pmlc,  which  can  only display the currently available
       instances.  To prevent  unintentional  errors,  only  the  instances  that  are  currently
       available to pmlc may appear in instance specifications.

       query metriclist
           The  current  logging  state  of  each  metric  (and  instances,  where applicable) in
           metriclist is displayed.  This includes the logging state (e.g. on,  maybe,  off)  and
           the  logging  interval  for  each  metric  (and  instance)  requested.   The following
           abbreviations pertaining to metrics (and instances) may appear  in  the  output:  adv,
           advisory;  mand,  mandatory;  nl,  not  in  the  log; na, in the log but not currently
           available from its Performance Metrics Domain Agent  (PMDA).   Where  appropriate,  an
           instance  name  will  appear  last on a line preceded by its numeric internal instance
           identifier.

       [ log ] mandatory on interval metriclist
           This form of the log command turns on logging for the metrics (and any  instances)  in
           metriclist.   interval  specifies  how often the specified metrics/instances should be
           logged.  once indicates that the metrics/instances should appear at most once  in  the
           log.   More  often  one  would  use  the optional keyword every followed by a positive
           number and one of millisecond (or msec), second (or sec), minute  (or  min),  hour  or
           their plurals.
           Note  that  the  keyword  default  which  may  be  used  for the default interval in a
           pmlogger(1) configuration file cannot be used in pmlc.
           Internal limitations require the interval to be less than  (approximately)  74  hours.
           An interval value of zero is a synonym for once.

       [ log ] mandatory off metriclist
           This  tells  the  pmlogger  instance  not  to  log  any  of  the  metrics/instances in
           metriclist.

       [ log ] mandatory maybe metriclist
           This tells the pmlogger instance to honor any subsequent advisory logging requests for
           the   metrics/instances   in   metriclist.   If  the  current  logging  state  of  the
           metrics/instances is mandatory (either on or off) the new state will be set  to  maybe
           (effectively  advisory off).  If the current state of the metrics/instances is already
           advisory (either on or off) the state(s) for the metrics/instances will remain as they
           are.

       [ log ] advisory on interval metriclist
       [ log ] advisory off metriclist
           Advisory  logging  is  only  applicable  if  the  last  logging  state specified for a
           metric/instance was "mandatory  maybe"  (which  permits  subsequent  advisory  logging
           control)  or  if  the  logging  state  is already advisory.  These two statements turn
           advisory logging on or off (respectively) for the specified metrics/instances.
           The interpretation for interval is as above for the mandatory case.

       There is no continuation character required for commands that span lines.

       The word at may be used interchangeably with @.

       A request to log all instances of a metric will supersede any prior request to log  either
       all  or  specific instances of a metric (if the request specifies a permissible transition
       in the logging state).  A request to log specific instances of a metric when all instances
       of a metric are already being logged is refused by pmlogger.

OPTIONS

       The available command line options are:

       -e, --echo
            Echo all command input on standard output.

       -h host, --host=host
            Connect pmlogger on host, rather than on the default localhost.

       -i, --interactive
            Force interactive behavior.

       -n pmnsfile, --namespace=pmnsfile
            Load an alternative Performance Metrics Name Space (PMNS(5)) from the file pmnsfile.

       -p port, --port=port
            Connect to the primary pmlogger on TCP/IP port port.

       -P, --primary
            Connect to the primary pmlogger.

       -z, --logzone
            Use local time of the pmlogger as the reporting timezone.

       -Z timezone, --timezone=timezone
            Use  timezone  for  the  date and time.  Timezone is in the format of the environment
            variable TZ as described in environ(7).

       -?, --help
            Display usage message and exit.

ACCESS CONTROL

       pmlc may have restricted access to and control over pmlogger(1) processes.

       If a pmlogger(1) is unable to export its control information to the  local  pmcd(1),  then
       that  pmlogger(1) cannot cannot be connected to nor controlled by pmlc.  In practice, this
       means the pmlogger(1) process has to be  owned  by  the  user  ``pcp''  and/or  the  group
       ``pcp''.   If  pmlogger(1)  is  running  on  the  host ``foo'' then use ``pminfo -f -h foo
       pmcd.pmlogger''  to  verify  that  the  pmlogger(1)  of  interest  is  known  to  pmcd(1),
       alternatively  pmlogger(1) instances that are not reported from the pmlc show loggers @foo
       command are not known to pmcd(1) on the host ``foo''.

       If pmlogger(1) is launched with a configuration file that contains  an  [access]  section,
       then  pmlc  will be unable to connect to that pmlogger(1) unless the access controls allow
       some access from the host where pmlc is being run.  Minimally this  requires  the  enquire
       access to be permitted in the pmlogger(1) access control section.

       If  pmlc  is  able  to  connect  to  the pmlogger(1) of interest, then the following table
       summarizes the permissions needed to perform different pmlc commands:

                      ┌──────────────────┬───────────────────────────────────────┐
                      │  pmlc command    │       Required pmlogger access        │
                      ├──────────────────┼───────────────────────────────────────┤
                      │show loggers      │ Any                                   │
                      │connect           │ Any of enquire, advisory or mandatory │
                      │status            │ Any of enquire, advisory or mandatory │
                      │query ...         │ Any of enquire, advisory or mandatory │
                      │disconnect        │ Any                                   │
                      │log advisory ...  │ advisory                              │
                      │log mandatory ... │ mandatory                             │
                      │new volumemandatory                             │
                      └──────────────────┴───────────────────────────────────────┘

CAVEATS

       If all instances of a metric are being logged and  a  request  is  made  to  log  specific
       instances  of  the  metric  with  the  same state and frequency, the request may appear to
       succeed, even though pmlogger has refused the request.  This is not normally a problem, as
       the required information will still be placed into the log by pmlogger.

       However  in  the case where the metric is to be logged once, the outcome is not what might
       be expected.  When pmlogger receives a request to log a metric once, it places the current
       value(s) of the metric into the log as soon as it can, regardless of whether the metric is
       already in the log.  This may be used to force values into the log.  When a request to log
       specific  instances of a metric arrives and is refused because all instances of the metric
       are already being logged, pmlogger does not place values for the instances requested  into
       the  log.   It returns the current logging state for each instance requested to pmlc.  The
       requested and returned states are identical, so pmlc doesn't raise an error as it should.

       To ensure that only certain instances of a metric are being logged, one should always turn
       off  logging  for all instances of the metric prior to turning on logging for the specific
       instances required.

DIAGNOSTICS

       Most error or warning messages are self-explanatory.  A message of the form
               Warning: unable to change logging state for...
       followed by a list of metrics (and possibly instances) indicates that pmlogger refused the
       request  for  the  metrics  (and instances) that appear.  Any metrics (and instances) that
       were specified but do not appear in the message  have  had  their  logging  state  updated
       successfully  (no  news  is  good  news).   Usually  this  warning results from requesting
       advisory logging when a mandatory control is already in place, or requesting  logging  for
       specific instances when all instances are already being logged.

ENVIRONMENT

       If  the  PMLOGGER_REQUEST_TIMEOUT environment variable is not set or set to 0 (zero), then
       pmlc will block until a connection is established with pmlogger(1) on the requested  port.
       If  PMLOGGER_REQUEST_TIMEOUT is set to a value greater than zero, then pmlc will fail with
       an error after that many seconds if a connection isn't established.  This may be  used  by
       administrative  scripts  such  as  pmlogger_daily(1)  to poll pmlogger when is starting up
       until it is ready and listening on it's control port.

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(5).

SEE ALSO

       PCPIntro(1),  pmcd(1),  pmdumplog(1),  pmlogger(1),  pcp.conf(5),  pcp.env(5), PMNS(5) and
       environ(7).