plucky (1) pmlc.1.gz

Provided by: pcp_6.3.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 archive and open a new volume.   Closed  volumes  may  be
           compressed  and/or  moved  to  a remote system, remote storage or off-line storage, e.g. as part of a
           regular archive management procedure to control the size of the physical archive files on the  system
           where pmlogger is running.

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

       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 logged (not in the archive); na, in
           the  archive  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 archive.  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 archive 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 archive 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 archive 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 archive 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 archive a metric once, it places the current value(s) of the metric
       into the archive as soon as it can, regardless of whether the metric is already in the archive.  This may
       be  used  to  force  values  into  the archive.  When a request to archive 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 archive.  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), pmlogdump(1), pmlogger(1), pcp.conf(5), pcp.env(5), PMNS(5) and environ(7).