SGI Techpubs Library

Linux  »  Man Pages
find in page



PMLAUNCH(5)                                                        PMLAUNCH(5)

NAME
       pmlaunch - 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 associ-
       ated with, Performance Co-Pilot (PCP).

       A script for the target tool parses the metrics specification and  gen-
       erates  command  line options and/or configuration files for the appro-
       priate metrics.  For example, pmview(1) will use the same metrics spec-
       ification  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 specifica-
       tion 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  direc-
       tory   specified   in   the  environment  variable  PM_LAUNCH_PATH,  or
       $PCP_VAR_DIR/config/pmlaunch if it is not set.

       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  argu-
       ment 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 for-
       mat, and the shell procedures that are provided for extracting the rel-
       evant information to build a launching script for any tool.

METRICS SPECIFICATION FORMAT
       The metrics specification which is generated by the launching tool con-
       tains 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  associ-
              ated 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).

       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 PCPIn-
              tro(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 associ-
              ated 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 config-
       urable. 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:

          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 visual-
       ized.  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''  indicat-
       ing  either  a host or an archive. The host or archive should be speci-
       fied 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 val-
       ues 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.

       The  metric  dimensions and internal instance domain identifier (indom)
       are described in PMAPI(3).  The dimension consists of three space-sepa-
       rated signed integer values representing Space, Time, and Count respec-
       tively.

       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 met-
       rics 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 com-
                 mand line arguments and configuration files from  a  pmlaunch
                 metrics specification.

       $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 sec-
       tion 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 ALSO
       PCPIntro(1), pmchart(1), pmdbg(1), pmgadgets(1), pmgsys(1), pmsocks(1),
       pmval(1), pmview(1), pmconfirm(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-explana-
       tory.  These messages will be displayed in an  pmconfirm(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 vari-
       able).

Performance Co-Pilot                  SGI                          PMLAUNCH(5)

Output converted with man2html


home/search | what's new | help