NAME

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


SYNOPSIS

       pmlc [-e] [-h host] [-i] [-n pmnsfile] [-P] [-p port]  [-Z
       timezone] [-z] [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  manda­
       tory,  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 Met­
       rics Name Space (PMNS), however if the -n option is speci­
       fied 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 con­
       nection 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 sub­
       sequent connections are made interactively (see  the  con­
       nect 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(5).
       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

       behavior,  and is typically used in conjunction with -e to
       echo all command input on standard output.

       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 spec­
           ified).  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 success­
           fully established, your pmlc will be the only one con­
           trolling the pmlogger instance it is connected to.

       new volume
           This command works only while a connection to a pmlog­
           ger 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 pmlog­
           ger  instance  is  established.  It prints information
           about the state of the pmlogger instance and its asso­
           ciated 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(5)
           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 pmlog­
           ger 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  syn­
           onym for flush.

           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 spec­
       ified as fully qualified names (e.g.  hinv.ncpu)  or  sub­
       trees  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 met­
       rics may be included in such lists.

       Each individual metric specification may be further quali­
       fied  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 qual­
       ification 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  dis­
           played.   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.

           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  met­
           rics/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 subse­
           quent  advisory  logging   requests   for   the   met­
           rics/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 (effec­
           tively 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 log­
           ging state specified for a metric/instance was "manda­
           tory 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  tran­
       sition  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.

       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

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


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 met­
       rics  (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.


CAVEAT

       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  informa­
       tion 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 cur­
       rent  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.


Man(1) output converted with man2html