pmlc(1) — Linux manual page

NAME | SYNOPSIS | DESCRIPTION | COMMANDS | OPTIONS | ACCESS CONTROL | CAVEATS | DIAGNOSTICS | ENVIRONMENT | PCP ENVIRONMENT | SEE ALSO | COLOPHON

PMLC(1)                  General Commands Manual                 PMLC(1)

NAME         top

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

SYNOPSIS         top

       pmlc [-eiPz?]  [-h host] [-n pmnsfile] [-p port] [-Z timezone]
       [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.

COMMANDS         top

       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         top

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

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

ENVIRONMENT         top

       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         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), pmlogdump(1), pmlogger(1), pcp.conf(5),
       pcp.env(5), PMNS(5) and environ(7).

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@groups.io.  This page was obtained from the
       project's upstream Git repository
       ⟨https://github.com/performancecopilot/pcp.git⟩ on 2024-06-14.
       (At that time, the date of the most recent commit that was found
       in the repository was 2024-06-14.)  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)pmlogctl(1)pmlogextract(1)pmlogger(1)pmlogger_check(1)pmlogger_daily(1)pmlogreduce(1)pmsnap(1)__pmconnectlogger(3)__pmcontrollog(3)