Next: , Previous: Getstats Internals, Up: Top

8 Graphing with Graphit

Graphit is a Perl script that generates both line and bar graphs using Gnuplot 3.8j or higher. Graphit automatically processes Getstats output, results files (by executing Getstats), and CSV files. Each input file is treated as a series, and has several components. To properly read this section, you should use the Postscript viewer (or HTML), as info may not correctly display images.

In a bar graph, each series creates a group of bars. In fig:bargraph, the series are Ext2, Ext3, and Reiserfs. Each component becomes a bar in each series. In fig:bargraph, the components are Elapsed, System, and User.


Figure 8.1: A bar graph with three series (Ext2, Ext3, and Reiserfs) and three components (Elapsed, System, and User).

In a line graph, a line is created for the cross product of the series and components. In fig:linegraph, there are two components and series. The components are Elapsed and System, and the series are Ext3 and Reiserfs. Of special note is that this line graph actually has more points than the corresponding bar graph even though it has fewer series and components. This is because each series-component combination in a line graph can have any number of points (in this case six), but a series-component combination only has a single point in a bar graph. Another important distinction between line and bar graphs is that bar graphs use an artificial x-axis, but a line graph uses an x-axis based on an actual quantity (for example, the number of threads).


Figure 8.2: A line graph with two components (Elapsed and System) and two series (Ext3 and Reiserfs). Each series-component combination has six points.

Graphit has three required options as follows:

--mode bar|line
Whether a bar or line graph should be produced.
--components name(,name)*
What components should be graphed. If the input file has other components, then they are ignored.
--graphfile file
What the name of the output graph file is. This also indirectly determines the format of the output.

After the options, Graphit takes an even number of arguments, which are pairs that define the graph's series. The first element of the pair is the series name (e.g., Ext2). The second element is the input that defines the series. The input specification is parser specific.

To create a bar graph using Getstats output the input specification is a file name. The file can either be a the output from a single run of Getstats (the tabular report, without the warnings), or an Auto-pilot results file. If an Auto-pilot results file is specified, then Getstats is executed using the command getstats --set warn=0 file, to create a corresponding tabular report.

When you specify the output of Getstats, Auto-pilot only handles files that contain a single result. To handle files with more than one result, then you must use the syntax file@index, where file is the name of the file and index is the name of the sample within the file. For example in the following file named summary:

Elapsed 10    8.168  8.154  8.131  8.205  8.112  8.271  0.633  0.453
System  10    0.140  0.135  0.119  0.161  0.100  0.190  20.757 14.849
User    10    0.021  0.020  0.011  0.031  0      0.040  65.253 46.680
Wait    10    8.007  7.987  7.967  8.047  7.957  8.131  0.697  0.498
CPU%    10    1.971  1.786  1.669  2.272  1.466  2.690  21.413 15.318

Elapsed 10    16.155 16.142 16.129 16.182 16.131 16.252 0.229  0.164  97.780
System  10    0.292  0.280  0.238  0.346  0.170  0.430  25.770 18.435 108.571
User    10    0.029  0.030  0.019  0.039  0.010  0.050  47.252 33.803 38.095
Wait    10    15.834 15.846 15.779 15.890 15.709 15.936 0.489  0.350  97.747
CPU%    10    1.987  1.891  1.644  2.330  1.301  2.905  24.142 17.271 0.820

There are two possible index values: samples/ext2:1.res and samples/ext2:2.res. To specify the first set, you would use summary@samples/ext2:1.res. Correspondingly the second set is summary@samples/ext2:2.res.

To create a line graph using Getstats output the input specification is a set of files using a shell globbing pattern. By default, the files' common prefix and suffix are removed to determine the x-axis position for a given file. For example, ext2:1.res and ext2:2.res have a common prefix of ext2: and a common suffix of .res, therefore ext2:1.res is located at 1 on the x-axis and ext2:2.res is located at position 2 on the x-axis. You must specify the globbing pattern, not the files on the Graphit command line, so it must be quoted (e.g., graphit [options] Ext2 'ext2:*.res'), so that the shell does not expand the glob. Sometimes the common prefix is too large. For example, test:100.res and test:1000.res have a common prefix of test:100, and a common prefix of .res. In these cases you must manually specify the prefix and suffix. To pass arguments to a parser use the --Xparser option. For example, graphit [options] --Xparser='--prefix=test:' --Xparser='--suffix=.res' Test 'test:*.res'. If you specify incorrect --Xparser options, the parsers do not issue warnings or errors, because each parser has access to all parser options, and the valid options are different for different parsers.

To specify files with multiple results, the syntax is similar to bar graphs, but you can use file globs both for the summary and index. If an index is used, then the index is computed before globbing is applied. Therefore, * matches all files, but no indexes. The pattern *@*, matches all files and all indexes.

A single CSV files can represent multiple series and components. For a bar graph, the columns are the components, and each row (line) is a series. The input specification is a single CSV file, but the series specification is special: it is a regular expression that matches the x-value in the CSV file. For bar graphs, each x-value becomes a set of bars. For example, if you have a CSV file with the x-value column "Filesystem", you use the regular expression Ext. to graph only Ext2 and Ext3. If not all components in the CSV file are being graphed, it is not clear what the x-value should be (if all of the other components are being graphed, the only remaining one is used as an x-value). To specify the column for the x-value, use the --xcol parser argument as follows graphit [options] --Xparser='--xcol=Column'.

For a line graph, the CSV uses a normal series specification (not a regular expression), and the input specification is a single file. Each column is a component (or used to determine the x-value). If all columns except one are used for the components, then the remaining column is automatically selected for the x-value. The --xcol parser option is used to select the column for the x-value, which must be numeric. Each row represents a single position along the x-axis.