NAME | SYNOPSIS | DESCRIPTION | ACCESS CONTROL | PCP ENVIRONMENT | SEE ALSO | DIAGNOSTICS | CAVEAT | COLOPHON

PMLC(1)                    General Commands Manual                   PMLC(1)

NAME         top

       pmlc  -  configure  active  Performance Co-Pilot pmlogger(s) interac‐
       tively

SYNOPSIS         top

       pmlc [-e] [-h host] [-i] [-n pmnsfile] [-P] [-p port] [-Z timezone]
       [-z] [pid]

DESCRIPTION         top

       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.

       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.

       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.

ACCESS CONTROL         top

       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 │
            │log advisory ...  │ advisory                              │
            │log mandatory ... │ mandatory                             │
            │new volume        mandatory                             │
            └──────────────────┴───────────────────────────────────────┘

PCP ENVIRONMENT         top

       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         top

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

DIAGNOSTICS         top

       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         top

       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.

COLOPHON         top

       This page is part of the PCP (Performance Co-Pilot) project.
       Information about the project can be found at ⟨http://www.pcp.io/⟩.
       If you have a bug report for this manual page, send it to
       pcp@oss.sgi.com.  This page was obtained from the project's upstream
       Git repository ⟨git://git.pcp.io/pcp⟩ on 2017-05-03.  If you discover
       any rendering problems in this HTML version of the page, or you
       believe there is a better or more up-to-date source for the page, or
       you have corrections or improvements to the information in this
       COLOPHON (which is not part of the original manual page), send a mail
       to man-pages@man7.org

Performance Co-Pilot                 PCP                             PMLC(1)

Pages that refer to this page: pcpintro(1)pmlogextract(1)pmlogger(1)pmlogger_check(1)pmlogreduce(1)pmnewlog(1)pmsnap(1)pmconnectlogger(3)pmcontrollog(3)