1, Before using Jumpshot, you need to know where the SLOG file is. typically they have the file extention, slog. The SLOG file should be generated by "utemerge". If you would like to see the statistics of the job, you also need a "tsv" file. "utestat". For further details, read ibm_doc/ute.man on how to generate the SLOG and tsv files in UTE environment. 2, To use Jumpshot, one needs to install the jumpshot first. To install jumpshot, one need to compile slog_api's java API slog_api.jar, and the actual GUI code, preview.jar and jumpshot.jar. ---- In order to build Jumpshot, we need to build three jar files. The simplest way is to cd to directory GUI. Update GUI_HOME and SLOG_HOME in file GUI/Make.conf."OSname" to reflect where these 2 directories are located. And type make. On SGI, one might need to do a gmake. If everything goes well, there should be 3 jar files generated in GUI/bin. Check if slog_api.jar, preview.jar and jumpshot.jar in GUI/bin are all updated. If things do NOT go well. One may need to build individual jar files separately. One is the SLOG-API's java interface and actual GUI codes. slog_api/src-java/slog.jar which are built from sources in slog_api/src-java, GUI/bin/preview.jar which are built from sources in GUI/src/GraphicPreview, and GUI/bin/jumpshot.jar which are built from sources in GUI/src/main. So one needs to cd to the slog_api/src-java and build slog.jar by typing "make". one may need to to set all the JAVA related environmental variable(s) so javac and jar are defined in your PATH before typing make. slog.jar does NOT depend on Swing. Once slog.jar is built, one can proceed to build jumpshot.jar by cd'ing to the top level directory GUI ( i.e. cd ../../GUI ). Edit Make.conf."OSname" to define JAVA_HOME where JAVA resides. On AIX, JAVA_HOME should be set to point to /usr/jdk_base. Also be sure the "java -fullversion" return a build data later than or equal to "JDK 1.1.6 IBM build a116-19990115 (JIT enabled: jitc)" Note: ignore the warning messages during compilation of jumpshot.jar. 3, There are 2 ways to run jumpshot. a, using the supplied script in GUI/bin: If you have followed the instruction to build the 2 jar files, cd to GUI/bin and run Jumpshot by entering "jumpshot slog_filename", e.g. /homes/chan/jumpshot/GUI/bin> jumpshot ../logfiles/merge.slog b, run jumpshot directly using "java" Set the CLASSPATH in your local shell to where slog.jar, jumpshot.jar and swing.jar, GraphicPlotter and UTEStatsViewer are located. And you can invoke the jumpshot as "java jumpshot slog_filename frame_number". For further details, Read ~GUI/README.slog 4, When Jumsphot is running, you will first see a small window titled "Jumpshot". The following is extracted from the GUI/bin/jumpshot.help ------------------------------------------------------------------------------ *************** Jumpshot Window *************** The first main window shows up when "jumpshot" is executed In the top window menu bar, there are 4 pull-down menus. They are FILE, DISPLAY, SYSTEM and HELP menus. FILE New Frame - Open a new Jumpshot Window Select Logfile - Opens up a window that allows you to select a logfile to view. Exit - Quit Jumpshot DISPLAY Select type of display jumpshot should show. Currenyly, only the Time Lines display is usable. Mountain display has been disabled. SYSTEM - Select look and feel of choice. Certain look and feel may not be supported by the JVM that you are using. - Enable or disable tool tips. Tool tips are small descriptions that become visible when user places mouse over some region like a button, window, etc. HELP Manual - Opens a window containing this document About - Gives a short description of Jumpshot Also there are LOGFILE panel and Read button. LOGFILE Contains name of loaded logfile READ Read in the logfile for processin ------------------------------------------------------------------------------ 5, Click the FILE pull down menu to select the file. Once the file is selected by double clicking on filename or clicking the OPEN button. The "View & Frame Selector" window will pop up. Again extract from the GUI/bin/jumpshot.help ------------------------------------------------------------------------------ **************************** View & Frame Selector Window **************************** After the READ button in the Jumpshot window has been pressed, the window titled "View & Frame Selector" will show up. In this window, you have a Graphical Frame Preview Selector which has two pull-down menus, FILE and GRAPH. The Graphical Preview contains a simple graph of event count versus the duration of the whole logfile. Read the description of various options in GUI/src/GraphicPreview/README File View Statistics - Open the UTE statistics viewer Close - Close the View & Frame Window Graph Type - Graphical preview's display type Bar - ( default ), cummulative Histograms Line - curves Rescale - rescaling of Y-axis On - automatic rescaling of y-axis Off - retains the current scale of the y-axis Data Sets All - display all data sets None - clears all data sets in the graph Zoom In - magnify the view around selected view point Out - demagnify the view around selected view point Reset - reset the magnification to the orginal scale Legend Display - display the legend for each data set. Hide - hide the Legend dialog box In the Graphical Preview, there is a Red Line which marks the middle of the frame to be displayed and also marks the view point to be used as a reference point during zoom in and out. In this window, there are 2 sets of radio buttons to define the properties of the frame to be displayed. One is titled as "Connectivity Options" which currently only allow "Disconnected States", and the other one is titled as "View Options" which currently allows 3 possible views - Application View, Thread View and Processor View. Application View: MPI rank ID is used as Y axis label in the displayed frame later. Thread View : MPI rank ID and logic thread ID, i.e. local thread ID, are used as the Y axis label in the displayed frame. Currently the 2 integers are encoded as one in the Y axis label through the equation : thread_Y_label = rank_ID * 1000 + logic_thread_ID. Processor View : Node ID and local cpu ID are used as the Y axis label in the displayed frame. Currently the 2 integers are encoded as one in the Y axis label through the equation: processor_Y_label = node_ID * 1000 + local_CPU_ID. Below these, there are buttons and textfield that allow user to manuelly select frame to display. It is particularly important when the number of the pixels in the Graphical Preview is less than the number of frames available in the logfile. In this case, the frame buttons are used to fine tune the frame of logfile that user wishes to view. The PREVIOUS frame button decrements the frame index. The NEXT frame button increments the frame index. The only way to display a frame is to click on the display button. Then a Time Line Window with the properties selected will pop up Also the textfield next to "Current frame =" under the Frame Information panel allows one to directly type in a frame index to view. The Red Line Marker in the Graphical Preview and the Frame Buttons will be updated according. The frame index should be between 0 and ( Number of frames - 1 ). The only way to display a frame is to click on the display button. Then a Time Line Window with the properties selected will pop up. The "View Statistics" option in under the FILE pull-down menu will invoke the statistical viewer to process the *.tsv file. Read the ~/ibm_doc/README.viewstat for further detail. ------------------------------------------------------------------------------ 6, After the display button is clicked, the display button turns dark grey. This indicates that the code is working to convert the raw data into a displayable graphical format. It takes about 30 seconds for a Time Lines Window to pop up. There are many operations allowed in the Time Lines Windows. Here is the extract from the GUI/bin/jumpshot.help ------------------------------------------------------------------------------ ***************** Time Lines Window ***************** Zoom Operations: --------------- IN, OUT - These buttons are used to zoom in and out horizontally Zooming out of the frame __before__ zooming in will produce unreasonable result. RESET - Reset the time range of the displayed frame to the default range. Miscellaneous Operations: ------------------------ PRINT - Clicking on this button will bring up the 'Print Dialog' window where you will be able to choose printer-related options, and print display of this window. It is NOT working yet. OPTIONS - Clicking on this button will bring up the 'Options' window Hidden Operations: ----------------- Y-axis LABEL - Double Clicking on label will bring up 'Adjust Process' window. SCROLL BAR - Use to move forward or backward in time. Usually, one scrolls by dragging the scroll bar by clicking on the empty space in the direction where one wants scroll bar to move to. Clicking on the arrows in the scroll bar will only move scroll bar 1 pixel at a time. KEYBOARD KEYS Z or z - Set the center of the Zoom operation. Lock Zoom at point where mouse is positioned T or t - Set a time marker at point where mouse is positioned MOUSE BUTTON - Clicking of any mouse button on a specific state instance on display will bring up 'State Info' Window which displays information on that state instance. Clicking on this window will dispose it. - Clicking of any mouse button on the circle at origin of a message will open up a window containing information on that message. Clicking on this window will dispose it. ************** Options Window ************** LINE DISPLAY - Turn off/on zoom lock line and elapsed time line. These are vertical lines that you see in Display Window. DISPLAY OPTIONS - Add/Cut time lines or mountain ranges to/from display window Again Mountains range is NOT usable. ZOOM & TIME - Zoom Factor: Length of display is multiplied by this value when you zoom in. Lenght of display is divided by this value when you zoom out. From and To are starting and ending times in viewport respectively. To change these values edit and press enter. NESTING - Nest Factor: Measure of difference between heights of successive nested levels. Larger the value larger the difference. To change value edit and press enter. DO OPTIMAL NESTING: Calculates most appropriate nest factor and implements it. ********************* Adjust Process Window ********************* This window contains options used to manipulate processes. SCROLLBAR - This scrollbar is used to move current process forward and backward in time. FORWARD/BACKWARD - This button is used to determine direction in which current process is to be moved RESET - This causes the process to take up its original position in time. DISPLAY - This checkbox controls display status of selected process. A process can be selected from 'AVAILABLE' list. SWAP - This causes selected process to be swapped with current process. DELETE - Selected process is deleted. Deleted process is removed from 'AVAILABLE' list and placed in 'DELETED' list. INSERT - Causes selected process from 'DELETED' list to be placed just above selected process from 'AVAILABLE' list. ***************** State Definitions ***************** Intially below Display Window, process states region contains buttons for each state and messages. This region can be attached to any of the 4 sides of Display Window. It can also be torn away from Display Window and made to form its own window. ALL STATES ON - Turn on all possible states ALL STATES OFF - Turn off all possible states [State] - Clicking on button for any state will show histogram window for that state. checkbox - Use this to enable/disable this state's display. ********************** state histogram Window ********************** This window contains information on associated state. The histogram given is the plot of number of state instances (y-axis) versus duration in seconds (x-axis). ------------------------------------------------------------------------------ 7, One can have several Time Lines windows displayed simultaneously as long as the JVM has enough memory. This feature allows one to compare the different frame with identical views or identical frame with different views. 8, For further details of code, read the READMEs in the slog_api, slog_api/src, GUI, GUI/src, GUI/src/GraphicPreview and GUI/src/main.