Perfometer README file version 1.2 8/2/02 Kevin London ***************************************************************************** Overview ***************************************************************************** Perfometer is a graphical user interface written in Java that monitors program[s] for performance. There are three parts of perfometer: the perfometer GUI which requires Java 1.2, the server written in C which requires Pthreads and the PAPI library, and the backend of perfometer which is written in C and requires the PAPI library. There is also a light weight version of the GUI written for JAVA 1.0 that runs on handheld devices. Features * Monitors remote applications or local applications. * Returns processor and executable information for the application being monitored. * MPI and multiple process support. * Alarms that pauses the program execution if a pre-specified threshold for the data being monitored is breached. * Different graph styles such as bar, scatter, etc.... * The ability to pause execution or continue execution but stop graphing the results. ***************************************************************************** Installation ***************************************************************************** There are two parts of the installation: Perfometer GUI installation, back-end installation which will install the server and the perfometer library. These topics will be covered separately in this document. **Perfometer GUI installation** ------------------------------- **Requirements** * Java 1.2 or higher (Or Java 1.1 and the swing toolkit) - java.sun.com can be used to download java * Mirco_perfometer which only allows one process to be monitored and lacks many of the features of perfometer, only needs the java provided by handhelds. **Installation** Change directory to the perfGUI directory. Make sure javac is in your path. Edit the Makefile and change the INSTALL_DIR to where you would like the programs installed (Or you can copy things manually). Then type: make This will create two jar files: Perfometer.jar and MicroPerfometer.jar If you changed the INSTALL_DIR type: make install Otherwise copy the Perfometer.jar to where you would like it installed (Or the MicroPerfometer if you are using a handheld). And then the corresponding run script, for Unix/linux you would use run or run_micro and for Windows you would copy run.bat to the installation directory. **Back-end installation** ------------------------- **Requirements for the Server** * Pthreads **Requirements for the Library** * PAPI must be installed * MPI must be installed if MPI support is desired **Installation** Change directories to perfometer If you want don't want MPI support, edit the .inc file that is associated with your platform and remove the mpi from TARGETS. The Makefile has comments on what needs to be changed but the major changes are as follows: PAPI_LIBRARY needs to be changed to where the library file resides. PAPI_INCLUDE needs to be changed to where the PAPI include files reside. MPI_LIBRARY needs to be changed to where MPI libraries reside (if not in a system directory). MPI_INCLUDE needs to be changed to where MPI include files reside (if not in a system directory). Then type: make If this doesn't work, it is possible uname -s isn't getting the correct system. In this case edit the Makefile, uncomment the SYSTEM= and add your system. For example for an SGI machine you would use: SYSTEM=IRIX64 This will make the perfometer library, perfometermpi library (If using MPI support), test programs and the server executable. The library(s), server and include files need to be copied to the directories to be installed. ***************************************************************************** Using Perfometer ***************************************************************************** To monitor an application, the user has to insert calls into the application. The following functions are provided by the perfometer back-end: void perfometer( ); The perfometer call should be inserted whenever the user wants the program to be monitored, this is normally the first call in the program. This function sets up a signal handler, does a handshake with the server (or with the GUI if only one process is running) and then starts sending performance information to the server (or GUI). If you are using MPI, perfometer should be put AFTER the MPI_initialize call. void mark_perfometer( int color, char *label ); Mark_perfometer changes the color that the GUI displays until the next mark_perfometer call is seen. This is a good way to distinguish between different sections in the code by color. The available colorcodes can be found in perfcolorcodes.h. You will need to include that file to use the predefined colors. The label is simply a character string of what you want to call that particular section of code, such as "do_work", etc.... void perfometer_update(); This forces perfometer to grab a sample when this call is seen. This can be good if you are missing mark_perfometer calls because the routines are to short. The problem with this currently is that the GUI expects all the time slices to be uniform, so the data can skew the way the graph should look if too many of these are used. Hopefully, this will be fixed in future releases. void stop_perfometer(); This removes all perfometer instrumentation. This is usually not called in a users code, as this can be called from the GUI or is called if an error crops up. **Monitoring one application** ------------------------------ After the perfometer calls have been inserted into the application and it has been recompiled, you execute the application like normal. It will then print out a port number that the application is listening on. To connect, start the GUI by executuing the script associated with what you are trying to run (run.bat run or run.micro). Then, click on the Connect to Net (or Connect Local if on the same machine) connection button and put in the host and port number that the application is listening on. And choose the Metric that you want to monitor by default. Then click OK. This will start the application running and begin graphing the results. **Monitoring multiple applications or an MPI program** ------------------------------------------------------ First, startup the applications that you wish to monitor. For separate applications, each will provide a port number that it is listening on. For an MPI application, only one port will be provided, the rest will be auto-exchanged. There are then two choices, you can specify the applications on the server command line, or you can specify the applications in the GUI. The server has the following command line syntax: perf_server [-nogui] [-f filename] host port host port ...... * -nogui which will allow the application to be monitored without the GUI. * -f filename will create a tracefile that the GUI can later read and use to graph the results. * Host and port are the host and port number of the application[s] that you want to monitor. After the server is executed, it will print out a port number that it is listening on. Then, the user starts up the GUI and connects to that host and port. If the applications are supplied on the server's command line, then all the connections will be setup and the GUI will begin graphing the performance data from all the applications. If the application is NOT supplied on the supply line, a popup window will appear. The information is then typed into the list, with one host and port per line, such as: somewhere.com 3045 another.com 3045 Then, all the connections will be setup and the GUI will begin graphing the performance data. The only difference between monitoring multiple processes and one, is that you will have several small graphs that you can click on. This will bring that graph to the main window.