AIMS(1)
NAME
AIMS - Automated Instrumentation and Monitoring System
DESCRIPTION
AIMS provides users of multi-processor parallel computers
and workstation networks with a suite of tools for monitor-
ing and analyzing the performance of their parallel applica-
tions. Native application source code (in either C or For-
tran) is passed through an instrumentor (see xinstrument(1)
and batch_inst(1)) which inserts ``instrumentation'' (or
monitoring code) around certain (user-selectable) con-
structs. This instrumented code is then linked with the
AIMS monitor libraries. When the instrumented application
is run, the monitor routines produce a trace of the execu-
tion. This trace can then be sorted (see tracesort(1)) and
passed to the analysis tools provided with AIMS. These tools
include VK(1) (an execution-trace animator), tally(1) (for
tabulation of performance data), and pc(1) (for perturbance
compensation).
GETTING STARTED QUICKLY
This section will show the first-time user how to quickly
instrument and view the performance of an application. To
learn about the full range of capabilites of AIMS, see The
AIMS Reference Manual.
Before actually instrumenting an application, the user
should become familiar with two data structures generated by
AIMS. The ``application database'' is used for storing
information about the static structure of an application's
source code. The analysis tools use this information to
relate traced events to instrumented constructs in the
source code. The instrumentation programs (see
batch_inst(1) and xinstrument(1)) build the application
database and write it to a file, which is subsequently
incorporated by AIMS into the trace file produced by execut-
ing an instrumented application program. Another important
data structure in AIMS is the ``instrument enabling pro-
file.'' This is a table of flags, one for each instrumented
construct in the application database. The profile can be
used either by the instrumentor to select the constructs to
be instrumented or by the monitor to select the instrumented
constructs to be traced. Only those constructs whose flag is
true in the profile will be instrumented/traced (see
MONITOR(5)).
AIMS supports two types of instrumentor interfaces: a batch
version and an interactive version. The batch version is
used by the interactive version and is not recommended for
the casual user. In both instances, instrumentation
proceeds in two basic phases: the extraction phase, where
the program structure is extracted from source files and
written out to the application database; and the instrumen-
tation phase, where the source code is annotated. In the
batch version of our instrumentors, there is no visible
separation between these phases; certain instrumentable con-
structs (see below) are instrumented by default. In the
interactive version, users are given an opportunity between
the phases to use the information about the structure of
their applications to interactively select the source-code
constructs to be instrumented.
The instrumented source files have the same names as their
respective originals; they are written into a different
directory. ./inst is the default pathname used by our
instrumentors. Here is an example of running the batch
instrumentor:
batch_inst -platform f77-pvm xpose_node.f xpose1.f
By default, all communication and syncronization calls, and
none of the user constructs (e.g. routines, loops) are
instrumented. To instrument all of the instrumentable con-
structs in the source, the following line could be used:
batch_inst -platform f77-pvm -enable all xpose_node.f
For information about the interactive instrumentor, refer to
the documentation for xinstrument(1).
Before compiling the instrumented code, the user must copy
any support files (e.g. include files, make files) into the
directory containing the instrumented code. Also, if any
modules were not instrumented (note that you must instrument
the modules containing the main procedures), these must also
be copied into the instrumented directory. Finally, modify
the makefile (in the instrumented directory) so that it
links the AIMS monitor libraries with the application exe-
cutables. Ask the system administrator for the location of
these libraries; their names are nodelib.a and hostlib.a.
Before running the program, you may need to modify the moni-
tor profile (named AIMS.monrc) created by the instrumentor.
This file specifies how large a buffer the monitor should
use, where the trace file should go, whether you have a host
program, as well as several other options. Refer to the AIMS
reference manual or MONITOR(5) for details. The example
shipped with AIMS provides the following AIMS.monrc file:
# Output for trace data
TRACE_FILE: TRACE.OUT
# application database
APPL_DB_FILE: APPL_DB
# Output for statistical trace data
STAT_FILE: TRACE.OUT.STAT
# Amount of data to save before flushing
BUFFER_SIZE: 262144
# 0 - Use the SRM's file system.
# 1 - Use the Concurrent File System
FILE_MODE: 1
# 0 - Don't flush when the buffer fills up.
# 1- Flush when the record buffer fills up.
FLUSH_MODE: 1
# 0 - Running hostless
# 1 - Running with a host program
HOST_PROGRAM: 0
# Define trace level, 0 for no trace
TRACE_LEVEL: 4
# Define statistical trace level, 0 for no statistics
STAT_LEVEL: 0
# 1 - Do tracesort, 0 - Don't perform tracesort
TRACE_SORT: 1
The AIMS.monrc profile must be in the same directory from
which you run your application. After running the applica-
tion, obtain the trace file and sort it using tracesprt(1).
You can now view the trace file with VK(1) or obtain perfor-
mance statistics using the tally(1) program.
An important note: AIMS currently does not monitor the full
PVM or MPI constructs.
USAGE OUTLINE
1) Instrument code using either the interactive instrumentor
(cref. xinstrument(1)) or the batch instrumentor
(cref. batch_inst(1)).
2) Copy support files into the instrumented directory.
3) Modify the makefile so that the AIMS monitor libraries
are linked with the final executable.
4) Modify the monitor profile (AIMS.monrc).
5) Run the application.
6) Sort the resulting trace file if necessary.
7) Analyze the sorted trace file using AIMS' analysis tools
FILES
/usr/lib/X11/app-defaults/Aims
SEE ALSO
batch_inst(1), xinstrument(1), tracesort(1), VK(1),
tally(1), pc(1), MONITOR(3), MONITOR(5)
The AIMS Reference Manual
AIMS Release 3.7 Last change: 2 July 1997