NAMEpmlaunch - metric specification and scripts for launching other tools
SYNOPSIS
$PCP_VAR_DIR/config/pmlaunch/pmlaunch.common
$PCP_VAR_DIR/config/pmlaunch/pmlaunchrc
$HOME/.pcp/pmlaunch/pmlaunchrc
DESCRIPTION
This page describes a metrics specification format and a set of scripts
that can be used by tools to facilitate launching, and being launched by,
other tools which have no knowledge of each other.
The intended use is for performance tools that are part of, or associated
with, Performance Co-Pilot (PCP).
A script for the target tool parses the metrics specification and
generates command line options and/or configuration files for the
appropriate metrics. For example, pmview(1) will use the same metrics
specification when launching tools such as pmchart(1), pmgsys(1) etc.,
without any knowledge of how these tools will visualize those metrics.
LAUNCH MENUS
The launch menu of tools which support the pmlaunch metrics specification
can be configured to include any selection of IRIX, PCP or other tools.
The launching tool will search $PCP_VAR_DIR/config/pmlaunch/pmlaunchrc
and $HOME/.pcp/pmlaunch/pmlaunchrc for a list of tools that can be
launched. The first line of the file specifies the version of pmlaunch
that this file conforms to. The following lines should contain the menu
button name followed by the path to a launching script or program,
including any arguments.
For example, the default $PCP_VAR_DIR/config/pmlaunch/pmlaunchrc will
contain:
pmlaunch Version 2.0
dkvis _pmview_frontend dkvis
mpvis _pmview_frontend mpvis
nfsvis _pmview_frontend nfsvis
pmchart _pmchart
pmgsys _pmgadgets_frontend pmgsys
pmkstat _pmkstat
pmval _pmval
Empty lines and lines which begin with a ``#'' are ignored.
Menu items with identical names in the second pmlaunchrc file will
replace the corresponding entries in the first file.
The launching tool will search for the launching script in the directory
specified in the environment variable PM_LAUNCH_PATH, or
$PCP_VAR_DIR/config/pmlaunch if it is not set.
Page 1
1
PMLAUNCH(5)PMLAUNCH(5)
For example, the launch menu of pmview(1) will contain the entries dkvis,
mpvis, nfsvis, pmchart, pmgsys, pmkstat and pmval. If a user selects
nfsvis, the script _pmview_frontend is executed with the argument nfsvis.
$PCP_VAR_DIR/config/pmlaunch/pmlaunchrc is automatically updated by PCP
products as new tools become available using the script
$PCP_VAR_DIR/config/pmlaunch/mk.rc.
The remainder of this man page describes the metrics specification
format, and the shell procedures that are provided for extracting the
relevant information to build a launching script for any tool.
METRICS SPECIFICATION FORMAT
The metrics specification which is generated by the launching tool
contains the minimal information required to display information related
to the source, domain, color, visual and value semantics, scale and
groupings of a collection of performance metrics.
To manage later configuration file revisions, the first line of the
configuration file should be
pmlaunch Version 2.0
All empty lines, or lines beginning with a ``#'' are ignored. A newline
character separates each statement.
To permit tools to convey update intervals, and other PCP specific
information, a set of options may be specified with the syntax:
option variable=string
Any variables that are specified are converted to shell variables by the
shell procedure launch_var. The following variables are commonly used
between PCP tools, and should have values that may be used in the
corresponding command line argument. An option without a value is
equivalent to not setting the variable.
debug The current debugging flag used by the launching tool which is
passed to the target tool as a command line option. Therefore,
valid values should be a combination of flags identified by
pmdbg(1). Usually associated with a -D option to PCP tools.
namespace
The PCP namespace used by the launching tool. Usually associated
with a -n option to PCP tools.
timeport
The identification of the port used for the time controls (see
pmtime(1)). Usually associated with a -p option to PCP tools that
use pmtime(1).
Page 2
PMLAUNCH(5)PMLAUNCH(5)
starttime
The starting time of the application in the currently fetched
contexts. In most cases, this will be the current time on the
host/s in live mode, or in the archive/s. See PCPIntro(1) for a
description of time formats. Usually associated with a -S option
to PCP tools.
endtime
The finishing time of the application. This is normally only used
with archives. See PCPIntro(1) for a description of time formats.
Usually associated with a -T option to PCP tools.
offset The starting time as an offset from the starttime. See
PCPIntro(1) for a description of time formats. Usually associated
with a -O option to PCP tools.
interval
The update interval of the launching application in seconds.
Usually associated with a -t option to PCP tools.
progname
The name of the launching tool.
pid The process ID of the launching tool.
selected
The metrics are based on a selection in the launching tool if this
is set to true.
timezone
The timezone currently in use by the launching tool.
defsourcetype
The type of the default metrics source in use by the launching
tool (either h or a).
defsourcename
The name of the default metrics source in use by the launching
tool (i.e. the name of a host or an archive). Usually associated
with either the -a or -h options to PCP tools.
The launching scripts for a particular application have the option to use
or ignore these variables as required.
The target PCP and IRIX tools may be static or dynamically configurable.
Therefore, a reasonable amount of information about each metric is
required in the metrics specification so that all possible launching
scripts can extract what they require. A metric specification must be of
this format:
Page 3
PMLAUNCH(5)PMLAUNCH(5)
metric metric_id group_id group_hint context source host_info
name color_spec type semantics scale dimension indom [instance]
The metric_id uniquely identifies the metric within the configuration
file, so an error is generated if another metric has the same number.
Ideally, the metric's internal PMID should be used, but is not required
(see PCPIntro(1)).
Metrics with the same group_id should, where possible, be visualized
together. The group_hint gives a hint as to how they should be
visualized. Hints which could be given include:
none Indicates that there is no appropriate hint.
point Each metric has its own plot. For example, a line in pmchart(1).
stack The metrics are stacked in a bar plot.
util The metrics are stacked in a utilization plot which is always
scaled to 100%.
The metric context may have one of two values, ``h'' or ``a'' indicating
either a host or an archive. The host or archive should be specified in
the source. The host_info for an archive should be the target host of
the archive. The host_info for a host should indicate with the value
true that the host must be reached using pmsocks(1).
The name contains the name of the metric, not including any sources or
instances.
The color_spec is used to describe not only the color of the metric, but
also any scaling that was applied. A color_spec must be of one of the
following formats:
S color,scale
D color,maximum,color,maximum...
A color_spec prefixed with a ``S'' is a static color definition which
contains only one color and scale. This should be used to describe a
metric which has a fixed color, regardless of its value. A color_spec
with a dynamic color scale is prefixed with a ``D'' character, and will
change to the next color in the list when the maximum value is exceeded.
The colors may be specified by name or with the X(1) rgbi tuple of three
normalized floats.
The metric type and semantics fields have single numeric values which
respectively map to the PM_TYPE and PM_SEM definitions in
/usr/include/pcp/pmapi.h. The scale field comprises three numeric values
for each of Space, Time, and Count. These fields are extensions to the
pmlaunch version 1.0 format (the current version is 2.0). Refer to
PMAPI(3) for detailed descriptions of each of the possible values for
these fields.
Page 4
PMLAUNCH(5)PMLAUNCH(5)
The metric dimensions and internal instance domain identifier (indom) are
described in PMAPI(3). The dimension consists of three space-separated
signed integer values representing Space, Time, and Count respectively.
The indom is a single integer. A metric which does not have an instance
domain should specify an instance domain of ``-''.
The last field in a metric specification is an instance. As the instance
may contain most characters, including spaces, the instance must be
enclosed in square brackets. If a metric does not have an instance, then
the instance should simply be ``[]''. Only one instance may be
specified, so multiple instances must be listed as separate metrics on
subsequent lines in the metrics specification file.
EXAMPLE CONFIGURATION FILE
The following text is an example of the possible output generated by
mpvis(1):
pmlaunch Version 2.0
metric 0 0 point h omen false kernel.percpu.cpu.idle S rgbi:0.000000/0.782569/0.000000,1000.000000 1 1 0 2 0 0 1 0 4194305 [cpu0]
metric 1 0 point h omen false kernel.percpu.cpu.wait.total S rgbi:0.000000/0.782569/0.779279,1000.000000 1 1 0 2 0 0 1 0 4194305 [cpu0]
metric 2 0 point h omen false kernel.percpu.cpu.intr S rgbi:0.750547/0.782569/0.000000,1000.000000 1 1 0 2 0 0 1 0 4194305 [cpu0]
metric 3 0 point h omen false kernel.percpu.cpu.sys S rgbi:0.750547/0.000000/0.000000,1000.000000 1 1 0 2 0 0 1 0 4194305 [cpu0]
metric 4 0 point h omen false kernel.percpu.cpu.user S rgbi:0.000000/0.000000/0.779279,1000.000000 1 1 0 2 0 0 1 0 4194305 [cpu0]
option interval=2
option debug=0
option timeport=/tmp/pmview.a002ct
option starttime=@Wed Dec 11 10:14:46 1996
option offset=@Wed Dec 11 10:14:51 1996
option timezone=EST-11EST-10,91/2:00,301/2:00
option progname=pmview
option pid=10809
option selected=false
FILES
$PCP_VAR_DIR/config/pmlaunch
Directory containing the default scripts and configuration
files for launching tools.
$PCP_VAR_DIR/config/pmlaunch/pmlaunchrc
List of menu items and the corresponding scripts for the
launching tools.
$PCP_VAR_DIR/config/pmlaunch/pmlaunch.common
Common shell procedures that can be used for generating command
line arguments and configuration files from a pmlaunch metrics
specification.
Page 5
PMLAUNCH(5)PMLAUNCH(5)
$PCP_VAR_DIR/config/pmlaunch/mk.rc
Script which builds the pmlaunchrc file from the component
*.menu files (during install).
$PCP_VAR_DIR/config/pmlaunch/*.menu
Generic menu specification files which are combined to form the
default pmlaunchrc file (during install).
$HOME/.pcp/pmlaunch/pmlaunchrc
User configurable list of menu items and the corresponding
scripts for the launching tools. These items may override those
specified in $PCP_VAR_DIR/config/pmlaunch/pmlaunchrc.
ENVIRONMENT
The PCP_STDERR environment variable described in the DIAGNOSTICS section
below is fully documented in the PCPIntro(1) manual page.
Additional trace and debugging information from the scripts that
``launch'' one PCP application from another may be gained as follows:
1. All trace and debug diagnostic information is added to the end of the
file named in the environment variable PMLAUNCH_FILE (or ${TMPDIR-
/var/tmp}/pmlaunch.trace by default).
2. If the environment variable PMLAUNCH_TRACE is set, then summary
information is produced for each ``launch'' operation.
3. If the environment variable PMLAUNCH_DUMP is set, then the contents
of various temporary files used in each ``launch'' operation are
reported.
The launching of a tool can be prevented by setting PMLAUNCH_CHECK in the
environment.
SEE ALSOPCPIntro(1), pmchart(1), pmdbg(1), pmgadgets(1), pmgsys(1), pmsocks(1),
pmval(1), pmview(1), xconfirm(1) and PMAPI(3).
BUGS
Future versions may allow a hierarchical representation of groups, so
that groups could contain other groups.
csh(1) aliases in the user's environment are ignored by most launch
scripts which determine the path to the target executable using the sh(1)
type command.
DIAGNOSTICS
Error messages produced by any pmlaunch scripts should be self-
explanatory. These messages will be displayed in an xconfirm(1) window
if DISPLAY is set and PCP_STDERR is set to ``DISPLAY'' in the environment
(refer to PMAPI(3) for a detailed explanation of this environment
Page 6
PMLAUNCH(5)PMLAUNCH(5)
variable).
Page 7
