pmlaunch(5)
pmlaunch - metric specification and scripts for launching other tools
As shipped in IRIX 6.5.30. Last changed in IRIX 6.5.30.
This page could not be fully tidied (pagination-warning, no-header); it is shown as printed.
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 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. 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). 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: 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. 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. $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 ALSO PCPIntro(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 variable).