# pmlc

## NAME



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


## SYNOPSIS



           **pmlc**[**-eiPz?**]  [**-D** _debug_] [**-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 volume** │ **mandatory** │
             └───────────────────┴───────────────────────────────────────┘
    


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


## DEBUGGING OPTIONS



           The **-D** or **--debug** option enables the output of additional
           diagnostics on _stderr_ to help triage problems, although the
           information is sometimes cryptic and primarily intended to provide
           guidance for developers rather end-users.  _debug_ is a comma
           separated list of debugging options; use pmdbg(1) with the **-l**
           option to obtain a list of the available debugging options and
           their meaning.
    
           Debugging options specific to **pmlc** are as follows:
           ┌────────┬───────────────────────────────────────────────────────┐
           │ **Option** │ **Description** │
           ├────────┼───────────────────────────────────────────────────────┤
           │ **appl0** │ dump metrics and instances received                   │
           ├────────┼───────────────────────────────────────────────────────┤
           │ **appl1** │ dump state after each command is parsed               │
           └────────┴───────────────────────────────────────────────────────┘
    


* * *