# SystemTap Graphing

## Getting Started

### Introduction

TWhen a SystemTap script is launched under a Run Configuration with the Graph the output of this script run option enabled, it is possible to plot its output in graph form. (If you are unfamiliar with how to load or write a SystemTap script, please review the IDE Tutorial in the SystemTap IDE User's Guide.) A variety of graph types are available for plotting the output of Systemtap scripts:

- Scatter Graph
- Line Graph
- Area Graph
- Bar Graph
- Pie Graph

These graph types can be instantiated as soon as a script is run by creating them in a script's Run Configuration, or after a script run has been initiated by using the Create Graph wizard in the Graph Selector View. Please refer to Lesson 3: Running Your Script for information on how to use Run Configurations and regular expressions to capture data from a script's output, and how to plot that data in graphs.

### Graphing Tutorial

This tutorial picks up from where Lesson 3: Running Your Script left off, and provides more information on graph configuration. If you followed that tutorial already, click Run As -> Run Configurations... and view the configuration you created earlier. If not, follow that tutorial now, and return here when you have finished.

Once the Run Configuration menu is opened with your configuration selected, click on the Graphing tab. At the bottom of the window, a section labelled Graph Set # displays a list of all graphs created for the currently-selected Regular Expression (the # in "Graph Set #" indicates which expression is chosen). There is also a set of buttons related to graph configuration:

- Add... - Brings up the Create Graph wizard to allow you to create a new graph.
- Duplicate - When one of the graphs in the list of entries is selected (by clicking on it), this button creates a duplicate of that graph.
- Edit... - When one of the graphs in the list of entries is selected, this button allows you to edit the settings of that graph with the Edit Graph wizard.
- Remove - Removes the currently selected graph.

Note: Each regular expression you create has its own Graph Set. When creating & editing graphs, the only graphs that will be visible in the Graph Set # section will be the graphs used for the expression currently selected in the Regular Expression combo box.

#### Create Graph Wizard

The Create Graph (or Edit Graph Wizard is used when creating a new graph or editing an existing one. It allows you to set all properties of a graph, such as its title, graph type, and series data.

- Graph Type - The type of graph to draw. See Graph Types for the list of graph types available, and an explanation of each.
- Title - The title the graph will have when displayed in the Graph Selector View.
- X Series - The class of data that will provide the graph's X series data. This data can come from one of the capturing groups of your regular expression (which appear as their user-defined titles), or, if set to Row Num, the graph will plot a new data point for every line/row of output that is matched by your regular expression.
- Y Series 0 - The class of data that will provide the graph's Y series data, relative to the X axis. A capturing group from your regular expression must be used for this.
- Y Series 1, 2, 3... - If you have included more than one capturing group in your regular expression, you may choose to provide your graph with multiple Y series data, each of which will be plotted relative to the same X series axis you specified earlier. They will appear as a seperate set of data points on your graph, labelled by title. When you do not want to include any extra Y series values, choose NA.

Note that two different series may not share the same data selection.

## Concepts

### Data Table

The Data Table is a view that is always available when running a script with the chart option. It intitially starts empty and populates as it recieves information parsed from the console originally from the script. The Data Table is a visualization of the data structure that every other graph type spawns from.

The columns of the Data Table can be resized at will by dragging the seperation lines between column headers. In addition, the information in the data table can be saved and loaded without having to re-run the script. Furthermore, the user can populate the Data Table without having to run a script if a script's output has been saved into a file, see Opening Script Output.Right clicking the Data Table provides a menu with the following options:

- Format as... - Depending on which column the user right clicked, this allows the user to format that column's data as one of the following:
  - Unformated - No formating is applied.
  - String
  - Date
  - Double
  - Hex
  - Octal
  - Binary
- Add Filter... - Adds a filter to the Data Table.
- Remove Filter... - Removes a filter from the Data Table.
- Manually Resize - Allows the user to resize column width without bouncing back to the minimum based on the largest value.

### Data Graph Types

Currently there are five graph types built into SystemTap Plug-in.

These graph types can be used instantiated by using the Create Graph wizard once the Data Table is populated. The Graphing Perspective can support multiple graphs from one Data Table. Each are updated and can be viewed by navigating through the tabs shown at the top of each Graph Set while in the Graph Selector View.

#### Scatter Graph

A Scatter Graph uses Cartesian coordinates to show the relation of two or more quantitative variables.

Creating a Scatter Graph will prompt the user for three values. The first is the title and is fully cosmetic. The option to turn on and off the title is given to the user, and its off by default. The second option is X Series; here you select which series of data you want to plot along the X Axis. The third option is the Y Series; here you select which series of data you want to plot along the Y Axis. Optionally you can add extra Y Series; here you select another series of data you want to plot along the Y Axis.

#### Line Graph

The Line Graph is traditionally ideal for horozontally depicting non-cumulative data over, say, time.

Creating a Line Graph will prompt the user for three values. The first is the title and is fully cosmetic. The option to turn on and off the title is given to the user, and its off by default. The second option is X Series; here you select which series of data you want to plot along the X Axis. The third option is the Y Series; here you select which series of data you want to plot along the Y Axis. Optionally you can add extra Y Series; here you select another series of data you want to plot along the Y Axis.

#### Area Graph

The Area Graph is traditionally ideal for horozontally depicting non-cumulative data over, say, time.

Creating an Area Graph will prompt the user for three values. The first is the title and is fully cosmetic. The option to turn on and off the title is given to the user, and its off by default. The second option is X Series; here you select which series of data you want to plot along the X Axis. The third option is the Y Series; here you select which series of data you want to plot along the Y Axis. Optionally you can add extra Y Series; here you select another series of data you want to plot along the Y Axis.

#### Bar Graph

The Bar Graph typically uses bars to show frequencies or values.

Creating a Bar Graph will prompt the user for three values. The first is the title and is fully cosmetic. The option to turn on and off the title is given to the user, and its off by default. The second option is X Series; here you select which series of data you want to plot along the X Axis. The third option is the Y Series; here you select which series of data you want to plot along the Y Axis. Optionally you can add extra Y Series; here you select another series of data you want to plot along the Y Axis.

#### Pie Graph

The Pie Graph uses a pie to show percentages.

Creating a Pie Graph will prompt the user for three values. The first is the title and is fully cosmetic. The option to turn on and off the title is given to the user, and its off by default. The second option is X Series; here you select the series to be used as labels of each area of the pie chart. The third option is the Y Series; here you select which series of data will be used to calculate the percentages of each area of the pie chart. Optionally you can add extra Y Series, each of which will draw another Pie containing that series' data.

### Filters

Filters are screens that you can set on your Data Table to limit the quantity of samples you wish to work with. Filters are very often used in restricting the sheer amount of information available to make data tables and graphs more substantial to people.

The following options exist to work with Filters in the Data Table:

- Add Filter... - Adds a Filter to the Data Table.
- Remove Filter... - Removes a Filter from the Data Table.

When you select Add Filter you see the following dialogue box:

What follows is a breakdown of each Filter type:

- Match Filter - This filter removes everything from the data set where the selected column's

value does not match the chosen value.

Result:

- Range Filter - This filter removes everything from the data set that is not included in the

selected range of values.

Result:

- Sort Filter - This filter will sort the data set based on the selected column. No data will be

removed.

Result:

- Unique Filter - This filter will remove all merge all entries in that data set that share a common

value in the selected column. Data for the removed rows will be aggregated together based on the chosen aggregation method.

- - Average Aggregate - This aggregate will return the average of all the items consolidated.
  - Count Aggregate - This aggregate will return the number of items consolidated.
  - Max Aggregate - This aggregate will return the maximum value of all the items consolidated.
  - Min Aggregate - This aggregate will return the minimum value of all the items consolidated.
  - Sum Aggregate - This aggregate will return the sum of all the items consolidated.

### Graph Interaction

Each of the Graph Types have similar options that can be used in the Graphical Perspective:

- Zoom Bar - The graph types that use axes (Scatter, Line, Area, and Bar graphs) support this control. This enables the user to reduce the number of X-axis values that are plotted on the graph, to effectively zoom in and out on the graph's display. Sliding the bar left reduces the range of the X-axis that is plotted (zoom in), and sliding right increases it (zoom out).

Use Preferences to configure other graph settings, such as grid lines and viewable data items.

## Reference

This section of the Graphing User Guide is intended to provide the following resources should you have any very specific questions regarding the graphing in general or one of the options associated with it. It also contains example scripts and FAQs.

### Frequently Asked Questions

This section details frequently asked questions relating to graphing script output.

Can I make more than one graph at one time? Do they update concurrently?

A: Yes and yes. In the Run Configuration of the script you want to create plots of, you can create multiple graphs at once. Also, after a graph-enabled script is run, you may create several additional graphs by clicking the Graph Wizard button in the Graph Selector View.

Can I increase the rate at which SystemTap GUI update the graph?

A: Yes. By default it is set to once per second, but you can increase this in Preferences.

Is there any way to save or export the graph images?

A: Currently, no. This feature will be restored in a newer version of Systemtap IDE.

What if I want to preserve this data for manipulation later?

A: This feature will be restored in a newer version of Systemtap IDE.