pGraph 2.0 - DOCUMENTATION UPDATE IN PROGRESS

Hello! I am still updating the pGraph documentation with new 2.0 version. Please keep checking this page or send me a mail (vagnini@it.ibm.com) if you have specific questions.

DOWNLOAD >>>>>>   Latest pgraph version is: pGraph.jar v2.0(Java 1.5 or later is required).

Performance Graph Viewer - pGraph Java tool

pGraph is a Java program designed to read multiple performance data formats and to produce graphs either interactively or in batch mode. There is no limit on input data size and user can view graphs related to the entire time frame or can select a specific time period. No installation is required, just a JRE 1.5 or later.

pGraph major features:

• support for multiple data formats (nmon, vmstat, topasout, iostat, lslparutil, sar)
• multiple operating systems (AIX, Linux, Solaris, HP-UX)
• no limit in performance data file
• data file can be in GZIP format (highly recommended to save space)
• can read multiple files at a time
• automatic merge of data files belonging to same operating system
• load of files belonging to multiple operating systems to show global processor usage
• zoom feature to show data related to a user defined time period
• graphs can be exported in PNG format
• applet version for easy web publishing
• simple capacity planning feature
  

Supported data formats

pGraph can be easily adapted to read the output of many performance tools, if they provide a time stamp to data samples. The following table show the current formats supported:

pGraph natively reads the text file produced by the commands or a compressed copy in GZIP format with a ".gz" extension. The data file can have any name and pGraph will automatically detect the file format and load the data. There is no limit in file size or in the number of samples present in the data.  

 Single and multiple file load

The following features are available:

• Load from single file

• Load from a directory: single host, multiple files
• Load from a directory: multiple hosts, multiple files
• Complex load using a configuration file

When a single file is selected, pGraph automatically detects its type and parses it. When the file is completely loaded, a set of graphs are made available, depending on the file content (for example, iostat does not provide CPU data).

The same performance tool can be run several times (for example, an nmon running every day for 24 hours) on the same operating system and the administrator may need to study all the outputs. pGraph is capable of automatically merge the content of files and treat them as a single input stream, just put all files in the same directory and load them with the single host, multiple files option. There is no requirement on file names since pGraph will use time stamps inside the files to correctly merge data. This feature does not apply to vmstat and iostat files that provide only time and not date: in this case cancatenate the files in the right order and load the result.

When an administrator collects data from several operating systems it may become very useful to compare how they are working in the same time period. pGraph can extract CPU data from each file, align in time all samples, show graphs related to each operating system and provide additional graphs that show the sum of all workloads. When nmon is used and all operating system are hosted in the same partitioned system, global processor pool statistics are also available. To obtain this view, put all files into the same directory and load it with the multiple hosts, multiple files option.

Sometimes administrator has complex analysis to made involving many files (maybe hundreds of them) with multiple views to made. In order to provide a very flexible file load schema, administrator can use a configuration file to program how pGraph loads files. A configuration file can use a mix of files and directories, select a specific time frame to show and even apply multipliers to CPU consumption to make simple capacity planning. The syntax is very simple:

 pGraph execution

 pGraph only requires a Java virtual machine (JRE or JDK) version 1.5 or later. It can be run either in interactive mode, in batch mode or in applet mode.

Interactive mode 

 If your operating system has associated the "jar" extension with a JVM you can just use the GUI and double click on the pGraph.jar file to launch the program. If you prefer command line (you still need a graphic environment), the  syntax to run the tool is (case sentitive):

java -cp pGraph.jar pGraph.Viewer [input file]

If you do not provide an input file on the command line, the pGraph GUI will start with an empty workspace waiting for your input file:

Use the Help menu to acces to the tool's Console with all error messages or to the About panel that provides the version of the tool you are using.

The File menu is used to select the file or the directory to be loaded. A separate window will appear allowing you to navigate inside your local filesystem. Once you select the data source, the tool will shon on the lower part of the GUI the status of file loading up to completion of data parsing. pGraph will first scan the file to detect its format and to identify the time range contained into the file(s). During this period of time you will see a bar moving back and forth. Once pGraph identifies the source type, it will start parsing the data and you will see a progress bar showing the percentage of lines read. If multiple files are read (either after the selection of a directory or a configuration file), the progress bar show the percentage of single file read.

If you have provided an input file with the command line, it will be loaded immediately as if you selected File -> Load single file.

When parsing is complete, the GUI is updated showing the time frame contained in the file(s) read and a set of buttons. Each button can be pressed to create a new window containing performance graphs. The number and types of buttons depend on the source file(s) type. Pressing a button may cause the creation of an empty window: in this case no data in the file was present that could be used to create the required graphs. If errors occur during graph creation, a console window will pop up providing some hints on the error cause: try to check the source file for errors or report the bug sending a mail to vagnini@it.ibm.com with the description of what you made and, possibly, a GZIP version of source file(s).

When a single nmon file is loaded, the GUI looks similar to the following:

 All graphs will be always related to the time frame shown in the GUI. If you need to focus on a restricted time window, perform a Zoom operation and pGraph will re-read the data source and update all graphs.

Batch Mode 

The tool can be used in batch mode to create PNG pictures of all available performance variables (the same PNG of interactive mode) with an HTML wrapping that can be used to publish them on a web site.

Due to Java limitations, a graphical adapter or a virtual frame buffer is required.

The syntax is:

    pGraph.Viewer - Version 2.0
    Interactive Usage: pGraph.Viewer [file]
    Batch Usage:       pGraph.Viewer [ -l begin end ] [ -d | -D ] <source> <output dir>
            -l limits time frame: begin and end in YYYYMMDDhhmmss format.
            -d source=directory : multiple hosts in multiple source files.
            -D source=directory : single host with multiple source files.
            <source> is by default a file. Use -d or -D to select a directory.
                    Valid input files are: "nmon", "vmstat -t",
                    "topasout <xmtrend file>", "topasout <topas_cec>",
                    "iostat -alDT", "lslparutil"
            <output dir> is where system usage reports in PNG format are written.

   java -cp pGraph.jar pGraph.Viewer myServer.nmon report 

Applet Mode 

If you have an HTTP server that provides access to performance files, you can use pGraph's applet version to allow users to download the files and interactively analyze then as if they were on the local filesystem. The applet provides the same GUI and the same functionalities as in the interactive version, but it will have access only to the files you define in applet configuration. The pGraph.jar file is signed using a self-signed certificate: if the user accepts the certificate, the applet will be apble to run correctly and to produce PNG pictures of performance graphs on the user's local filesystem.

The pGraph.jar package contains the pGraph.ViewerApplet class that can be used in the HTTP server. It will show by default on the web page as a button with a Start label. If you want another label, it can be customized. When the button is pressed, the applet will create the GUI and start downloading from the server all the performance files associated. Since network is used, it is highly recommended to store performance files compressed in GZIP format with a ".gz" file extension.

The applet accepts three possible parameters:

• FILES                  a comma separated list of files on the web server that will be read by the Viewer. The path is either relative to the jar location or a full URL
• SINGLE_HOST      true or false value
• LABEL                 label to be printed inside the applet in the web page. The default is Start

FILES parameter must be used otherwise the applet will be empty with no chance of loading any file. The Viewer will immediately load the provided files from the web.

If FILES containes a single file, tha applet will show its content. If FILES contains multiple files, they will be treated as belonging to multiple servers and only CPU data will be shown (like in multiple hosts, multiple files), except when SINGLE_HOST is set to true value. The SINGLE_HOST parameter should be used when multiple files belonging to the same operating system are provided and must be merged by the applet.

Examples of usage: single nmon compressed with GZIP, three nmon files to be merged:

    <applet
        code="pGraph/ViewerApplet.class"
        archive="pGraph-1.5.3-alpha.jar"
        width=80 height=30
        files="files/nmon.gz">
    </applet>
    <applet
        code="pGraph/ViewerApplet.class"
        archive="pGraph-1.5.3-alpha.jar"
        width=80 height=30
        files="mfsh/nmon1,mfsh/nmon2,mfsh/nmon3"
        single_host="true"
        label="mfsh">
    </applet>

Zoom Operation 

 aaaaaaa from Major GUI, from graphs

Graph window components

 wwwwww

This tool is not officially supported by IBM. No warrantee is given or implied, and you cannot obtain help from IBM. It a personal project of the author, Federico Vagnini (vagnini@it.ibm.com). Any comment and suggestion is really appreciated. |