Man Linux: Main Page and Category List

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

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

       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.

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

       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  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.

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  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.