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