Revision as of 17:11, 29 May 2014

Overview

Welcome to the SystemTap plug-in Help pages. This section is intended to provide users with information and links about the SystemTap scripting language itself, in addition to a brief introduction to SystemTap plug-in's structure for new users and a brief explanation of SystemTap.

The SystemTap Plugin

The SystemTap Plugin is designed to help you create, edit, and run SystemTap scripts. It also provides the ability to graph the output of your scripts and run SystemTap scripts remotely.

It provides the SystemTap IDE perspective. When in this perspective you should be able to see the Probe view, the Function view, and the Project Explorer. You should also be able to create SystemTap scripts.

SystemTap

SystemTap provides free software (GPL) infrastructure to simplify the gathering of information about the running Linux kernel. This assists diagnosis of a performance or functional problem. SystemTap eliminates the need for the developer to go through the tedious and disruptive instrument, recompile, install, and reboot sequence that may be otherwise required to collect data.

SystemTap provides a simple command line interface and scripting language for writing instrumentation for a live running kernel. The internal tapset library as well as the published samples can be used to aid reuse and abstraction.

Current project members include Red Hat, IBM, Intel, and Hitachi.

Installing

Requirements

Hardware Requirements:

x86, x86_64, ppc64, s390

Software Requirements:

Linux kernel v2.6.14 or newer
- Linux kernel devel and debuginfo packages
Eclipse v3.8/v4.2 or newer
SystemTap v0.7 or newer

Once all dependencies are installed, the easiest way to install the SystemTap plug-in for Eclipse is through the Software Updates and Add-ons menu. For information on how to use this menu, refer to this link.

Kernel Source Location

In order to use the kernel source browser, you will need to point it to the kernel source initially. SystemTap IDE will be set with a default kernel source path by default, but it may be necessary to set it manually. Do this by either selecting the Kernel Source Browser in the browser pane or by going to Window->Preferences, then going to the SystemTap->IDE->'Kernel Source Path' tab. It is possible to explore the kernel source in your local machine or in the same machine used to run SystemTap scripts. Enter your option and inform the kernel source location. If you selected the remote option, it is necessary to set up the remote machine information at SystemTap->'Remote Server' tab.

Tutorials

If you haven't already, you will want to take the IDE and Graphing tutorials. You can find them in the Getting Started section of each perspective's help pages. These tutorial provides fundamental knowledge on graphing in SystemTap plug-in.

Preferences (Optional)

Finally, you may want to set certain non-essential preferences before using SystemTap plug-in regularly. Use Window->Preferences to access the Preferences page.

Links to SystemTap Resources

The following links contain information specific to the SystemTap scripting language.

SystemTap website - http://sourceware.org/systemtap/
SystemTap wiki - http://sourceware.org/systemtap/wiki
SystemTap tutorial - http://sourceware.org/systemtap/tutorial/
Full list of documentation - http://sourceware.org/systemtap/documentation.html

SystemTap IDE

Getting Started

IDE Tutorial

Lesson 1: Getting Started

In this tutorial we will orient you with the SystemTap IDE and its functions. At this point we assume that you are able to run SystemTap plug-in and are unfamiliar with how to proceed. If you cannot yet start the application, please refer to our Installation help page. NOTE: If this is your the first time opening the SystemTap IDE, it will take a while to load as it has to parse the tapsets.

The SystemTap IDE's purpose is to allow the user to create, view, and edit SystemTap scripts. There are other editors built in (plain text and the C editor), however, they ultimately exist to facilitate the writing of SystemTap scripts.

In this lesson we will open a new SystemTap script file to familiarize ourselves with the SystemTap IDE. If you don't already have a project you plan to put your new script in, start by creating a new one. Select the File menu -> New -> Project -> General -> Project. Follow the wizard to create a new project.

Now you are ready to create the script. Select File -> New -> Other -> SystemTap -> SystemTap Script. Follow the wizard to provide your script name and the project which will contain it (use the project we created above).

This should open up a new editor with a small stub of a script.

At this point proceed to Lesson 2: Writing Your First Script if you wish to learn how to write your own script file or Lesson 3: Running Your Script if you wish to run this one.

Lesson 2: Writing Your First Script

In this tutorial we will guide you through the process of writing your first SystemTap script. It is strongly recommended that you review the SystemTap website's tutorial - http://sourceware.org/systemtap/tutorial for up-to-date information on the latest version of SystemTap.

In the previous lesson we created a new script and opened it in the editor.

Now try writing a new script or type/copy the following example:

global read, write, start

probe begin {
	start = gettimeofday_s()
}

probe syscall.write {
	write += count
}

probe timer.ms(1000) {
	printf("%d\t%d\t%d\n", (gettimeofday_s()-start), read, write)
	read=0
	write=0
}

Now to demonstrate the functionality of the Probe Alias browser we will have you complete the read probe yourself. Start by opening the syscall folder in the Probe Alias browser. If you do not have any content in the browser, you are experiencing a problem with SystemTap installation and should refer to our Installation help page. Now search for the "syscall.read" probe alias and double click it. SystemTap IDE will insert the skeleton probe at the end of your script, and should look similar to the following:

probe syscall.read
{
	/*
	 * available variables on this probe:
	 * $buf:long int, $count:long int, $fd:long int, $ret:long int,
	 * argstr:string, buf_uaddr:long, count:long, fd:long, name:string
	 */

}

Now insert the following line into the syscall.read probe:

read += count

You may remove the comment (/* ... */) if you wish. This will count the number of bytes read and written each second and print it out. The begin probe executes first, by getting the time of day. The read and write probes increment each time the function is called. The timer probe prints the information every second.

Another way to get assistance while writing a new probe is to press Ctrl+Space at any point during editing. Doing so will provide auto-completion for partially spelled probe names, what variables and functions are available inside a probe, and documentation where available.

In Lesson 3 you will learn how to run SystemTap scripts.

Lesson 3: Running Your Script

In this lesson we will cover running your script. You may use either the script you wrote in Lesson two or write a new one.

There are two ways to run a script:

Simple Run - Clicking this button in the toolbar will run the current script as the current user on the local machine, and will print all script output to the Eclipse console.
Run Configuration - For more control over running options, you can use a Run Configuration. To run a script with an existing Run Configuration, open the script file you want to run, then do any of the following:
- right-click on the script editor or the script file in the Project Explorer, and select Run As->SystemTap Script
- click on the Run As... button on the toolbar
- select either Run->Run or Run->Run As->SystemTap Script on the menu bar
- press Ctrl+F11 on the keyboard

If any of these options are used when a Run Configuration is not yet created for the script, a new one with default settings will be created for it. If multiple Run Configurations exist, you will be prompted to select which one to run the script with.

If you know which Run Configuration you want to use, you may simply click the arrow next to the Run As button on the toolbar and select from a list of recently-run configurations.

To create a new Run Configuration, right-click on the script editor or the script file in the Project Explorer then select Run As -> Run Configurations.... Once the dialogue pops up, double click on the SystemTap tree item and you should be presented with the following dialogue:

Here you can specify the path of the script to run, enter remote host information, run as a different user, as well as various other options for running SystemTap. Explore the various tabs and options. The tooltips should provide help in understanding what the various options do. When you are ready, click Run to run your script.

Now we will demonstrate running SystemTap scripts with graphs. In order to run the chart example you'll need to use the code provided in Lesson 2: Writing Your First Script:

global read, write, start

probe begin {
	start = gettimeofday_s()
}

probe syscall.write {
	write += count
}

probe syscall.read {
	read += count
}

probe timer.ms(1000) {
	printf("%d\t%d\t%d\n", (gettimeofday_s()-start), read, write)
	read=0
	write=0
}

To do this, select Run As -> Run Configurations... and create a new SystemTap Launch Configuration as you did previously and switch to the Graphing tab. By the end of this tutorial, the tab will look like this:

The following instructions will walk you through the steps towards configuring the graph settings as shown above.

First, select Graph the output of this script run, and in the text box labeled Regular Expression, enter a regular expression that will match the output of your script. Place parentheses () around whatever data you want to capture for graphing.

For this example, enter the following as your Regular Expression:

(\d+)\t(\d+)\t(\d+)

Alternatively, you can click the button labeled Click here to generate regular expressions from printf statements. Clicking this button will automatically create regular expressions that will capture output created by the script's printf statements.

This expression will capture the output produced by the example script. Note that in order to capture data from script output, the output must be formatted into lines/rows. Output-parsing regular expressions try to match individual lines of script output, so make sure your scripts print a line break ("\n") to mark the end of a line. (The line break character does not need to be included in the regular expression.)

Once this expression is entered, a table of Titles and Sample Extracted Values will appear. To test that your regular expression is working as intended, you may enter as Sample Output a line of text similar to what you expect your script to produce.

For this example, copy and paste the following line into the Sample Output box:

10	1000	100

and enter the following as Titles:

Time
Reads
Writes

The text boxes displayed under Sample Extracted Value now show you the values that are captured by your regular expression, which will be plotted in any graphs you create that use those values.

Now to add a graph using the parsed output, click the Add... button in the Graph Set section, which will bring up the Create Graph wizard. Select a line graph as the Graph Type, and enter the following as your Title and series values, then click Finish to save your changes:

Title:		Read Write Count
X Series:	Time
Y Series 0:	Reads
Y Series 1:	Writes

You may also specify additional regular expressions to capture output with. To do this, either press the Down arrow key while typing into the Regular Expression text box, or click the drop-down arrow of the text box and click the entry labeled New Regular Expression...

You will notice that all data entered in the Graphing menu so far, such as the sample output and graphs, will no longer visible after adding a new regular expression. This is because each regular expression has its own sample output, column titles, and set of graphs (or Graph Set) associated with it. Data for the currently-selected expression is displayed, and since the current expression is blank, so are the column & graph settings.

To capture the example script's output only at intervals of 10 units of time, use the line below as your second regular expression:

(\d+0)\t(\d+)\t(\d+)

Enter the same sample output & title values that were used for the first regular expression. Also add a graph with the same series data as before, and with a title of "Decade Read Write Counts".

When the script is executed under this Run Configuration, the Graph Selector view is opened and it will contain a Data View and any graphs you have created, with a tab for each regular expression's set of graphs. The Data View chart is populated with the output from the console. If you click on the tab labeled Graph Set 1, you should see a screen similar to the following:

Switch between the graphs in Graph Set 1 and 2 to see the difference between the two graphs you plotted. If you click on the Data View tab of either Graph Set, you will see that the data that is being parsed live from the console:

You may also create new graphs while in this view, to display data captured by your regular expressions in alternate ways. To create a new graph, first select the Graph Set you want to add a new graph to, then click on the Create Graph button, which appears to the left of the Data View tab. This will bring up the same Create Graph wizard that appears when creating a graph in a script's Run Configurations menu.

Concepts

SystemTap IDE Perspective

This is the primary perspective for SystemTap script writers. It contains the Function Browser, Kernel Browser, Probe Alias Browser, and Views and Editors. The IDE Perspective contains the features necessary execute SystemTap scripts and the syntax coloring and code completion features that facilitate efficient development of scripts.

STP Editor

This editor is the most commonly used; it is used for the authoring and editing of SystemTap scripts. It is invoked when the user starts a new file or opens a file with the .stp extension. It provides syntax highlighting, code completion, and run support.

Function Browser

The Function Browser lists all of the functions that are defined in the tapset library. Functions are grouped by the file that they are defined. Each listed function has an icon that corresponds to its return type.

String
Long
Void
Unknown

If you double click on any function a call to that function will be added to the active editor at the current cursor location. Also if you right click on a function and click View Definition the tapset file where the function is defined will be opened.

The default behavior of this view is to look for functions in the tapset library in the local machine. To look for functions in the same machine used to run the SystemTap scripts, go to Window->Preferences, select SystemTap->SystemTap IDE and check the Use remote connection to load SystemTap probes and functions option. Don't forget to configure the remote server used by remote execution in SystemTap->Remote Server.

Kernel Browser

The Kernel Source Browser is used to display the kernel tree. This provides you with a quick way to locate places to add probes. Any file in the Kernel Source tree can be opened by double clicking on it. This will open up the selected file in the Editor view. You can then double click on the ruler next to any line that you wish to probe. If SystemTap can probe that line a probe point will be inserted at the end of the script you were most recently working on. If the line can't be probed, an error message will be displayed.

To use this feature it is necessary to configure the Kernel Source Location.

Probe Alias Browser

The Probe Alias Browser lists all of the probe aliases that are defined in the tapset library, as well as all static probes defined internally by SystemTap. Probes are grouped by name. In addition to the list of probes, each probe lists all of the variables that it has access to. Each variable is listed with an icon that represents its data type. Types are as follows:

String
Long
Struct
Unknown

If you double click on any probe alias, probe point will be added to the end of the active editor. Also if you right click on a probe and click View Definition the tapset file where the probe is defined will be opened.

The default behavior of this view is to look for probes in the local machine. To look for probes in the same machine used to run the SystemTap scripts, go to Window->Preferences, select SystemTap->SystemTap IDE and check the Use remote connection to load SystemTap probes and functions option. Don't forget to configure the remote server used by remote execution in SystemTap->Remote Server.

Tasks

Creating SystemTap Scripts

Create a SystemTap script by selecting File -> New -> Other... -> SystemTap -> SystemTap Script from the menu bar. You'll be prompted to enter a name for the file; make sure that you use a .stp extension or else the SystemTap IDE will not recognize the file as a SystemTap script and certain editor and run features will not be active.

Your new file will be open and ready for coding in the Editor pane.

A IDE Tutorial is also provided in the help pages for a step by step demo.

For advanced SystemTap language help please see the SystemTap Development User's Guide and the documentation available at the SystemTap website's documentation page - http://sourceware.org/systemtap/documentation.html

Using the STP Editor

The STP Editor is used for the authoring and editing of SystemTap scripts. It is invoked when the user starts a new file or opens a file with the .stp extension. Using the editor is as easy as setting the focus to the editor pane and typing.

There are certain features within the editor you may want to take advantage of:

Syntax Highlighting - Certain code items are colored in .stp and .c files based on a set of rules and colors.
Code Assist - SystemTap IDE will attempt to finish your probe alias names based on what you have already typed. You can then select the appropriate probe alias or continue typing to filter the list down even more.
Run Support - See the Lesson 3: Running Your Script help page on a walk through use of the Run command. The Run command allows scripts to be executed directly through SystemTap IDE.

Creating Run Configurations

Advanced options for running SystemTap scripts are available in the Run Configurations menu. This menu may be accessed by right-clicking a script and choosing Run As->Run Configurations from the context menu, by selecting Run->Run Configurations in the menu bar, or by using the drop-down menu next to the Run toolbar button.

Local/Remote Runs

It is possible to run scripts either locally or remotely, and as different users. To configure these settings, use the General tab of the Run Configurations menu.

The following options are available:

Execute script as current user - Uncheck this box to run the script as a different user. While unchecked, you may enter the User Name and Password of the user you wish to run the script as.
Run script on localhost - Uncheck this box to run the script on a remote machine. Type the name of the desired host to use in Host Name. (This option is only available when running as a non-current user.)
Use default port - When unchecked, you may specify the port that is to be used for remote communication. The default port is 22. (This option is only available when running on a non-local host.)

SystemTap Options

The SystemTap tab allows for the specification of many command-line options to the stap command that is to be run. View the SystemTap manual for information on these options - https://sourceware.org/systemtap/man/stap.1.html

Graphing

Many options and features are available in the Graphing tab for creating graphs out of a script's output. For detailed information on how to create graphs, refer to Lesson 3: Running Your Script and the Graphing Tutorial.

Viewing Data Charts

Viewing data charts from a SystemTap script is accomplished by running that script with the Run Configurations containing your graphs. This is covered in Lesson 3: Running Your Script. After running a script with the graphing option, the user is presented with the Graph Selector View, and the last graph of the final Graph Set is loaded by default. When that view appears, click on the Data View tab of any Graph Set to see it begin populating as it receives input back through the console from the running SystemTap script.

Reference

Views and Editors

This section details the views and editor in relation to the SystemTap IDE.

Views

The IDE Perspective consists of 5 views and and two editors.

Probe Alias Browser - A list of all probe aliases currently available in your version of SystemTap and all active tapsets. Covered in detail here.
Function Browser - A list of functions currently supported in your version of SystemTap and all active tapsets. Covered in detail here.
Kernel Source Browser - Used to display the kernel tree. Covered in detail here.
Console - The console view is where all of the output from the running script is shown. If more then one script is running at the same time you are able to switch between which console is currently displayed by clicking on the Display Selected Console button. The script can halt execution here if the user selects the Stop button. The user also has the option of saving the console output to a file, which can be done while the script is running by clicking the Save log output button at the top of the console.

Error Log - If the script you tried to run contained errors, this view will become active and display the errors. You can double click on the error message to jump to the line in the file where the error occurred.

Editors

Three editors are available in the SystemTap IDE.

STP Editor - This editor is the most commonly used; it is used for the authoring and editing of SystemTap scripts. It is invoked when the user starts a new file or opens a file with the .stp extension. It provides syntax highlighting, code completion, and run support.
C Editor - This editor is available for the read only viewing of kernel source. It is invoked when the user opens a file of extension .c. Syntax highlighting is supported in this mode.
Plain Text Editor - A plain text editor is also implemented for the user should they need it.

Menus

What follows is a comprehension list of the menu options available within the SystemTap IDE.

Edit

Undo - Undos the previous editor related action. (Shortcut: Ctrl+Z)
Redo - Redos the previous editor related action removed by Undo. (Shortcut: Ctrl+Y)
Cut - Removes the selected text from the editor pane and places it in the clipboard. (Shortcut: Shift+Delete, Ctrl+X)
Copy - Copies the selected text from the editor pane and places it in the clipboard. (Shortcut: Ctrl+Insert, Ctrl+C)
Paste - Copies the text from the clipboard to the location of the focus in the editor pane. (Shortcut: Shift+Insert, Ctrl+V)
Select All - Selects all text within the file in the editor that the focus is currently in. (Shortcut: Ctrl+A)
Find/Replace - Opens the Find/Replace dialogue in which users may specify a text string to find and/or replace, with options to search forwards or backwards, the entire document or just the selected lines, and whether or not they want the following options:
- Case sensitive
- Wrap Search
- Whole Word
- Incremental
- Regular expressions

(Shortcut: Ctrl+F)

Find Next - Finds the next instance of the search string in the direction indicated in the Find/Replace dialogue box. (Shortcut: Ctrl+K)
Find Previous - Finds the previous instance of the search string in the direction indicated in the Find/Replace dialogue box. (Shortcut: Shift+Ctrl+K)
Incremental Find Next - Finds the next occurrence of the text and updates the selection after each character typed. To use Incremental Find:
- In the text (or Java) editor, press Ctrl+J or select Edit > Incremental Find Next from the menu bar.
- The workbench status line displays Incremental Find:. The editor is now in the Incremental Find mode.
- As you type, the editor finds the next occurrence of the text and updates the selection after each character typed.
- Navigate to the next or previous match by pressing Arrow Down or Arrow Up.
- Undo the last action within the Incremental Find mode by pressing Backspace.
- You can leave the Incremental Find mode by pressing Esc
Incremental Find Previous - Operates as illustrated in above bullet but in the reverse. (Shortcut: Shift+Ctrl+J)
Select All - Selects all the text in the file that currently has the focus. (Shortcut: Ctrl+A)
Word Completion - Completes the string being typed by using the last example typed by the user. (Shortcut: Alt+/)

Navigate

Forward - Navigates to the next file in sequence as they were opened in the editor pane. (Shortcut: Alt+Right)
Back - Navigates to the previous file in sequence as they were opened in the editor pane. (Shortcut: Alt+Left)
Last Edit Location - Moves the focus to the file containing the last known edit. (Shortcut: Ctrl+Q)
Goto Line... - Moves the focus to the specified line number, with the range of line numbers listed in the dialogue box. (Shortcut: Ctrl+L)

Run

Run - Available when a SystemTap script is loaded into the editor, this feature runs the script. You will be prompted to run the script either locally or on a remote machine. If run locally and multiple Run Configurations exist for the script, you will be prompted to choose which of them to run. (Shortcut: Ctrl+F11)

Window

New Window - This option opens a new instance of the SystemTap IDE.
Open Perspective - This submenu lists each of the available perspectives to open:
- SystemTap IDE
- Other... - Lists all other perspectives available to Eclipse.
Show Views - This submenus lists each of the available views to open:
- Console
- Functions
- Kernel Source
- Probe Alias
- SystemTap Error Log
- Other... - Lists all views in the application.
Preferences - Due to the breath of this topic it is covered in another section. Please see Preferences.

Toolbars

Action Bar

New File - This button will bring up a dialogue to create a new file. When you click OK the file will be opened in the editor window.
Simple Run - This will compile the open script and start running it, without using a Run Configuration. All output will be sent to the console. If there is an error in the script the error will be reported in the Error Log.
Run As - This compiles & runs the current script, but also searches for a Run Configuration that targets the script, and runs the script with the launch options provided by it. Use this instead of Simple Run when you want graphs to be plotted. (Shortcut: Ctrl+F11)

Preferences

This section details each of the options listed under Window->Preferences. The Preferences dialog is used to set user preferences. Its pages can be searched using the filter function. To filter by matching the page title, simply type the name of the page you are seeking in the text box in the top-left corner of the dialog, and the available pages will be presented in the list below. The filter also searches on keywords such as "appearance" and "Java".

SystemTap - This section contains options relevant to SystemTap itself.
- Environment Variables - Allows the user to set specific values to the following environment variables
  - LD_LIBRARY_PATH
  - PATH
  - SYSTEMTAP_TAPSET
  - SYSTEMTAP_RUNTIME
- Graphing - Preferences related to the Graphing Perspective.
  - Refresh Delay (ms) - Milliseconds between graphs are updated with the latest data.
  - Data Table - Preferences related to the data table.
    - Jump to the newest entry - Determines whether the scroll bar maintains its location at the newest entry.
    - Auto resize columns - Determines whether columns automatically resize to the width of the contents or whether they can be adjusted by the user.
    - Max data items - Maximum number of entries that the table shows, though the table itself may have more not visible.
  - Graph - Preferences related to graphs.
    - Show X/Y grid lines - Turns on and off painting of the grid lines for either axis.
    - Max data items - Number of maximum samples read from a script's output.
    - Viewable data items - Number of maximum samples plotted at any time.
    - X/Y series ticks - Specify the number of labeled number markers on either axis.
- IDE - Preferences when loading the IDE Perspective.
  - Use stored tapset trees - If checked, the next initialization of SystemTap IDE will load all tapset contents (probes & functions) from a local configuration file instead of having to search for them manually. This configuration file is saved whenever changes to tapsets are made while this box is checked, or when it is checked for the first time.
  - Use remote connection to load SystemTap probes and functions - If checked, tapset contents (probes & functions) will be loaded from a remote machine (specified in Remote Server) instead of the local machine.
  - Kernel Source Path - Location of the directory that the kernel source code is pulled from. A local or remote machine may be used.
    - Tapsets - Preferences related to tapsets.
      - Additional Tapsets - Allows you to specify additional tapsets scripts to be added in with every script, and to be displayed in the Function and Probe Alias Browsers.
- Remote Server - Details regarding running SystemTap on a remote machine. Any operations that run SystemTap on a remote machine will use the one specified by the credentials provided here.
  - Host Name - IP address of the remote machine.
  - Port - Port used for communication. Default is 22462.
  - User Name - User name that has sufficient permissions to transfer and run the script on the remote machine.
  - Password - Password for the above user.

Frequently Asked Questions

This section details frequently asked questions relating to the IDE Perspective.

Where can I find information regarding the SystemTap scripting language?

A: The best place to look for up to date information regarding SystemTap itself is its homepage - http://sourceware.org/systemtap/documentation.html

How do I run a script once I've written it?

A: There are two ways to run a script: -with the Simple Run button on the toolbar, which runs the script that has editor focus. It will be run without drawing graphs or any other configurations. -by launching it with a Run Configuration that targets any specified script, even one that is not in the workspace.

Read Lesson 3: Running Your Script and Menus to learn more about the ways of running SystemTap scripts.

Why does the application seem to hang when switching to the SystemTap IDE?

A: If this is the first time you are trying to open the SystemTap IDE, or have recently gotten a new version of SystemTap this is expected. In order to generate a full list of all of the available probes and functions, the GUI has to run a background SystemTap process and parse the results. A future update to SystemTap IDE will reduce the duration of this operation.

Example SystemTap Scripts

What follows is a few SystemTap Scripts that you may use in SystemTap IDE, taken from and linked to http://sourceware.org/systemtap/documentation.html

There is also a description of the examples - http://sourceware.org/systemtap/examples/demo_script.txt

top.stp - Prints the top 20 system calls (http://sourceware.org/systemtap/examples/top.stp)

#!/usr/bin/env stap
#
# This script continuously lists the top 20 system calls on the system
#

global syscalls

function print_top () {
	cnt=0
	log ("SYSCALL\t\t\t\tCOUNT")
	foreach ([name] in syscalls-) {
		printf("%-20s\t\t%5d\n",name, syscalls[name])
		if (cnt++ = 20)
			break
	}
	printf("--------------------------------------\n")
	delete syscalls
}

probe kernel.function("sys_*") {
	syscalls[probefunc()]++
}

# print top syscalls every 5 seconds
probe timer.ms(5000) {
	print_top ()

prof.stp - Simple profiling (http://sourceware.org/systemtap/examples/prof.stp)

#!/usr/bin/env stap

# This is an example of profiling a specific command or pid.
# It works by recording the time when a system call is entered
# exited.

# Usage: prof.stp -c "top -n5"
# Will start up "top" and after 5 iterations, will exit.
#
# Usage: prof.stp -x 3323
# Will profile pid 3323 until it ^c is hit.
#

probe kernel.function("sys_*") {
	if (target() = tid())
		calltime[tid()] = gettimeofday_us()
}

probe kernel.function("sys_*").return {
	if (target() != tid())  next
	now = gettimeofday_us()
	c = calltime[tid()]
	if (!c) next
	ttime[probefunc()] <<< now - c
	delete calltime[tid()]
}

probe end {
	printf("\n")
	foreach (x in ttime)
		printf("%-20s\tcalls:%6d\tavg time (ms):%5d\ttotal(ms):%7d\n",
			x, @count(ttime[x]), @avg(ttime[x]), @sum(ttime[x]))
}

global calltime, ttime

keyhack.stp - Modifying variables in the kernel. (http://sourceware.org/systemtap/examples/keyhack.stp)

#! /usr/bin/env stap

# This is not useful, but it demonstrates that
# SystemTap can modify variables in a running kernel.

# Usage: ./keyhack.stp -g

probe kernel.function("kbd_event") {
	# Changes 'm' to 'b' .
	if ($event_code = 50) $event_code = 48
}

probe end {
	printf("\nDONE\n")
}

kmalloc.stp - Statistics example. (http://sourceware.org/systemtap/examples/kmalloc.stp)

#! /usr/bin/env stap

# Using statistics to examine kernel memory allocations

global kmalloc

probe kernel.function("__kmalloc") {
	kmalloc <<< $size
}

# Exit after 10 seconds
probe timer.ms(10000) { exit () }

probe end {
	printf("Count:   %d allocations\n", @count(kmalloc))
	printf("Sum:     %d Kbytes\n", @sum(kmalloc)/1000)
	printf("Average: %d bytes\n", @avg(kmalloc))
	printf("Min:     %d bytes\n", @min(kmalloc))
	printf("Max:     %d bytes\n", @max(kmalloc))	
	print("\nAllocations by size in bytes\n")
	print(@hist_log(kmalloc))
}

kmalloc2.stp - Example using arrays of statistics. (http://sourceware.org/systemtap/examples/kmalloc2.stp)

#! /usr/bin/env stap

# Using statistics and maps to examine kernel memory allocations

global kmalloc

probe kernel.function("__kmalloc") {
	kmalloc[execname()] <<< $size
}

# Exit after 10 seconds
probe timer.ms(10000) { exit () }

probe end {
	foreach ([name] in kmalloc) {
		printf("Allocations for %s\n", name)
		printf("Count:   %d allocations\n", @count(kmalloc[name]))
		printf("Sum:     %d Kbytes\n", @sum(kmalloc[name])/1000)
		printf("Average: %d bytes\n", @avg(kmalloc[name]))
		printf("Min:     %d bytes\n", @min(kmalloc[name]))
		printf("Max:     %d bytes\n", @max(kmalloc[name]))	
		print("\nAllocations by size in bytes\n")
		print(@hist_log(kmalloc[name]))
		printf("-------------------------------------------------------\n\n");
	}
}

Guide to Regular Expressions

Regular expressions are used for SystemTap graphs to interpret information that it recieves from a script's output.

Basic regex (taken from "http://java.sun.com/j2se/1.5.0/docs/api/ ) -

 Summary of regular-expression constructs

Construct 	Matches

Characters
x 	The character x
\\ 	The backslash character
\0n 	The character with octal value 0n (0 <= n <= 7)
\0nn 	The character with octal value 0nn (0 <= n <= 7)
\0mnn 	The character with octal value 0mnn (0 <= m <= 3, 0 <= n <= 7)
\xhh 	The character with hexadecimal value 0xhh
\uhhhh 	The character with hexadecimal value 0xhhhh
\t 	The tab character ('\u0009')
\n 	The newline (line feed) character ('\u000A')
\r 	The carriage-return character ('\u000D')
\f 	The form-feed character ('\u000C')
\a 	The alert (bell) character ('\u0007')
\e 	The escape character ('\u001B')
\cx 	The control character corresponding to x

Character classes
[abc] 	a, b, or c (simple class)
[^abc] 	Any character except a, b, or c (negation)
[a-zA-Z] 	a through z or A through Z, inclusive (range)
[a-d[m-p]] 	a through d, or m through p: [a-dm-p] (union)
[a-z&&[def]] 	d, e, or f (intersection)
[a-z&&[^bc]] 	a through z, except for b and c: [ad-z] (subtraction)
[a-z&&[^m-p]] 	a through z, and not m through p: [a-lq-z](subtraction)

Predefined character classes
. 	Any character (may or may not match line terminators)
\d 	A digit: [0-9]
\D 	A non-digit: [^0-9]
\s 	A whitespace character: [ \t\n\x0B\f\r]
\S 	A non-whitespace character: [^\s]
\w 	A word character: [a-zA-Z_0-9]
\W 	A non-word character: [^\w]

POSIX character classes (US-ASCII only)
\p{Lower} 	A lower-case alphabetic character: [a-z]
\p{Upper} 	An upper-case alphabetic character:[A-Z]
\p{ASCII} 	All ASCII:[\x00-\x7F]
\p{Alpha} 	An alphabetic character:[\p{Lower}\p{Upper}]
\p{Digit} 	A decimal digit: [0-9]
\p{Alnum} 	An alphanumeric character:[\p{Alpha}\p{Digit}]
\p{Punct} 	Punctuation: One of !"#$%&'()*+,-./:;<=>?@[\]^_`{|}~
\p{Graph} 	A visible character: [\p{Alnum}\p{Punct}]
\p{Print} 	A printable character: [\p{Graph}\x20]
\p{Blank} 	A space or a tab: [ \t]
\p{Cntrl} 	A control character: [\x00-\x1F\x7F]
\p{XDigit} 	A hexadecimal digit: [0-9a-fA-F]
\p{Space} 	A whitespace character: [ \t\n\x0B\f\r]

java.lang.Character classes (simple java character type)
\p{javaLowerCase} 	Equivalent to java.lang.Character.isLowerCase()
\p{javaUpperCase} 	Equivalent to java.lang.Character.isUpperCase()
\p{javaWhitespace} 	Equivalent to java.lang.Character.isWhitespace()
\p{javaMirrored} 	Equivalent to java.lang.Character.isMirrored()

Classes for Unicode blocks and categories
\p{InGreek} 	A character in the Greek block (simple block)
\p{Lu} 	An uppercase letter (simple category)
\p{Sc} 	A currency symbol
\P{InGreek} 	Any character except one in the Greek block (negation)
[\p{L}&&[^\p{Lu}]]  	Any letter except an uppercase letter (subtraction)

Boundary matchers
^ 	The beginning of a line
$ 	The end of a line
\b 	A word boundary
\B 	A non-word boundary
\A 	The beginning of the input
\G 	The end of the previous match
\Z 	The end of the input but for the final terminator, if any
\z 	The end of the input

Greedy quantifiers
X? 	X, once or not at all
X* 	X, zero or more times
X+ 	X, one or more times
X{n} 	X, exactly n times
X{n,} 	X, at least n times
X{n,m} 	X, at least n but not more than m times

Reluctant quantifiers
X?? 	X, once or not at all
X*? 	X, zero or more times
X+? 	X, one or more times
X{n}? 	X, exactly n times
X{n,}? 	X, at least n times
X{n,m}? 	X, at least n but not more than m times

Possessive quantifiers
X?+ 	X, once or not at all
X*+ 	X, zero or more times
X++ 	X, one or more times
X{n}+ 	X, exactly n times
X{n,}+ 	X, at least n times
X{n,m}+ 	X, at least n but not more than m times

Logical operators
XY 	X followed by Y
X|Y 	Either X or Y
(X) 	X, as a capturing group

Back references
\n 	Whatever the nth capturing group matched

Quotation
\ 	Nothing, but quotes the following character
\Q 	Nothing, but quotes all characters until \E
\E 	Nothing, but ends quoting started by \Q

Special constructs (non-capturing)
(?:X) 	X, as a non-capturing group
(?idmsux-idmsux)  	Nothing, but turns match flags on - off
(?idmsux-idmsux:X)   	X, as a non-capturing group with the given flags on - off
(?=X) 	X, via zero-width positive lookahead
(?!X) 	X, via zero-width negative lookahead
(?<=X) 	X, via zero-width positive lookbehind
(?<!X) 	X, via zero-width negative lookbehind
(?>X) 	X, as an independent, non-capturing group
Match a position that is not a word boundary.

Information regarding regular expressions can be found all over the Internet. A few examples have been listed below:

SystemTap Graphing

Getting Started

Introduction

When 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 labeled 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 separate set of data points on your graph, labeled 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 initially 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 separation lines between column headers, as long as the Auto resize columns option (in Preferences->SystemTap->Graphing->Data Table) has been deactivated. 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:
- Unformatted - No formatting 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. All values must be numeric.

Line Graph

The Line Graph is traditionally ideal for horizontally depicting non-cumulative data over, say, time. All values must be numeric.

Area Graph

The Area Graph is traditionally ideal for horizontally depicting non-cumulative data over, say, time. All values must be numeric.

Bar Graph

The Bar Graph typically uses bars to show frequencies or values. Labels can be given to bars by applying string values to the x-axis. Y-axis values, though, must be numeric.

Pie Graph

The Pie Graph uses a pie to show percentages. One pie is drawn for each data series provided. Titles can be given to slices by applying string values to the x-axis. Y-axis values, though, must be numeric.

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 and manageable.

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

Add Filter... - Adds a Filter to the Data Table. Multiple filters may be applied at a time.
Remove Filter... - Removes a Filter from the Data Table. All currently applied filters will be listed in a drop-down menu; the user may select which of them to remove.

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

What follows is a breakdown of each Filter type, and an example of how each affects this sample data set:

Match Filter - This filter either removes or keeps everything from the data set where the selected selected column's value matches the chosen value.

Result:

Range Filter - This filter keeps everything from the data set that is either inside or outside the selected range of values. Note that it is possible to use unbounded ranges by leaving either the lower or upper bound blank.

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

Graph Options

Each of the Graph Types have similar options that can be used in the Graph Selector View:

Legend - This option turns on and off the legend, particularly useful in the graph types that show multiple series.
Graph Scrolling/Scaling - It is possible to zoom & scroll through any graph axis. Different controls are provided for navigating through continuous and discrete axes.

To zoom in/out of a continuous axis (ie Scatter/Line/Area Graph), use the +/- buttons or the Scale bar beneath / to the left of a graph. To scroll through the viewing area, use the horizontal/vertical scroll bars provided.

Specialized controls are available for zooming & scrolling through discrete axis, namely the bars of a Bar Graph or the pies of a Pie Chart.

Zooming is performed with the Zoom In/Out buttons beneath the graph. To scroll to left or right, click < or > respectively. To jump to the beginning or end of the axis, click << or >> respectively.

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

Graph Coordinate Tooltips

Hover over any data point on a graph to display detailed information about that point's coordinates. This feature is available for all graph types.

Graphing Tasks

Importing/Exporting Data Sets

A data set is comprised of the contents of a Graph Set's data table. From time to time the user may want to preserve this data for continued work at a later date/time or to share findings with others. The Importing and Exporting options provide an easy way to do this.

To save a data set, click the Export Data Set toolbar button while viewing one of the tabs of the Graph Set data that is to be saved (either the Data Table or one of its graphs). To load & display a previously-exported data set, use the Import Data Set toolbar button, which is available at all times.

The Data Set toolbar buttons that appear while viewing a Graph Set. (Blue/left: Export. Red/Right: Import.)

The Import Data Set button as it appears while a Graph Set is not being viewed.

In either case, a file dialog will appear to allow the user to choose the path on the filesystem where the data set should be exported to / imported from.

Saving a Graph Image

It is possible to save graphs as image files. To do so, view the graph that is to be saved and click the Save Graph button that appears in the toolbar. This opens a dialogue box where the user can navigate to the location they desire to save the image file.

Reference

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 graphs are updated?

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: Yes. A Save Graph button appears in the toolbar whenever you are viewing a graph. Clicking it will allow you to save the graph currently in focus.

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

A: While viewing a Data Table or one of the graphs it provides data to, the Export Data Set toolbar button is available. Click this button to save the focused Data Table's contents into a .set file. Such files can be loaded back later with the Import Data Set button on the toolbar (which is always available).

@@ Line 1: / Line 1: @@
-{{#eclipseproject:tools.linuxtools}}
+= Overview =
-{{Linux_Tools}}
-= Overview =
 Welcome to the SystemTap plug-in Help pages. This section is intended to provide users with information and links about the SystemTap scripting language itself, in addition to a brief introduction to SystemTap plug-in's structure for new users and a brief explanation of SystemTap.
-== SystemTap Plugin Design ==
+== The SystemTap Plugin ==
-SystemTap plug-in was built with a modular goal in mind, namely, to provide the application as a series of plugins so that users may obtain just the ones they need without having to use a heavy-weight application should if they didn't need to. The most common example of this is to ship the Dashboard plugin independently, allowing non-SystemTap savvy users the ability to execute modules without having to write any scripts. The application in its complete state includes three perspective, each with a specific goal:
-* '''IDE Perspective''' - Contains script editor and Function, Kernel Source, and Probe Alias browsers to assist in the creation and editting of SystemTap scripts.
+The SystemTap Plugin is designed to help you create, edit, and run SystemTap scripts. It also provides the ability to graph the output of your scripts and run SystemTap scripts remotely.
-* '''Graphics Perspective''' - Graphs data from SystemTap scripts in the desired graph form according to a regular expression passed to interpret the data.
-* '''Dashboard Perspective''' - Allows the execution of modules, which are scripts with associated metadata that open one or more graphs in a dashboard environment that update in real time.This perspective is still under development
-Each perspective has full documentation associated with it and is packaged in the respective plugin.
+It provides the '''SystemTap IDE''' perspective. When in this perspective you should be able to see the Probe view, the Function view, and the Project Explorer. You should also be able to create SystemTap scripts.
-== Systemtap ==
+== SystemTap ==
 SystemTap provides free software (GPL) infrastructure to simplify the gathering of information about the running Linux kernel. This assists diagnosis of a performance or functional problem. SystemTap eliminates the need for the developer to go through the tedious and disruptive instrument, recompile, install, and reboot sequence that may be otherwise required to collect data.
@@ Line 30: / Line 24: @@
 * x86, x86_64, ppc64, s390
-'''Sotware Requirements:'''
+'''Software Requirements:'''
-** Linux kernel v2.6.14 or newer
+* Linux kernel v2.6.14 or newer
-*** Linux kernel devel and debuginfo packages
+** Linux kernel devel and debuginfo packages
-** Eclipse v3.8/v4.2 or newer
+* Eclipse v3.8/v4.2 or newer
-** SystemTap v0.7 or newer
+* SystemTap v0.7 or newer
-Once  all dependencies are installed, the easiest way to install the SystemTap plug-in for Eclipse is through the '''''Software Updates and Add-ons''''' menu. For information on how to use this menu, refer to [http://wiki.eclipse.org/Linux_Tools_Project/PluginInstallHelp#Installing_Updates_From_the_Linux_Tools_Update_Site this link].
+Once all dependencies are installed, the easiest way to install the SystemTap plug-in for Eclipse is through the '''''Software Updates and Add-ons''''' menu. For information on how to use this menu, refer to [http://wiki.eclipse.org/Linux_Tools_Project/PluginInstallHelp#Installing_Updates_From_the_Linux_Tools_Update_Site this link].
 === Kernel Source Location ===
-In order to use the kernel source browser you'll need to point it to the kernel source initially. Do this by either selecting the Kernel Source Browser in the browser pane or by going to '''<u>W</u>indow-><u>P</u>references''', then going to the SystemTap->IDE->'Kernel Source Path' tab. It is possible to explore the kernel source in your local machine or in the same machine used to run SystemTap scripts. Enter your option and inform the kernel source location. If you selected the remote option, it is necessary to set up the remote machine information at SystemTap->'Remote Server' tab.
+In order to use the kernel source browser, you will need to point it to the kernel source initially. SystemTap IDE will be set with a default kernel source path by default, but it may be necessary to set it manually. Do this by either selecting the Kernel Source Browser in the browser pane or by going to '''<u>W</u>indow-><u>P</u>references''', then going to the SystemTap->IDE->'Kernel Source Path' tab. It is possible to explore the kernel source in your local machine or in the same machine used to run SystemTap scripts. Enter your option and inform the kernel source location. If you selected the remote option, it is necessary to set up the remote machine information at SystemTap->'Remote Server' tab.
-This configuration detail is relevent to the IDE Perspective only.
 === Tutorials ===
@@ Line 50: / Line 42: @@
 === Preferences (Optional) ===
-Finally, you may want to set certain non-essential preferences before using SystemTap plug-in regularly. Use
+Finally, you may want to set certain non-essential preferences before using SystemTap plug-in regularly. Use '''<u>W</u>indow-><u>P</u>references''' to access the Preferences page.
-'''<u>W</u>indow-><u>P</u>references''' to access the Preferences page.
-Of particular note are
-Logging->Log To, SystemTap->Environment Variables, SystemTap->Graphing->Refresh Delay,
-SystemTap->IDE->Editor->Syntax Coloring.
 == Links to SystemTap Resources ==
@@ Line 65: / Line 52: @@
 * '''SystemTap tutorial''' - http://sourceware.org/systemtap/tutorial/
 * '''Full list of documentation''' - http://sourceware.org/systemtap/documentation.html
-The following links are related to the SystemTap GUI project:
-* '''SystemTap GUI Sourceforge''' - https://sourceforge.net/projects/stapgui/
-* '''SystemTap GUI Homepage''' - http://stapgui.sourceforge.net/
 = SystemTap IDE =
 == Getting Started ==
 === IDE Tutorial ===
 ==== Lesson 1: Getting Started ====
-In this tutorial we will orient you with IDE Perspective and its functions. At this point we assume
+In this tutorial we will orient you with the SystemTap IDE and its functions. At this point we assume
-that you are able to run Systemtap plug-in and are unfamiliar with how to procede. If you cannot yet start
+that you are able to run SystemTap plug-in and are unfamiliar with how to proceed. If you cannot yet start
-the application, please refer to our [[#Installation | Installation help page]]
+the application, please refer to our [[#Installation | Installation help page]].
-'''NOTE:''' If this is the first time opening the IDE Perspective it will take a while to load as it has to
+'''NOTE:''' If this is your the first time opening the SystemTap IDE, it will take a while to load as it has to parse the tapsets.
-parse the tapsets.
-The IDE Perspective's purpose is to allow the user to create, view, and edit Systemtap scripts. There are
+The SystemTap IDE's purpose is to allow the user to create, view, and edit SystemTap scripts. There are
-other editors built in (plain text and the C editor), however, they ultimately exist to facilitate the
+other editors built in (plain text and the C editor), however, they ultimately exist to facilitate the writing of SystemTap scripts.
-writing of Systemtap scripts.
-In this lesson we will open a new Systemtap script file to familiarize ourselves with the IDE Perspective.
+In this lesson we will open a new SystemTap script file to familiarize ourselves with the SystemTap IDE.
-Start by opening the <u>F</u>ile menu and selecting <u>O</u>pen. A dialogue box will pop up and request the
+If you don't already have a project you plan to put your new script in, start by creating a new one.
-location of the file you want to open. We've included a folder called "examples" right in the tar ball. You
+Select the <u>F</u>ile menu -> New -> Project -> General -> Project. Follow the wizard to create a new project.
-may chose any of them to use; in this tutorial we will open top.stp. Go ahead and open the file.
-[[Image:Editor.png]]
+Now you are ready to create the script. Select File -> New -> Other -> SystemTap -> SystemTap Script. Follow the wizard to provide your script name and the project which will contain it (use the project we created above).
-You'll see the file is loaded into the editor pane of Systemtap GUI. You'll also noticed different colored
+This should open up a new editor with a small stub of a script.
-text. Systemtap GUI supports syntax highlighting for the ease of the writer. Feel free to edit the file.
-At this point proceed to [[#Lesson_2:_Writing_Your_First_Script | Lesson 2: Writing Your First Script ]] if you wish to learn how to write your
+At this point proceed to [[#Lesson_2:_Writing_Your_First_Script | Lesson 2: Writing Your First Script]] if you wish to learn how to write your own script file or [[#Lesson_3:_Running_Your_Script | Lesson 3: Running Your Script]] if you wish to run this one.
-own script file or [[#Lesson_3:_Running_Your_Script | Lesson 3: Running Your Script ]] if you wish to run this one.
 ==== Lesson 2: Writing Your First Script ====
-In this tutorial we will guide you through the process of writing your first Systemtap script. It is strongly recommended that you review the '''Systemtap website's tutorial''' - http://sourceware.org/systemtap/tutorial for up-to-date information on the latest version of Systemtap.
+In this tutorial we will guide you through the process of writing your first SystemTap script. It is strongly recommended that you review the '''SystemTap website's tutorial''' - http://sourceware.org/systemtap/tutorial for up-to-date information on the latest version of SystemTap.
-Start by selecting <u>F</u>ile-&gt;<u>N</u>ew. Specify a file name of your choosing, but be sure that it ends with an .stp extension. Click ok. Your blank script should be present in the editor pane.
+In the previous lesson we created a new script and opened it in the editor.
 [[Image:Newfile.png]]
-Now type/copy the following:
+Now try writing a new script or type/copy the following example:
+<pre>global read, write, start
-<pre>
+probe begin {
-	global read, write, start
+	start = gettimeofday_s()
+}
-	probe begin {
+probe syscall.write {
-		start = gettimeofday_s()
+	write += count
-	}
+}
-	probe syscall.write {
-		write += count
-	}
-	probe timer.ms(1000) {
-		printf("%d\t%d\t%d\n", (gettimeofday_s()-start), read, write)
-		read=0
-		write=0
-	}
-</pre>
-Now to demonstrate the functionality of the Probe Alias browser we will have you complete the read probe yourself. Start by opening the syscall folder in the Probe Alias browser. If you do not have any content in the browser you are experiencing a problem with Systemtap installation and should refer to our [[#Installation|Installation help page]]. Ensure your cursor is located at the end of the file. Now scroll down and double click the read probe alias. Systemtap GUI will insert the skeleton probe at the point at which your cursor is at, and should look similar to the following:
+probe timer.ms(1000) {
+	printf("%d\t%d\t%d\n", (gettimeofday_s()-start), read, write)
+	read=0
+	write=0
+}
+</pre>
+Now to demonstrate the functionality of the Probe Alias browser we will have you complete the read probe yourself. Start by opening the syscall folder in the Probe Alias browser. If you do not have any content in the browser, you are experiencing a problem with SystemTap installation and should refer to our [[#Installation|Installation help page]]. Now search for the "syscall.read" probe alias and double click it. SystemTap IDE will insert the skeleton probe at the end of your script, and should look similar to the following:
 <pre>probe syscall.read
 {
 	/*
 	 * available variables on this probe:
-	 * argstr, buf_uaddr, count, fd, name
+	 * $buf:long int, $count:long int, $fd:long int, $ret:long int,
+	 * argstr:string, buf_uaddr:long, count:long, fd:long, name:string
 	 */
 }
 </pre>
+Now insert the following line into the syscall.read probe:
+<pre>read += count</pre>
+You may remove the comment (/* ... */) if you wish. This will count the number of bytes read and written each second and print it out. The begin probe executes first, by getting the time of day. The read and write probes increment each time the function is called. The timer probe prints the information every second.
-Now insert the following line into the syscall.read probe:
+Another way to get assistance while writing a new probe is to press Ctrl+Space at any point during editing. Doing so will provide auto-completion for partially spelled probe names, what variables and functions are available inside a probe, and documentation where available.
-<pre>read += count</pre>
-You may remove the comment (/* ... */) if you wish.
-This will count the number of bytes read and written each second and print it out. The begin probe executes first, by getting the time of day. The read and write probes increment each time the function is called. The timer probe prints the information every second. If you typed the script in manually you may have noticed that the editor provides code completion for probe alias. If you did not, type "syscall.". You'll see a box come up that you may use to select an item to complete your probe alias.
+[[Image:ContextAssist.png]]
-In [[#Lesson_3:_Running_Your_Script|Lesson 3]] you will learn how to run Systemtap scripts in the IDE Perspective.
+In [[#Lesson_3:_Running_Your_Script|Lesson 3]] you will learn how to run SystemTap scripts.
 ==== Lesson 3: Running Your Script ====
-In this lesson we will cover running your script. You may use either the example script you opened in Lesson 1 or the script you wrote in Lesson two. Select <u>R</u>un-&gt;<u>R</u>un. Enter the remote server details. You should receive output in the console similar to the following, which shows the reads and write per second.
+In this lesson we will cover running your script. You may use either the script you wrote in Lesson two or write a new one.
-[[Image:IDEOutput.png]]
+There are two ways to run a script:
-Now we will demonstrate running Systemtap scripts with graphs. In order to run the chart example you'll need to use the code provided in [[#Lesson_2:_Writing_Your_First_Script | Lesson 2: Writing Your First Script ]];. To do this select '''<u>R</u>un-&gt;Run w/ <u>C</u>hart'''. This feature will prompt the user for the number of columns for the chart, in addition to their titles and regular expressions. The regular expressions are used to parse the console output for the script and determine the values of each column at a certain sample point. The combined regular expression is shown at the bottom of the dialogue box.
+* [[Image:Run_exc.gif]] '''Simple Run''' - Clicking this button in the toolbar will run the current script as the current user on the local machine, and will print all script output to the Eclipse console.
+* '''Run Configuration''' - For more control over running options, you can use a Run Configuration. To run a script with an existing Run Configuration, open the script file you want to run, then do any of the following:
+** right-click on the script editor or the script file in the Project Explorer, and select '''Run As->SystemTap Script'''
+** click on the [[Image:Run_exc.gif]] '''Run As...''' button on the toolbar
+** select either '''Run->Run''' or '''Run->Run As->SystemTap Script''' on the menu bar
+** press Ctrl+F11 on the keyboard
-[[Image:chartbox1.png]]
+If any of these options are used when a Run Configuration is not yet created for the script, a new one with default settings will be created for it. If multiple Run Configurations exist, you will be prompted to select which one to run the script with.
-For this example enter the following:
+[[Image:Multiconfigs.png]]
-<pre>	Columns: 3
-	TITLE	REGULAR EXPRESSION	DELIMITER
+If you know which Run Configuration you want to use, you may simply click the arrow next to the [[Image:Run_exc.gif]] '''Run As''' button on the toolbar and select from a list of recently-run configurations.
-	Time		\d+		.*			\D+
-	Read		\d+		.*			\D+
-	Write		\d+		.*			\D+
+[[Image:RunConfigDropDown.png]]
+To create a new Run Configuration, right-click on the script editor or the script file in the Project Explorer then select '''Run As -> Run Configurations...'''. Once the dialogue pops up, double click on the SystemTap tree item and you should be presented with the following dialogue:
+[[Image:SystemTapRunConfiguration.png]]
+Here you can specify the path of the script to run, enter remote host information, run as a different user, as well as various other options for running SystemTap. Explore the various tabs and options. The tooltips should provide help in understanding what the various options do. When you are ready, click Run to run your script.
+Now we will demonstrate running SystemTap scripts with graphs. In order to run the chart example you'll need to use the code provided in [[#Lesson_2:_Writing_Your_First_Script | Lesson 2: Writing Your First Script]]:
+<pre>global read, write, start
+probe begin {
+	start = gettimeofday_s()
+}
+probe syscall.write {
+	write += count
+}
+probe syscall.read {
+	read += count
+}
+probe timer.ms(1000) {
+	printf("%d\t%d\t%d\n", (gettimeofday_s()-start), read, write)
+	read=0
+	write=0
+}
 </pre>
+To do this, select '''Run As -> Run Configurations...''' and create a new SystemTap Launch Configuration as you did previously and switch to the Graphing tab. By the end of this tutorial, the tab will look like this:
-The title fields simply display the associated string in the column's header. After clicking OK the script will prompt you for details regarding the Remote Server. Provide the ip address of the remote server that is running the systemtapgui Server or the Data Management Daemon. The port is by default 22462. Enter a username and password.This will give the application permissions to run your script on the remote machine. You have the option of saving your password as well, however be warned this is currently NOT encrypted so this convenience runs at a risk. The username is also used to transfer the file to the remote system using SCP. If the same machine is used as both the server and the client enter 'localhost' for the Host field. When the script is executed the application will switch into the Graphing perspective. A Data View chart is populated with live data, in addition to the output in the console.  You should see a screen similar to the following:
+[[Image:GraphingTab.png]]
-[[Image:IDEGraphics.png]]
+The following instructions will walk you through the steps towards configuring the graph settings as shown above.
-You will see that the data table poplulates from live data parsed from the console. Now we'll make a graph to briefly illustrate the Graphing perspective. Click the Create Graph button next to bring up the Select Chart dialogue.Select line graph. You will be prompted to select a column of the X series and Y series; select "Time" and "Write" respectively. After you click ok you should see the line graph as follows:
+First, select '''Graph the output of this script run''', and in the text box labeled '''Regular Expression''', enter a regular expression that will match the output of your script. Place parentheses () around whatever data you want to capture for graphing.
-[[Image:IDEGraph.png]]
+For this example, enter the following as your '''Regular Expression''':
+<pre>(\d+)\t(\d+)\t(\d+)
+</pre>
+Alternatively, you can click the button labeled '''Click here to generate regular expressions from printf statements.''' Clicking this button will automatically create regular expressions that will capture output created by the script's printf statements.
+[[Image:AutoGraphAfter.png]]
+This expression will capture the output produced by the example script. Note that in order to capture data from script output, the output must be formatted into lines/rows. Output-parsing regular expressions try to match individual lines of script output, so make sure your scripts print a line break ("\n") to mark the end of a line. (The line break character does not need to be included in the regular expression.)
+Once this expression is entered, a table of '''Title'''s and '''Sample Extracted Value'''s will appear. To test that your regular expression is working as intended, you may enter as '''Sample Output''' a line of text similar to what you expect your script to produce.
+For this example, copy and paste the following line into the '''Sample Output''' box:
+<pre>10	1000	100
+</pre>
+and enter the following as '''Titles''':
+<pre>Time
+Reads
+Writes
+</pre>
+The text boxes displayed under '''Sample Extracted Value''' now show you the values that are captured by your regular expression, which will be plotted in any graphs you create that use those values.
+Now to add a graph using the parsed output, click the '''Add...''' button in the Graph Set section, which will bring up the [[#Create_Graph_Wizard | Create Graph]] wizard. Select a line graph as the '''Graph Type''', and enter the following as your Title and series values, then click '''Finish''' to save your changes:
+<pre>Title:		Read Write Count
+X Series:	Time
+Y Series 0:	Reads
+Y Series 1:	Writes
+</pre>
+You may also specify additional regular expressions to capture output with. To do this, either press the Down arrow key while typing into the '''Regular Expression''' text box, or click the drop-down arrow of the text box and click the entry labeled '''New Regular Expression...'''
+[[Image:SystemtapNewRegex.png]]
+You will notice that all data entered in the Graphing menu so far, such as the sample output and graphs, will no longer visible after adding a new regular expression. This is because each regular expression has its own sample output, column titles, and set of graphs (or Graph Set) associated with it. Data for the currently-selected expression is displayed, and since the current expression is blank, so are the column & graph settings.
+To capture the example script's output only at intervals of 10 units of time, use the line below as your second regular expression:
+<pre>(\d+0)\t(\d+)\t(\d+)
+</pre>
+Enter the same sample output & title values that were used for the first regular expression. Also add a graph with the same series data as before, and with a title of "Decade Read Write Counts".
+When the script is executed under this Run Configuration, the Graph Selector view is opened and it will contain a Data View and any graphs you have created, with a tab for each regular expression's set of graphs. The Data View chart is populated with the output from the console. If you click on the tab labeled '''Graph Set 1''', you should see a screen similar to the following:
+[[Image:SystemtapGraphView.png]]
+Switch between the graphs in Graph Set 1 and 2 to see the difference between the two graphs you plotted. If you click on the '''Data View''' tab of either Graph Set, you will see that the data that is being parsed live from the console:
-Note that the multiple series graphs (Multi-Line, Multi-Bar, and Multi-Scatter) will request two Y series, Y1 and Y2. In the case of our example, these would be "Read" and "Write". Each series will be assigned a different color value for the purposes of differentiation and will be plotted both in respect to the specified X series.
+[[Image:SystemtapGraphDataView.png]]
-Those are the basics behind running a script in Systemtap GUI.
+You may also create new graphs while in this view, to display data captured by your regular expressions in alternate ways. To create a new graph, first select the Graph Set you want to add a new graph to, then click on the [[Image:New_wiz.gif]] '''Create Graph''' button, which appears to the left of the Data View tab. This will bring up the same [[#Create_Graph_Wizard | Create Graph]] wizard that appears when creating a graph in a script's Run Configurations menu.
 == Concepts ==
-=== SystemTap Perspectives ===
-SystemTap has three perspectives, each with its own purpose.
-* [[Image:ide.png]] '''IDE Perspective''' - This is the primary perspective for SystemTap script writers. It contains the [[#Function_Browser | Function Browser ]], [[#Kernel_Browser | Kernel Browser ]], [[#Probe_Alias_Browser | Probe Alias Browser ]], and [[#Views_and_Editors | Views and Editors ]]. The IDE Perspective contains the features necessary execute SystemTap scripts and the syntax highlighting and code
+=== SystemTap IDE Perspective ===
-completion features that facilitate efficient development of scripts.
-* [[Image:graphing.png]] '''Graphing Perspective''' - This perspective is invoked when the user calls the Run /w Chart option. It defaults to showing a data table containing the script results and is capable of producing six different chart types: Scatter Graph, Line Graph, Area Graph, Bar Graph, Pie Graph.
+This is the primary perspective for SystemTap script writers. It contains the [[#Function_Browser | Function Browser]], [[#Kernel_Browser | Kernel Browser]], [[#Probe_Alias_Browser | Probe Alias Browser]], and [[#Views_and_Editors | Views and Editors]]. The IDE Perspective contains the features necessary execute SystemTap scripts and the syntax coloring and code completion features that facilitate efficient development of scripts.
-* [[Image:dash.png]]'''Dashboard Perspective''' - This perspective is capable of storing meta-data related to each graph such as filters, aggregates, and display options in addition to showing a "dashboard" interface with multiple graphs updating simultaneously.
 === STP Editor ===
-This editor is the most commonly used; it is used for the authoring and editing of Systemtap scripts. It is invoked when the user starts a new file or opens a file with the .stp extension. It provides syntax highlighting, code completion, and run support.
+This editor is the most commonly used; it is used for the authoring and editing of SystemTap scripts. It is invoked when the user starts a new file or opens a file with the .stp extension. It provides syntax highlighting, code completion, and run support.
 [[Image:Editor.png]]
-See also: [[#Menus | Menus ]],
+See also: [[#Menus | Menus]],
-[[#Example_SystemTap_Scripts | Example SystemTap Scripts ]], [[#Toolbars | Toolbars ]]
+[[#Example_SystemTap_Scripts | Example SystemTap Scripts]], [[#Toolbars | Toolbars]]
 === Function Browser ===
-The Funtion Browser lists all of the functions that are defined in the tapset library.  Functions are grouped by the file that they are defined.  Each listed function has an icon that corresponds to its return type.
-* [[Image:var_str.gif]] String
+The Function Browser lists all of the functions that are defined in the tapset library. Functions are grouped by the file that they are defined. Each listed function has an icon that corresponds to its return type.
-* [[Image:var_long.gif]] Long
-* [[Image:var_void.gif]] Void
-If you double click on any function a call to that function will be added to the active editor at the current cursor location.  Also if you right click on a function and click "View Definition" the tapset file where the function is defined will be opened.
+* [[Image:Var_str.gif]] String
+* [[Image:Var_long.gif]] Long
+* [[Image:Var_void.gif]] Void
+* [[Image:Var_unk.gif]] Unknown
-[[Image:function.png]]
+If you double click on any function a call to that function will be added to the active editor at the current cursor location. Also if you right click on a function and click '''View Definition''' the tapset file where the function is defined will be opened.
+[[Image:Function.png]]
 The default behavior of this view is to look for functions in the tapset library in the local machine. To look for functions in the same machine used to run the SystemTap scripts, go to Window->Preferences, select SystemTap->SystemTap IDE and check the ''Use remote connection to load SystemTap probes and functions'' option. Don't forget to configure the remote server used by remote execution in SystemTap->Remote Server.
 === Kernel Browser ===
-The Kernel Source Browser is used to display the kernel tree.  This provides you with a quick way to locate places to add probes.  Any file in the Kernel Source tree can be opened by double clicking on it.  This will open up the selected file in the Editor view.  You can then double click on the ruler next to any line that you wish to probe.  If SystemTap can probe that line a probe point will be inserted at the end of the script you were most recently working on.  If the line can't be probed, an error message will be displayed.
+The Kernel Source Browser is used to display the kernel tree. This provides you with a quick way to locate places to add probes. Any file in the Kernel Source tree can be opened by double clicking on it. This will open up the selected file in the Editor view. You can then double click on the ruler next to any line that you wish to probe. If SystemTap can probe that line a probe point will be inserted at the end of the script you were most recently working on. If the line can't be probed, an error message will be displayed.
 [[Image:KernelSource.png]]
-To use this feature it is necessary to configure the [http://wiki.eclipse.org/Linux_Tools_Project/Systemtap/User_Guide#Kernel_Source_Location Kernel Source Location].
+To use this feature it is necessary to configure the [http://wiki.eclipse.org/Linux_Tools_Project/SystemTap/User_Guide#Kernel_Source_Location Kernel Source Location].
 === Probe Alias Browser ===
-The Probe Alias Browser lists all of the probe aliases that are defined in the tapset library. Probes are grouped based on their type. In addition to the list of probes, each probe lists all of the variables that it has access to. Each variable is listed with an icon that represents its type. Types are as follows:
-* [[Image:Var str.gif]] String
+The Probe Alias Browser lists all of the probe aliases that are defined in the tapset library, as well as all static probes defined internally by SystemTap. Probes are grouped by name. In addition to the list of probes, each probe lists all of the variables that it has access to. Each variable is listed with an icon that represents its data type. Types are as follows:
-* [[Image:Var long.gif]] Long
-* [[Image:Var unk.gif]] Unknown
-If you double click on any probe alias, probe point will be added to the end of the active editor. Also if you right click on a probe and click "View Definition" the tapset file where the probe is defined will be opened.
+* [[Image:Var_str.gif]] String
+* [[Image:Var_long.gif]] Long
+* [[Image:Var_struct.gif]] Struct
+* [[Image:Var_unk.gif]] Unknown
+If you double click on any probe alias, probe point will be added to the end of the active editor. Also if you right click on a probe and click '''View Definition''' the tapset file where the probe is defined will be opened.
 [[Image:ProbeAlias.png]]
@@ Line 230: / Line 291: @@
 == Tasks ==
 === Creating SystemTap Scripts ===
-Create a SystemTap script by selecting '''<u>F</u>ile-><u>N</u>ew''' in the IDE Perspective. You'll be prompted to enter a name for the file; ''make sure that you use a .stp extension or else SystemTap GUI will not recognize the file as a SystemTap script and certain editor and run features will not be active.''
+Create a SystemTap script by selecting '''File -> New -> Other... -> SystemTap -> SystemTap Script''' from the menu bar. You'll be prompted to enter a name for the file; ''make sure that you use a .stp extension or else the SystemTap IDE will not recognize the file as a SystemTap script and certain editor and run features will not be active.''
 Your new file will be open and ready for coding in the Editor pane.
-A [[#IDE_Tutorial | IDE Tutorial ]] is also provided in the help pages for a step by step demo.
+A [[#IDE_Tutorial | IDE Tutorial]] is also provided in the help pages for a step by step demo.
-For advanced SystemTap langauge help please see the SystemTap Development User's Guide and the documentation available at the SystemTap website's documentation page -  http://sourceware.org/systemtap/documentation.html
+For advanced SystemTap language help please see the SystemTap Development User's Guide and the documentation available at the SystemTap website's documentation page - http://sourceware.org/systemtap/documentation.html
 === Using the STP Editor ===
-The STP Editor is used for the authoring and editing of Systemtap scripts. It is invoked when the user starts a new file or opens a file with the .stp extension. Using the editor is as easy as setting the focus to the editor pane and typing.
+The STP Editor is used for the authoring and editing of SystemTap scripts. It is invoked when the user starts a new file or opens a file with the .stp extension. Using the editor is as easy as setting the focus to the editor pane and typing.
 [[Image:Editor.png]]
 There are certain features within the editor you may want to take advantage of:
-* Syntax Highlighting - Certain code items are colored in .stp and .c files based on a set of rules and
+* Syntax Highlighting - Certain code items are colored in .stp and .c files based on a set of rules and colors.
-colors. You can turn this on or off and change the colors in '''<u>W</u>indow-><u>P</u>references'''.
+* Code Assist - SystemTap IDE will attempt to finish your probe alias names based on what you have already typed. You can then select the appropriate probe alias or continue typing to filter the list down even more.
-* Code Assist - SystemTap GUI will attempt to finish your probe alias names based on what you have already
+* Run Support - See the [[#Lesson_3:_Running_Your_Script | Lesson 3: Running Your Script]] help page on a walk through use of the Run command. The Run command allows scripts to be executed directly through SystemTap IDE.
-typed. You can then select the appropriate probe alias or continue typing to filter the list down even more.
-You can turn this feature on and off or set the speed on it in '''<u>W</u>indow-><u>P</u>references'''.
+See also: [[#Menus | Menus]], [[#Toolbars | Toolbars]], [[#Example_SystemTap_Scripts | Example SystemTap Scripts]]
-* Run Support - See the [[#Lesson_3:_Running_Your_Script | Lesson 3: Running Your Script ]]
-help page on a walk through use of the Run command. The Run command allows scripts to be executed directly
+=== Creating Run Configurations ===
-through SystemTap GUI.
+Advanced options for running SystemTap scripts are available in the '''Run Configurations''' menu. This menu may be accessed by right-clicking a script and choosing '''Run As->Run Configurations''' from the context menu, by selecting '''Run->Run Configurations''' in the menu bar, or by using the drop-down menu next to the [[Image:Run_exc.gif]] '''Run''' toolbar button.
+==== Local/Remote Runs ====
+It is possible to run scripts either locally or remotely, and as different users. To configure these settings, use the '''General''' tab of the Run Configurations menu.
+The following options are available:
+* '''Execute script as current user''' - Uncheck this box to run the script as a different user. While unchecked, you may enter the '''User Name''' and '''Password''' of the user you wish to run the script as.
+* '''Run script on localhost''' - Uncheck this box to run the script on a remote machine. Type the name of the desired host to use in '''Host Name'''. (This option is only available when running as a non-current user.)
+* '''Use default port''' - When unchecked, you may specify the port that is to be used for remote communication. The default port is 22. (This option is only available when running on a non-local host.)
+==== SystemTap Options ====
+The '''SystemTap''' tab allows for the specification of many command-line options to the stap command that is to be run. View the SystemTap manual for information on these options - https://sourceware.org/systemtap/man/stap.1.html
+==== Graphing ====
-See also: [[#Menus | Menus ]],
+Many options and features are available in the '''Graphing''' tab for creating graphs out of a script's output. For detailed information on how to create graphs, refer to [[#Lesson_3:_Running_Your_Script | Lesson 3: Running Your Script]] and the [[#Graphing_Tutorial | Graphing Tutorial]].
-[[#Toolbars | Toolbars ]], [[#Example_SystemTap_Scripts | Example SystemTap Scripts ]]
 === Viewing Data Charts ===
-Viewing data charts from a SystemTap script is accomplished by running that script with the '''<u>R</u>un-><u>R</u>un w/ Chart''' option. This is covered in the [[#Lesson_3:_Running_Your_Script | Lesson 3: Running Your Script ]]. After running a script with the chart option, the user is taken into the Graphing Perspective and the Data Table is loaded by default. The data table immediately begins populating as it recieves input back through the console from the running SystemTap script.
-[[Image:IDEGraphics.png]]
+Viewing data charts from a SystemTap script is accomplished by running that script with the Run Configurations containing your graphs. This is covered in [[#Lesson_3:_Running_Your_Script | Lesson 3: Running Your Script]]. After running a script with the graphing option, the user is presented with the Graph Selector View, and the last graph of the final Graph Set is loaded by default. When that view appears, click on the Data View tab of any Graph Set to see it begin populating as it receives input back through the console from the running SystemTap script.
+[[Image:SystemtapGraphDataView.png]]
 == Reference ==
 === Views and Editors ===
-This section details the views and editor in relation to the IDE Perspective.
+This section details the views and editor in relation to the SystemTap IDE.
 ==== Views ====
@@ Line 271: / Line 352: @@
 The IDE Perspective consists of 5 views and and two editors.
-* '''Probe Alias Browser''' - A list of all probe aliases currently available in your version of Systemtap. Covered in detail [[#Probe_Alias_Browser | here ]].
+* '''Probe Alias Browser''' - A list of all probe aliases currently available in your version of SystemTap and all active tapsets. Covered in detail [[#Probe_Alias_Browser | here]].
-* '''Function Browser''' - A list of functions currently supported in your version of Systemtap. Covered in detail [[#Function_Browser | here ]].
+* '''Function Browser''' - A list of functions currently supported in your version of SystemTap and all active tapsets. Covered in detail [[#Function_Browser | here]].
-* '''Kernel Source Browser''' - Used to display the kernel tree. Covered in detail [[#Kernel_Browser | here ]].
+* '''Kernel Source Browser''' - Used to display the kernel tree. Covered in detail [[#Kernel_Browser | here]].
-* '''Console''' - The console view is where all of the output from the running script is shown. If more then one script is running at the same time you are able to switch between which console is currently displayed by clicking on the "Display Selected Console" button. The script can halt execution here if the user selects the '''Stop''' button. The user also has the option of saving the console output to a file, which can be done by clicking the '''Save log output''' button at the top of the console.[[Image:IDEConsole.png]]
+* '''Console''' - The console view is where all of the output from the running script is shown. If more then one script is running at the same time you are able to switch between which console is currently displayed by clicking on the '''Display Selected Console''' button. The script can halt execution here if the user selects the '''Stop''' button. The user also has the option of saving the console output to a file, which can be done while the script is running by clicking the '''Save log output''' button at the top of the console.
-* '''Error Log''' - If the script you tried to run contained errors, this view will become active and display the errors. You can double click on the eror message to jump to the line in the file where the error occured. [[Image:ErrorLog.png]]
+[[Image:IDEConsole.png]]
+* '''Error Log''' - If the script you tried to run contained errors, this view will become active and display the errors. You can double click on the error message to jump to the line in the file where the error occurred.
+[[Image:ErrorLog.png]]
 ==== Editors ====
-Three editors are available in Systemtap GUI.
+Three editors are available in the SystemTap IDE.
-* '''STP Editor''' - This editor is the most commonly used; it is used for the authoring and editing of Systemtap scripts. It is invoked when the user starts a new file or opens a file with the .stp extension. It provides syntax highlighting, code completion, and run support.
+* '''STP Editor''' - This editor is the most commonly used; it is used for the authoring and editing of SystemTap scripts. It is invoked when the user starts a new file or opens a file with the .stp extension. It provides syntax highlighting, code completion, and run support.
 * '''C Editor''' - This editor is available for the read only viewing of kernel source. It is invoked when the user opens a file of extension .c. Syntax highlighting is supported in this mode.
 * '''Plain Text Editor''' - A plain text editor is also implemented for the user should they need it.
 === Menus ===
-What follows is a comprehension list of the menu options available within the IDE Perspective of Systemtap GUI.
-==== File ====
+What follows is a comprehension list of the menu options available within the SystemTap IDE.
-* '''<u>N</u>ew File''' - This option will bring up a dialog to create a new file. You may specify any location. Files ending in a .stp or .c extension will have syntax highlighting and code completion features as appropriate. (Shortcut: Crtl+L)
-[[Image:newbox1.png]]
-* '''<u>O</u>pen File''' - This option will bring up a dialog to select a file to open.  Once a file is selected it will open in the editor window. (Shortcut: Crtl+O)
-[[Image:openbox1.png]]
-* '''<u>C</u>lose''' - This option closes the file in the editor pane that currently has the focus. (Shortcut: Crtl+F4)
-* '''C<u>l</u>ose All''' - This option closes all files in the editor pane. (Shortcut: Shift+Crtl+F4)
-* '''<u>S</u>ave''' - This option saves the file that currently has the focus. (Shortcut: Crtl+S)
-* '''Save <u>A</u>s''' - This option prompts the user for a new location and file name and saves the file that currently has the focus under that new name and location.
-* '''Sav<u>e</u> All''' - This option saves all files currently open in the editor pane. (Shortcut: Shift+Crtl+S)
-* '''Rever<u>t</u>''' - This option discards changes to the file currently under the focus replaces it with the last saved version.
-* '''<u>P</u>rint''' - This option prints the file in the editor pane currently holding the focus. (Shortcut: Crtl+P)
-* '''<u>E</u>xport Script''' - This option prompts the user to enter metadata associated with the Systemtap script to be exported and used in the Dashboard perspective. See the [[#Creating_Modules | Creating Modules guide]] for instructions.
-* '''<u>I</u>mport Tapset''' - This option allows you to include additional tapset directories when you run a script. (Shortcut: Crtl+I)
-[[Image:importbox1.png]]
-* '''E<u>x</u>it''' - Exits Systemtap GUI.
 ==== Edit ====
-* '''<u>U</u>ndo''' - Undos the previous editor related action.  (Shortcut: Crtl+Z)
+* '''<u>U</u>ndo''' - Undos the previous editor related action. (Shortcut: Ctrl+Z)
-* '''<u>R</u>edo''' - Redos the previous editor related action removed by Undo.  (Shortcut: Crtl+Y)
+* '''<u>R</u>edo''' - Redos the previous editor related action removed by Undo. (Shortcut: Ctrl+Y)
-* '''Cu<u>t</u>''' - Removes the selected text from the editor pane and places it in the clipboard.  (Shortcut: Shift+Delete, Ctrl+X)
+* '''Cu<u>t</u>''' - Removes the selected text from the editor pane and places it in the clipboard. (Shortcut: Shift+Delete, Ctrl+X)
-* '''<u>C</u>opy''' - Copies the selected text from the editor pane and places it in the clipboard.  (Shortcut: Ctrl+Insert, Crtl+C)
+* '''<u>C</u>opy''' - Copies the selected text from the editor pane and places it in the clipboard. (Shortcut: Ctrl+Insert, Ctrl+C)
-* '''<u>P</u>aste''' - Copies the text from the clipboard to the location of the focus in the editor pane.  (Shortcut: Shift+Insert, Crtl+V)
+* '''<u>P</u>aste''' - Copies the text from the clipboard to the location of the focus in the editor pane. (Shortcut: Shift+Insert, Ctrl+V)
-* '''Select <u>A</u>ll''' - Selects all text within the file in the editor that the focus is currently in.  (Shortcut: Crtl+A)
+* '''Select <u>A</u>ll''' - Selects all text within the file in the editor that the focus is currently in. (Shortcut: Ctrl+A)
 * '''<u>F</u>ind/Replace''' - Opens the Find/Replace dialogue in which users may specify a text string to find and/or replace, with options to search forwards or backwards, the entire document or just the selected lines, and whether or not they want the following options:
 ** Case sensitive
@@ Line 318: / Line 388: @@
 ** Incremental
 ** Regular expressions
-(Shortcut: Crtl+F)
+(Shortcut: Ctrl+F)
-[[Image:findbox1.png]]
-* '''Find <u>N</u>ext''' - Finds the next instance of the search string in the direction indicated in the Find/Replace dialogue box. (Shortcut: Crtl+K)
+[[Image:Findbox1.png]]
-* '''Find Pre<u>v</u>ious''' - Finds the previous instance of the search string in the direction indicated in the Find/Replace dialogue box. (Shortcut: Shift+Crtl+K)
+* '''Find <u>N</u>ext''' - Finds the next instance of the search string in the direction indicated in the Find/Replace dialogue box. (Shortcut: Ctrl+K)
+* '''Find Pre<u>v</u>ious''' - Finds the previous instance of the search string in the direction indicated in the Find/Replace dialogue box. (Shortcut: Shift+Ctrl+K)
 * '''<u>I</u>ncremental Find Next''' - Finds the next occurrence of the text and updates the selection after each character typed. To use Incremental Find:
 ** In the text (or Java) editor, press Ctrl+J or select Edit > Incremental Find Next from the menu bar.
-** The workbench status line displays "Incremental Find:". The editor is now in the Incremental Find mode.
+** The workbench status line displays '''Incremental Find:'''. The editor is now in the Incremental Find mode.
 ** As you type, the editor finds the next occurrence of the text and updates the selection after each character typed.
 ** Navigate to the next or previous match by pressing Arrow Down or Arrow Up.
 ** Undo the last action within the Incremental Find mode by pressing Backspace.
 ** You can leave the Incremental Find mode by pressing Esc
-* '''Incre<u>m</u>ental Find Previous''' - Operates as illustrated in above bullet but in the reverse. (Shortcut: Shift+Crtl+J)
+* '''Incre<u>m</u>ental Find Previous''' - Operates as illustrated in above bullet but in the reverse. (Shortcut: Shift+Ctrl+J)
 * '''Select <u>A</u>ll''' - Selects all the text in the file that currently has the focus. (Shortcut: Ctrl+A)
 * '''<u>W</u>ord Completion''' - Completes the string being typed by using the last example typed by the user. (Shortcut: Alt+/)
@@ Line 336: / Line 407: @@
 * '''<u>F</u>orward''' - Navigates to the next file in sequence as they were opened in the editor pane. (Shortcut: Alt+Right)
 * '''<u>B</u>ack''' - Navigates to the previous file in sequence as they were opened in the editor pane. (Shortcut: Alt+Left)
-* '''Last Edit Lo<u>c</u>ation''' - Moves the focus to the file containing the last known edit. (Shortcut: Crtl+Q)
+* '''Last Edit Lo<u>c</u>ation''' - Moves the focus to the file containing the last known edit. (Shortcut: Ctrl+Q)
-* '''<u>G</u>oto Line...''' - Moves the focus to the specified line number, with the range of line numbers listed in the dialogue box. (Shortcut: Ctrl+L)[[Image:gotobox1.png]]
+* '''<u>G</u>oto Line...''' - Moves the focus to the specified line number, with the range of line numbers listed in the dialogue box. (Shortcut: Ctrl+L)
+[[Image:Gotobox1.png]]
 ==== Run ====
-* '''<u>R</u>un''' - Available when a Systemtap script is loaded into the editor, this feature runs the script. You will be prompted to enter details of the remote machine running the systemtapgui server.ShortCut(Ctrl+F5)
+* '''<u>R</u>un''' - Available when a SystemTap script is loaded into the editor, this feature runs the script. You will be prompted to run the script either locally or on a remote machine. If run locally and multiple Run Configurations exist for the script, you will be prompted to choose which of them to run. (Shortcut: Ctrl+F11)
-[[Image:consolebox1.png]]
-* '''<u>R</u>un w/Chart''' - Available when a Systemtap script is loaded into the editor, this feature will prompt the user for the number of columns for the chart, in addition to their titles and regular expressions. The regular expressions are used to parse the console output for the script and determine the values of each column at a certain sample point. The combined regular expression is shown at the bottom of the dialogue box. The user has the option to use Command Line Options as well. When you click OK you will be prompted to enter the details of the remote machine running the systemtapgui server. When the script is executed the application will switch into the Graphing perspective. A Data View chart is populated with live data, in addition to the output in the console. More information regarding the Graphing perspective is available here.
+[[Image:Consolebox1.png]]
-[[Image:chartbox1.png]]
-* '''<u>S</u>top''' - This option terminates the script thread associated with whichever script currently has the focus. (Shortcut: Ctrl+F9)
 ==== Window ====
-* '''Open in <u>N</u>ew Window''' - This option opens a new instance of SystemTap GUI.
+* '''<u>N</u>ew Window''' - This option opens a new instance of the SystemTap IDE.
 * '''<u>O</u>pen Perspective''' - This submenu lists each of the available perspectives to open:
-** IDE Perspective
+** SystemTap IDE
-** Graphing Perspective
+** Other... - Lists all other perspectives available to Eclipse.
-** Dashboard Perspective
 * '''Show <u>V</u>iews''' - This submenus lists each of the available views to open:
 ** Console
-** Error Log
 ** Functions
 ** Kernel Source
 ** Probe Alias
-** Other - Lists all views in the application.
+** SystemTap Error Log
-[[Image:viewbox1.png]]
+** Other... - Lists all views in the application.
-* '''<u>P</u>references''' - Due to the breath of this topic it is covered in another section. Please see [[#Preferences | Preferences ]].
+* '''<u>P</u>references''' - Due to the breath of this topic it is covered in another section. Please see [[#Preferences | Preferences]].
 === Toolbars ===
-SystemTap GUI currently has two toolbars built in; an Action Bar for file and execution operations and a Perspective Selector to jump to different perspectives.
 ==== Action Bar ====
-* [[Image:new_wiz.gif]] '''New File''' - This button will bring up a dialog to create a new file.  When you click ok the file will be opened in the editor window.
+* [[Image:New_wiz.gif]] '''New File''' - This button will bring up a dialogue to create a new file. When you click OK the file will be opened in the editor window.
-* [[Image:open_wiz.gif]] '''Open File''' - This button will bring up a dialog to select a file to open.  Once a file is selected it will open in the editor window.
+* [[Image:Run_exc.gif]] '''Simple Run''' - This will compile the open script and start running it, without using a Run Configuration. All output will be sent to the console. If there is an error in the script the error will be reported in the Error Log.
-* [[Image:import_wiz.gif]] '''Import Tapset''' - This button allows you to include additional tapset directories when you run a script.
+* [[Image:Run_exc.gif]] '''Run As''' - This compiles & runs the current script, but also searches for a Run Configuration that targets the script, and runs the script with the launch options provided by it. Use this instead of Simple Run when you want graphs to be plotted. (Shortcut: Ctrl+F11)
-* [[Image:run_exc.gif]] '''Run Script''' - This will compile the open script and start running it.  All output will be sent to the console.  If there is an error in the script the error will be reported in the ErrorLog.
-* [[Image:run_chart.gif]] '''Run Script w/Chart''' - This button is also like the standard Run Script button but will bring up a charting dialog box.  Once the formatting expressions have been entered it will change the current perspective to the graphing perspective.
-* [[Image:stop_obj.gif]] '''Stop Script''' - This button will stop the currently active script from running.
-==== Perspective Selector ====
+=== Preferences ===
-* [[Image:ide.png]] '''IDE Perspective''' - This button brings you into the IDE Perspective, useful for writing and executing scripts.
+This section details each of the options listed under '''<u>W</u>indow-><u>P</u>references'''. The Preferences dialog is used to set user preferences. Its pages can be searched using the filter function. To filter by matching the page title, simply type the name of the page you are seeking in the text box in the top-left corner of the dialog, and the available pages will be presented in the list below. The filter also searches on keywords such as "appearance" and "Java".
-* [[Image:graphing.png]] '''Graphing Perspective''' - This button brings you into the Graphing Perspective, useful for graphing scripts.
-=== Preferences ===
-This section details each of the options listed under '''<u>W</u>indow-><u>P</u>references'''. The Preferences dialog is the dialog used to set user preferences. The Preferences dialog pages can be searched using the filter function. To filter by matching the page title, simply type the name of the page you are seeking and the available pages will be presented below. The filter also searches on keywords such as appearance and java.
-* '''Logging'''
+* '''SystemTap''' - This section contains options relevant to SystemTap itself.
-** '''Enable logging''' - This option turns on and off the ability to log data from the console.
-** '''Logging level''' - This dropdown box allows you to select one of our levels of logging.
-*** Debug - A very large quantity of debug information, difficult to identify what you are looking for but extremely exhaustive.
-*** Info - Displays most information regarding program execution; the default level.
-*** Critical - Lists only critical errors duration execution.
-*** Fatal - Lists only fatal errors during execution.
-** ''Log to''' - Specifies where you wish the logging to be written:
-*** Console - Writes the debug information directly to the console.
-*** File - Write the debug information to a file.
-** '''File''' - The location of the file that logging sends the debug information to.
-* '''SystemTap''' - This section contains options relevent to SystemTap itself.
-** '''Remember window state''' - Preserves the state of the window on exitting SystemTap GUI.
-** '''Dashboard Preferences''' - Preferences relate to the Dashboard Perspective.
-*** Additional Modules - Provides for the addition of more modules to the Dashboard. Modules are files containing a SystemTap script and associated metadata.
 ** '''Environment Variables''' - Allows the user to set specific values to the following environment variables
 *** LD_LIBRARY_PATH
@@ Line 403: / Line 450: @@
 *** SYSTEMTAP_RUNTIME
 ** '''Graphing''' - Preferences related to the Graphing Perspective.
-*** '''<u>R</u>efresh Delay (ms)''' - Milliseconds in between re-painting the graph.
+*** '''<u>R</u>efresh Delay (ms)''' - Milliseconds between graphs are updated with the latest data.
 *** '''Data Table''' - Preferences related to the data table.
 **** <u>J</u>ump to the newest entry - Determines whether the scroll bar maintains its location at the newest entry.
-**** <u>A</u>uto resize columns - Determines whether columns automatically resize to the width of the contents or whether they remain placed when moved.
+**** <u>A</u>uto resize columns - Determines whether columns automatically resize to the width of the contents or whether they can be adjusted by the user.
 **** <u>M</u>ax data items - Maximum number of entries that the table shows, though the table itself may have more not visible.
 *** '''Graph''' - Preferences related to graphs.
-**** <u>S</u>how grid lines - Turns on and off painting of the grid lines.
+**** <u>S</u>how X/Y grid lines - Turns on and off painting of the grid lines for either axis.
+**** <u>M</u>ax data items - Number of maximum samples read from a script's output.
 **** <u>V</u>iewable data items - Number of maximum samples plotted at any time.
+**** <u>X</u>/<u>Y</u> series ticks - Specify the number of labeled number markers on either axis.
 ** '''IDE''' - Preferences when loading the IDE Perspective.
-*** '''Use stored tapset trees''' - Loads the stored tapset trees on initialization.
+*** '''Use stored tapset trees''' - If checked, the next initialization of SystemTap IDE will load all tapset contents (probes & functions) from a local configuration file instead of having to search for them manually. This configuration file is saved whenever changes to tapsets are made while this box is checked, or when it is checked for the first time.
-*** '''Editor''' - Preferences related to the editor.
+*** '''Use remote connection to load SystemTap probes and functions''' - If checked, tapset contents (probes & functions) will be loaded from a remote machine (specified in Remote Server) instead of the local machine.
-**** <u>E</u>ditor Background Color - Sets the color painted in the background of the editor pane.
+*** '''Kernel Source Path''' - Location of the directory that the kernel source code is pulled from. A local or remote machine may be used.
-**** Show Line <u>N</u>umbers - Option to turn on and off line numbers in the editor pane.
+**** Tapsets - Preferences related to tapsets.
-**** Code Assist
+***** <u>A</u>dditional Tapsets - Allows you to specify additional tapsets scripts to be added in with every script, and to be displayed in the Function and Probe Alias Browsers.
-***** <u>U</u>se Code Assist - Turns on and off the option to use Code Assist, which is a method that predicts what you are typing based on existing probe alias and opens a window that allows you to scroll down and select and/or continue typing for refined results.
+** '''Remote Server''' - Details regarding running SystemTap on a remote machine. Any operations that run SystemTap on a remote machine will use the one specified by the credentials provided here.
-***** How Code Assist adds code - Method used in Code Assist.
+*** '''Host Name''' - IP address of the remote machine.
-****** <u>I</u>nsert - Inserts the selected text directly into the cursor point.
-****** <u>O</u>verwrite - Overwrites as you type.
-***** Activation <u>D</u>elay (requires restart) - Delay in milliseconds before the code assist routines attempts to run.
-***** Activation <u>T</u>rigger - This is the key that actives Code Assist. For SystemTap GUI it is set to the divider between tapset and probe alias.
-**** Syntax Coloring - These options assign color values to identified types within the .stp and .c editors.
-***** STP editor
-****** <u>D</u>efault Color - Color of normal code.
-****** <u>K</u>eyword Color - Color of keywords.
-****** <u>E</u>mbedded C Color - Color of embedded C code.
-****** <u>E</u>mbedded Color - Color of embedded code.
-****** <u>C</u>omment Color - Color of comments.
-****** <u>T</u>ype Color - Color of items identified as types.
-****** <u>S</u>tring Color - Color of strings.
-***** C editor
-****** <u>D</u>efault Color - Color of normal code.
-****** <u>K</u>eyword Color - Color of keywords.
-****** <u>P</u>reprocessor Color - Color of preprocessor code.
-****** <u>C</u>omment Color - Color of comments.
-****** <u>T</u>ype Color - Color of items identified as types.
-****** <u>S</u>tring Color - Color of strings.
-**** Typeing - No options available at this time.
-*** '''Path'''
-**** <u>K</u>ernel Source Directory - Location of the directory that the kernel source code is pulled from.
-**** Stap - No options available at this time.
-***** Tapsets - Preferences related to tapsets.
-****** <u>A</u>dditional Tapsets - Allows you to specify additional tapsets scripts to be added in with every script.
-** '''Remote Server''' - Details regarding the remote machine running the systemtapgui Server
-*** '''Host Name''' - IP address of the remote machine
 *** '''Port''' - Port used for communication. Default is 22462.
 *** '''User Name''' - User name that has sufficient permissions to transfer and run the script on the remote machine.
 *** '''Password''' - Password for the above user.
 === Frequently Asked Questions ===
 This section details frequently asked questions relating to the IDE Perspective.
-'''Where can I find information regarding the Systemtap scripting language?'''
-A: The best place to look for up to date information regarding Systemtap itself is its homepage - http://sourceware.org/systemtap/documentation.html
+'''Where can I find information regarding the SystemTap scripting language?'''
+A: The best place to look for up to date information regarding SystemTap itself is its homepage - http://sourceware.org/systemtap/documentation.html
 '''How do I run a script once I've written it?'''
-A: There are different options as far as running your Systemtap script. Please visit the [[#Menus | Menus ]] to learn more about the four ways of running Systemtap scripts.
+A: There are two ways to run a script:
+-with the [[Image:Run_exc.gif]] Simple Run button on the toolbar, which runs the script that has editor focus. It will be run without drawing graphs or any other configurations.
+-by launching it with a Run Configuration that targets any specified script, even one that is not in the workspace.
+Read [[#Lesson_3:_Running_Your_Script | Lesson 3: Running Your Script]] and [[#Menus | Menus]] to learn more about the ways of running SystemTap scripts.
-'''Why does the application seem to hang when switching to the IDE Perspective?'''
-A: If this is the first time you are trying to open the IDE perspective, or have recently gotten a new version of SystemTap this is expected.  In order to generate a full list of all of the available probes, and functions the GUI has to run the stap command.  If there are tapsets that do not run correctly using the 'stap -up2' comamnd this takes a long time.  In order to build as complete a list as possible it will use a binary filtering algorithm to figure out which tapset function is broken and generate data for all of the others.
+'''Why does the application seem to hang when switching to the SystemTap IDE?'''
+A: If this is the first time you are trying to open the SystemTap IDE, or have recently gotten a new version of SystemTap this is expected. In order to generate a full list of all of the available probes and functions, the GUI has to run a background SystemTap process and parse the results. A future update to SystemTap IDE will reduce the duration of this operation.
 === Example SystemTap Scripts ===
-What follows is a few SystemTap Scripts that you may use in SystemTap GUI, taken from and linked to
+What follows is a few SystemTap Scripts that you may use in SystemTap IDE, taken from and linked to http://sourceware.org/systemtap/documentation.html
-http://sourceware.org/systemtap/documentation.html
 There is also a description of the examples - http://sourceware.org/systemtap/examples/demo_script.txt
@@ Line 479: / Line 505: @@
 <pre>
 #!/usr/bin/env stap
 #
-# This script continuously lists the top 20 systemcalls on the system
+# This script continuously lists the top 20 system calls on the system
 #
@@ Line 514: / Line 540: @@
 # This is an example of profiling a specific command or pid.
 # It works by recording the time when a system call is entered
 # exited.
 # Usage: prof.stp -c "top -n5"
@@ Line 540: / Line 566: @@
 	printf("\n")
 	foreach (x in ttime)
 		printf("%-20s\tcalls:%6d\tavg time (ms):%5d\ttotal(ms):%7d\n",
 			x, @count(ttime[x]), @avg(ttime[x]), @sum(ttime[x]))
 }
@@ Line 553: / Line 579: @@
 # This is not useful, but it demonstrates that
-# Systemtap can modify variables in a running kernel.
+# SystemTap can modify variables in a running kernel.
 # Usage: ./keyhack.stp -g
@@ Line 577: / Line 603: @@
 global kmalloc
 probe kernel.function("__kmalloc") {
 	kmalloc <<< $size
 }
@@ Line 605: / Line 631: @@
 global kmalloc
 probe kernel.function("__kmalloc") {
 	kmalloc[execname()] <<< $size
 }
@@ Line 629: / Line 655: @@
 === Guide to Regular Expressions ===
-Regular expressions are used in SystemTap GUI to define how the GUI interprets information that it recieves
+Regular expressions are used for SystemTap graphs to interpret information that it recieves from a script's output.
-from the script file. If the user wishes to change the regular expression during runtime they may do so by
-selecting '''<u>E</u>dit->Modify <u>P</u>arsing Expression'''.
 Basic regex (taken from "http://java.sun.com/j2se/1.5.0/docs/api/ ) -
@@ Line 638: / Line 662: @@
 Construct 	Matches
 Characters
 x 	The character x
@@ Line 654: / Line 678: @@
 \e 	The escape character ('\u001B')
 \cx 	The control character corresponding to x
 Character classes
 [abc] 	a, b, or c (simple class)
@@ Line 663: / Line 687: @@
 [a-z&&[^bc]] 	a through z, except for b and c: [ad-z] (subtraction)
 [a-z&&[^m-p]] 	a through z, and not m through p: [a-lq-z](subtraction)
 Predefined character classes
 . 	Any character (may or may not match line terminators)
@@ Line 672: / Line 696: @@
 \w 	A word character: [a-zA-Z_0-9]
 \W 	A non-word character: [^\w]
 POSIX character classes (US-ASCII only)
 \p{Lower} 	A lower-case alphabetic character: [a-z]
@@ Line 687: / Line 711: @@
 \p{XDigit} 	A hexadecimal digit: [0-9a-fA-F]
 \p{Space} 	A whitespace character: [ \t\n\x0B\f\r]
 java.lang.Character classes (simple java character type)
 \p{javaLowerCase} 	Equivalent to java.lang.Character.isLowerCase()
@@ Line 693: / Line 717: @@
 \p{javaWhitespace} 	Equivalent to java.lang.Character.isWhitespace()
 \p{javaMirrored} 	Equivalent to java.lang.Character.isMirrored()
 Classes for Unicode blocks and categories
 \p{InGreek} 	A character in the Greek block (simple block)
@@ Line 700: / Line 724: @@
 \P{InGreek} 	Any character except one in the Greek block (negation)
 [\p{L}&&[^\p{Lu}]]  	Any letter except an uppercase letter (subtraction)
 Boundary matchers
 ^ 	The beginning of a line
@@ Line 710: / Line 734: @@
 \Z 	The end of the input but for the final terminator, if any
 \z 	The end of the input
 Greedy quantifiers
 X? 	X, once or not at all
@@ Line 718: / Line 742: @@
 X{n,} 	X, at least n times
 X{n,m} 	X, at least n but not more than m times
 Reluctant quantifiers
 X?? 	X, once or not at all
@@ Line 726: / Line 750: @@
 X{n,}? 	X, at least n times
 X{n,m}? 	X, at least n but not more than m times
 Possessive quantifiers
 X?+ 	X, once or not at all
@@ Line 734: / Line 758: @@
 X{n,}+ 	X, at least n times
 X{n,m}+ 	X, at least n but not more than m times
 Logical operators
 XY 	X followed by Y
 X|Y 	Either X or Y
 (X) 	X, as a capturing group
 Back references
 \n 	Whatever the nth capturing group matched
 Quotation
 \ 	Nothing, but quotes the following character
 \Q 	Nothing, but quotes all characters until \E
 \E 	Nothing, but ends quoting started by \Q
 Special constructs (non-capturing)
 (?:X) 	X, as a non-capturing group
@@ Line 756: / Line 780: @@
 (?<=X) 	X, via zero-width positive lookbehind
 (?<!X) 	X, via zero-width negative lookbehind
 (?>X) 	X, as an independent, non-capturing group
 Match a position that is not a word boundary.
 </pre>
@@ Line 767: / Line 791: @@
 = SystemTap Graphing =
 == Getting Started ==
 === Introduction ===
-The Graphing Perspective in the SystemTap Plug-in is a perspective that is active once a user runs a script with the chart option ('''<u>R</u>un->Run w/ <u>C</u>hart'''). From this point a [[#DataTable | DataTable ]] is populated with live data as it is parsed from the Console. From the information in the DataTable you can generate the following graphs:
-* [[#Scatter_Graph | Scatter Graph ]]
+When 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 | IDE Tutorial]] in the SystemTap IDE User's Guide.) A variety of graph types are available for plotting the output of SystemTap scripts:
-* [[#Line_Graph | Line Graph ]]
-* [[#Area_Graph | Area Graph ]]
-* [[#Bar_Graph | Bar Graph ]]
-* [[#Pie_Graph | Pie Graph ]]
-These graph types can be used instantiated by using the Graph Wizard once the DataTable is populated. The Graphing Perspective can support multiple graphs from one DataTable. Each are updated and can be viewed by navigating through the tabs shown at the top of each graph.
+* [[#Scatter_Graph | Scatter Graph]]
+* [[#Line_Graph | Line Graph]]
+* [[#Area_Graph | Area Graph]]
+* [[#Bar_Graph | Bar Graph]]
+* [[#Pie_Graph | Pie Graph]]
-If you have not already, you will want to review the [[#Graphing_Tutorial | Graphing Tutorial ]]
+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 [[Image:New_wiz.gif]] [[#Create_Graph_Wizard | Create Graph]] wizard in the Graph Selector View. Please refer to [[#Lesson_3:_Running_Your_Script | 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 ===
-In order to graph SystemTap scripts you must have a script open in the IDE Perspective, and the '''<u>R</u>un-&gt;Run w/ Chart''' option must be used. 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. Please use the following script for this example by copying and pasting it into a new file (any name is fine that ends in a .stp extension):
+This tutorial picks up from where [[#Lesson_3:_Running_Your_Script | 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.
-<pre>global read, write, start
-probe begin {
+Once the Run Configuration menu is opened with your configuration selected, click on the '''Graphing''' tab. At the bottom of the window, a section labeled '''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:
-   start = gettimeofday_s()
-}
-probe syscall.write {
-   write += count
-}
-probe syscall.read {
+* '''Add...''' - Brings up the [[#Create_Graph_Wizard | Create Graph]] wizard to allow you to create a new graph.
-   read += count
+* '''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 [[#Create_Graph_Wizard | Edit Graph]] wizard.
+* '''Remove''' - Removes the currently selected graph.
-probe timer.ms(1000) {
+'''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.
-   printf("%d\t%d\t%d\n", (gettimeofday_s()-start), read, write)
-   read=0
-   write=0
-}
-</pre>
-Now select '''<u>R</u>un-&gt;Run w/ <u>C</u>hart'''. This feature will prompt the user for the number of columns for the chart, in addition to their titles and regular expressions. The regular expressions are used to parse the console output for the script and determine the values of each column at a certain sample point. The combined regular expression is shown at the bottom of the dialogue box. You should see the following:
+==== Create Graph Wizard ====
-[[Image:Chartbox1.png]]
+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.
-For this example enter the following:
+* '''Graph Type''' - The type of graph to draw. See [[#Data_Graph_Types | Graph Types]] for the list of graph types available, and an explanation of each.
-<pre>	Columns: 3
+* '''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 separate set of data points on your graph, labeled by title. When you do not want to include any extra Y series values, choose '''NA'''.
-	TITLE	REGULAR EXPRESSION	DELIMITER
+Note that two different series may not share the same data selection.
-	Time		\d+		.*			\D+
-	Read		\d+		.*			\D+
-	Write		\d+		.*			\D+
-</pre>
-The title fields simply display the associated string in the column's header. After clicking OK the script will prompt you for details regarding the Remote Server. Provide the ip address of the remote server that is running the systemtapgui Server or the Data Management Daemon. The port is by default 22462. Enter a username and password.This will give the application permissions to run your script on the remote machine. You have the option of saving your password as well, however be warned this is currently NOT encrypted so this convenience runs at a risk. The username is also used to transfer the file to the remote system using SCP. If the same machine is used as both the server and the client enter 'localhost' for the Host field. When the script is executed the application will switch into the Graphing perspective. A Data View chart is populated with live data, in addition to the output in the console.  You should see a screen similar to the following:
-[[Image:IDEGraphics.png]]
-You will see that the data table poplulates from live data parsed from the console. Now we'll make a graph to briefly illustrate the Graphing perspective. Click the Create Graph button next to bring up the Select Chart dialogue.
+== Concepts ==
-[[Image:GraphWizard.png]]
+=== Data Table ===
-Select line graph. You will be prompted to select a column of the X series and Y series; select "Time" and "Write" respectively. After you click ok you should see the line graph as follows:
+The Data Table is a view that is always available when running a script with the chart option. It initially 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.
-[[Image:IDEGraph.png]]
+[[Image:SystemtapGraphDataView.png]]
-Note that the multiple series graphs (Multi-Line, Multi-Bar, and Multi-Scatter) will request two Y series, Y1 and Y2. In the case of our example, these would be "Read" and "Write". Each series will be assigned a different color value for the purposes of differentiation and will be plotted both in respect to the specified X series.
+The columns of the Data Table can be resized at will by dragging the separation lines between column headers, as long as the '''Auto resize columns''' option (in Preferences->SystemTap->Graphing->Data Table) has been deactivated. In addition, the information in the data table can be [[#Importing_a_Data_Set|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|Opening Script Output]]. Right clicking the Data Table provides a menu with the following options:
-== Concepts ==
+* '''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:
-=== DataTable ===
+** Unformatted - No formatting is applied.
-The DataTable is the default view the user sees 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 DataTable is a visualization of the data structure that every other graph type spawns from.
+** String
-[[Image:GraphingPerspective.png]]
+** Date
+** Double
+** Hex
+** Octal
+** Binary
+* '''Add Filter...''' - Adds a [[#Filters | filter]] to the Data Table.
+* '''Remove Filter...''' - Removes a [[#Filters | 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.
-The columns of the DataTable can be resized at will by dragging the seperation lines between column headers. In addition, the information in the data table can be [[#Importing_a_Data_Set|saved and loaded ]] without having to re-run the script. Furthermore, the user can populate the DataTable without having to run a script if a script's output has been saved into a file, see [[#Opening_Script_Output|Opening Script Output ]].Right clicking the DataTable provides a menu with the following options:
+=== Data Graph Types ===
-* '''Format as...''' - Depending on which column the user right clicked, his 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 [[#Filters | filter ]] to the DataTable.
-* '''Remove Filter...''' - Removes a [[#Filters | filter ]] from the DataTable.
-* '''Manually Resize''' - Allows the user to resize column width without bouncing back to the minimum based on the largest value.
-=== DataGraph Types ===
 Currently there are five graph types built into SystemTap Plug-in.
-These graph types can be used instantiated by using the Graph Wizard once the DataTable is populated. The Graphing Perspective can support multiple graphs from one DataTable. Each are updated and can be viewed by navigating through the tabs shown at the top of each graph.
+These graph types can be used instantiated by using the [[#Create_Graph_Wizard | 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.
+A Scatter Graph uses Cartesian coordinates to show the relation of two or more quantitative variables. All values must be numeric.
-Optionally you can add extra Y Series; here you select another series of data you want to plot along the Y Axis.
-[[Image:scatter.png]]
+[[Image:Scatter.png]]
 ==== 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.
+The Line Graph is traditionally ideal for horizontally depicting non-cumulative data over, say, time. All values must be numeric.
-Optionally you can add extra Y Series; here you select another series of data you want to plot along the Y Axis.
+[[Image:Line.png]]
-[[Image:line.png]]
 ==== 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.
+The Area Graph is traditionally ideal for horizontally depicting non-cumulative data over, say, time. All values must be numeric.
-Optionally you can add extra Y Series; here you select another series of data you want to plot along the Y Axis.
+[[Image:Area.png]]
-[[Image:area.png]]
 ==== 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.
+The Bar Graph typically uses bars to show frequencies or values. Labels can be given to bars by applying string values to the x-axis. Y-axis values, though, must be numeric.
-Optionally you can add extra Y Series; here you select another series of data you want to plot along the Y Axis.
 [[Image:Bar.png]]
 ==== 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; here you select another series of data you want to plot along the Y Axis.
+The Pie Graph uses a pie to show percentages. One pie is drawn for each data series provided. Titles can be given to slices by applying string values to the x-axis. Y-axis values, though, must be numeric.
 [[Image:Pie.png]]
 === Filters ===
-Filters are screens that you can set on your DataTable 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 DataTable:
+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 and manageable.
-* '''Add Filter...''' - Adds a Filter to the DataTable.
-* '''Remove Filter...''' - Removes a Filter from the DataTable.
+The following options exist to work with Filters in the Data Table:
+* '''Add Filter...''' - Adds a Filter to the Data Table. Multiple filters may be applied at a time.
+* '''Remove Filter...''' - Removes a Filter from the Data Table. All currently applied filters will be listed in a drop-down menu; the user may select which of them to remove.
 When you select '''Add Filter''' you see the following dialogue box:
-[[Image:filters.png]]
+[[Image:StapDataFilters.png]]
+What follows is a breakdown of each Filter type, and an example of how each affects this sample data set:
+[[Image:UnfilteredDataset.png]]
-What follows is a breakdown of each Filter type:
+* '''Match Filter''' - This filter either removes or keeps everything from the data set where the selected selected column's value matches the chosen value.
-* '''Match Filter''' - This filter removes everything from the data set where the selected column's
+[[Image:Match.png]]
-value does not match the chosen value.
-[[Image:match.png]]
 Result:
-[[Image:match2.png]]
+[[Image:Match2.png]]
-* '''Range Filter''' - This filter removes everything from the data set that is not included in the
-selected range of values.
-[[Image:range.png]]
+* '''Range Filter''' - This filter keeps everything from the data set that is either inside or outside the selected range of values. Note that it is possible to use unbounded ranges by leaving either the lower or upper bound blank.
+[[Image:Range.png]]
 Result:
-[[Image:range2.png]]
+[[Image:Range2.png]]
@@ Line 926: / Line 926: @@
 removed.
-[[Image:sort.png]]
+[[Image:Sort.png]]
 Result:
-[[Image:sort2.png]]
+[[Image:Sort2.png]]
@@ Line 934: / Line 936: @@
 value in the selected column. Data for the removed rows will be aggregated together based on the chosen
 aggregation method.
-[[Image:unique.png]]
+[[Image:Unique.png]]
 ** '''Average Aggregate''' - This aggregate will return the average of all the items consolidated.
 ** '''Count Aggregate''' - This aggregate will return the number of items consolidated.
@@ Line 942: / Line 946: @@
 === Graph Interaction ===
-Each of the [[#DataGraph_Types | Graph Types ]] have similar options that can be used in the Graphical
-Perspective:
-* '''Zoom Bar''' - This enables the user to zoom in and out on the current graph by sliding the bar up and down. The current magnification is shown at the top of the bar. Magnification can range from as high as .0625x to as low as 4x the dimensions of the original graph.<[[Image:zoom.png]]
-* '''Title''' - This option turns on and off the title specified in the graph creation wizard.
-* '''Legend''' - This option turns on and off the legend, particularly useful in the graph types that show multiple series.
-* '''Grid Lines''' - This option permits the user to turn and off the grid lines.
-* '''Normalization''' - The option to normalize occurs only in multi-series graphs. By default, series graphs are rendered using normalization which scales them to visuals easily comparable to one another. The user has the option to view the normalization scale by clicking the data in the graph. The user also has the option of disabling normalization by deselecting it.
-[[Image:graphExpanded.png]]
+==== Graph Options ====
-== Tasks ==
+Each of the [[#Data_Graph_Types | Graph Types]] have similar options that can be used in the Graph Selector View:
-This section of the Graphing User Guild is intended to provide help pages for common tasks that the user may wish to perform in the Graphics Perspective.
+* '''Legend''' - This option turns on and off the legend, particularly useful in the graph types that show multiple series.
+* '''Graph Scrolling/Scaling''' - It is possible to zoom & scroll through any graph axis. Different controls are provided for navigating through continuous and discrete axes.
-=== Importing/Exporting Data Sets ===
+[[Image:GraphNavBefore.png]]
-From time to time the user may want to preserve the script results for continued work at a later date/time or to share findings with others. The Importing and Exporting options provide an easy way to do this.
+To zoom in/out of a continuous axis (ie Scatter/Line/Area Graph), use the +/- buttons or the Scale bar beneath / to the left of a graph. To scroll through the viewing area, use the horizontal/vertical scroll bars provided.
-==== Importing a Data Set ====
+[[Image:GraphNavAfter.png]]
-In order to import a Data Set the user must first have one either from running a script or from another user. To import the Data Set select '''<u>F</u>ile-><u>I</u>mport Data Set'''. The user will be prompted with an Open File dialogue box. Navigate to the Data Set file you wish to open and select it. Keep in mind Data Set files can have any extension type, though the user may want to use .set for consistency.
+Specialized controls are available for zooming & scrolling through discrete axis, namely the bars of a Bar Graph or the pies of a Pie Chart.
-[[Image:import.png]]
-==== Exporting a Data Set ====
+[[Image:BarNavBefore.png]]
-In order to export a Data Set the user must first have a populated DataTable from a previously running script. To export the Data Set select '''<u>F</u>ile-><u>E</u>xport Data Set'''. The user will be prompted with an New File dialogue box. Navigate to the location you wish to export the Data Set to and save it. Keep in mind Data Set files can have any extension type, though the user may want to use .set for consistency.
+Zooming is performed with the '''Zoom In/Out''' buttons beneath the graph. To scroll to left or right, click '''<''' or '''>''' respectively. To jump to the beginning or end of the axis, click '''<<''' or '''>>''' respectively.
-[[Image:export.png]]
-=== Generating Graphs ===
+[[Image:BarNavAfter.png]]
-In order to graph SystemTap scripts you must have a script open in the IDE Perspective, and the '''<u>R</u>un->Run w/ Chart''' option must be used. 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 [[#Graphing_Tutorial | Graphing Tutorial ]] has been written to guide the user through the execution and charting of a provided script. Any script can be used however that provides consistent data along with a regular expression (regex). For instructions on using regex see our [[#Guide_to_Regular_Expressions | Guide to Regular Expressions ]].
-=== Opening Script Output ===
+Use [[#Preferences | Preferences]] to configure other graph settings, such as grid lines and viewable data items.
-This option allows the user to open a text file containing the output of a SystemTap script, and to parse it as it would real time data from a running script.  Select '''<u>F</u>ile-><u>O</u>pen Script Output'''. Navigate to the file you wish to open and select it. The DataTable will populate with the data, at which point you can graph the results.
-=== Saving a Graph Image ===
+==== Graph Coordinate Tooltips ====
-The Graphics Perspective provides a unique feature to users that allows them to save their graphs in a standard image format. In order to do this use the menu option '''<u>F</u>ile->Save <u>G</u>raph Image'''. This opens a dialogue box where the user can navigate to the location they desire to save the image file.
+Hover over any data point on a graph to display detailed information about that point's coordinates. This feature is available for all graph types.
-[[Image:saveoutput.png]]
+[[Image:LineChartTooltip.png]]
-== Reference ==
+== Graphing Tasks ==
-This section of the Graphing User Guild is intended to provide the following resources should you have any
+=== Importing/Exporting Data Sets ===
-very specific questions regarding the Graphing Perspective in general or one of the options associated with
-it. It also contains example scripts and FAQs.
-=== Frequently Asked Questions ===
+A data set is comprised of the contents of a Graph Set's data table. From time to time the user may want to preserve this data for continued work at a later date/time or to share findings with others. The Importing and Exporting options provide an easy way to do this.
-This section details frequently asked questions relating to the Graphing Perspective.
-'''Can I make more than one graph at one time? Do they update concurrently?'''
+To save a data set, click the '''Export Data Set''' toolbar button while viewing one of the tabs of the Graph Set data that is to be saved (either the Data Table or one of its graphs). To load & display a previously-exported data set, use the '''Import Data Set''' toolbar button, which is available at all times.
-A: Yes and yes. Start another graph the same way you started the first one, by clicking the Graph Wizard button.
+[[Image:DataSetImportExport.png]] ''The Data Set toolbar buttons that appear while viewing a Graph Set. (Blue/left: Export. Red/Right: Import.)''
+[[Image:DataSetImportOnly.png]] ''The Import Data Set button as it appears while a Graph Set is not being viewed.''
-'''Can I increase the rate at which SystemTap GUI update the graph?'''
+In either case, a file dialog will appear to allow the user to choose the path on the filesystem where the data set should be exported to / imported from.
-A: Yes. By default it is set to once per second, but you can increase this in the [[#Preferences | Preferences ]]
+=== Saving a Graph Image ===
+It is possible to save graphs as image files. To do so, view the graph that is to be saved and click the '''Save Graph''' button that appears in the toolbar. This opens a dialogue box where the user can navigate to the location they desire to save the image file.
-'''Is there any way to save or export the graph images?'''
+[[Image:SaveStapGraphButton.png]]
-A: Yes. Use '''<u>F</u>ile->Save <u>G</u>raph Image''' to save the graph.
-'''What if I want to preserve this data for manipulation later?'''
-A: You can do this by using '''<u>F</u>ile-><u>E</u>xport Data Set'''. This will save your data set for further
-work.
-=== Menus ===
-What follows is a comprehension list of the menu options available within the Systemtap GUI Graphing Perspective.
-==== File ====
-* '''<u>O</u>pen Script Output''' - This option opens the specified file and reads the contents into the DataTable for use in the Graphing Perspective.[[Image:openbox1.png]]
-* '''Save <u>G</u>raph Image''' - This option saves the graph in the specified file extension format.[[Image:saveoutput.png]]
-* '''<u>I</u>mport Data Set''' - This option allows you to load a previously saved set of data obtained from running a SystemTap script. You can proceed from this point as if you had just ran a script and populated the DataTable.[[Image:import.png]]
-* '''<u>E</u>xport Data Set''' - This option allows you to save a current data set after you've ran a script in the intention of having someone else look at the user's script results through the tool or for further work done by the user. (Shortcut: Ctrl+X)[[Image:export.png]]
-* '''<u>P</u>rint''' - This option prints the graph currently holding the focus. (Shortcut: Crtl+P)
-* '''E<u>x</u>it''' - Exits Systemtap GUI.
-==== Run ====
-* '''<u>S</u>top''' - This option terminates the script thread associated with whichever script currently has the focus. (Shortcut: Ctrl+F9)
-==== Window ====
-* '''Open in <u>N</u>ew Window''' - This option opens a new instance of SystemTap GUI.
-* '''<u>O</u>pen Perspective''' - This submenu lists each of the available perspectives to open:
-** IDE Perspective
-** Graphing Perspective
-* '''Show <u>V</u>iews''' - This submenus lists each of the available views to open:
-** Console
-** Error Log
-** Functions
-** Kernel Source
-** Probe Alias
-** Other - Lists all views in the application.[[Image:viewbox1.png]]
-* '''<u>P</u>references''' - Due to the breath of this topic it is covered in another section. Please see [[#Preferences | Preferences ]].[[Image:preferencesbox1.png]]
-=== Toolbars ===
-SystemTap GUI currently has two toolbars built in; an Action Bar for file and execution operations and a Perspective Selector to jump to different perspectives.
-==== Action Bar ====
-* [[Image:open_wiz.gif]] '''Open Script Output''' - This option opens the specified file and reads the contents into the DataTable for use in the Graphing Perspective.
-* [[Image:save_wiz.gif]] '''Save Graph Image''' - This option saves the graph in the specified file extension format.
-* [[Image:import_wiz.gif]] '''Import Data Set''' - This option allows you to load a previously saved set of data obtained from running a SystemTap script. You can proceed from this point as if you had just ran a script and populated the DataTable.
-* [[Image:export_wiz.gif]] '''Export Data Set''' - This option allows you to save a current data set after you've ran a script in the intention of having someone else look at the user's script results through the tool or for further work done by the user.
-* [[Image:stop_obj.gif]] '''Stop Script''' - This button will stop the currently active script from running.
-==== Perspective Selector ====
-* [[Image:ide.png]] '''IDE Perspective''' - This button brings you into the IDE Perspective, useful for writing and executing scripts.
-* [[Image:graphing.png]] '''Graphing Perspective''' - This button brings you into the Graphing Perspective, useful for graphing scripts.
-= SystemTap Dashboard =
-Welcome to SystemTap GUI help pages. Here you will find wide selection of help pages covering the Dashboard Perspective of SystemTap GUI.
-== Dashboard Tutorial ==
-The Dashboard Perspective is the most advanced part of SystemTap GUI. It is designed to allow users to browse and run prebuilt [[#Modules | Modules ]] in order to see multiple graphs updating in sequence.
-For this tutorial we'll use one of the prebuilt modules to illustrate  how the Dashboard perspective is used. Each module is part of a module family, a collection of related modules. To start, switch to the Dashboard perspective. On the left you should see a browser titled "Modules".
-[[Image:moduleBrowser.png]]
-The [[#Modules_Browser | Modules Browser ]] contains a list of modules available to run. Notice that there is another tab, "Active Modules", in the same pane. The [[#Active_Modules_Browser | Active Modules Browser ]] allows you to browse the modules you currently have running. At this point, however, it will be empty; there are no modules currently running. Open the module family "Hard Disk" by clicking the arrow next to it's name. This will display each module associated in the "Hard Disk" module family.
-We are going to be running the Disk Access module. This can be accomplished two ways. You may select it and '''<u>R</u>un-><u>R</u>un Script'''. You can alternatively click the '''Run Script''' button in the Toolbar. SystemTap GUI will request the details of the Remote Server(ip address, username, password), enter the details to proceed. You should see a display similar to the following:
-[[Image:runningDashboard.png]]
-The Dashboard shows three graphs, each obtaining data from one script, each analyzing different components of disk access - bytes read, bytes written, and a multi-line graph illustrating both.
-[[Image:smallGraph.png]]
-Each graph comes with graph-specific options:
-* [[Image:expandButton.png]] - '''Expand Graph''' - This option opens a set of graph-unique options:
-** '''Zoom''' - This option allows the user to increase and decrease the no of x-axis ticks.
-* [[Image:rightleft.png]] - '''Close Zoom bar''' - This hides the zoom bar.
-* [[Image:closeButton.png]] - '''Close Graph''' - This removes the graph from the viewer pane.
-Take a moment to interact with these options to familiarize yourself with them.
-[[Image:graphExpanded.png]]
-==== Multiple Module Execution ====
-SystemTap GUI supports the execution of more than one module at one time. The currently running script does not not to be halted and the currently open graphs do not need to be closed, though they may be if desired. To execute another module, simply select and run it as described above. If you were to run  a module in the Memory module family for example, a new tab will be opened titled 'Memory' in addition to the current tab for 'Hard Disk'.
-Up to 8 graphs may be open in each tab at any given time. Drag and drop support is included for the graph types, permitting re-arrangement for ideal analysis. In addition, '''Pausing''' is also implemented in SystemTap GUI. You may pause any module by selecting '''<u>R</u>un-><u>P</u>ause Module''', or by selecting '''Pause''' from the toolbar. Know that this method of pausing is an illusion; the graph data is simply not updated while the script continues to run. This inability to truly pause is inherent in SystemTap itself. You can also stop the script using the above methods. This will halt the running script of that module and remove the graphs entirely from the view pane. It will not affect graphs or scripts associated with any other modules. If at any time you are unsure of which modules are currently active you can check this by navigating to the [[#Active_Modules_Browser | Active Modules Browser ]]
-== Concepts ==
-This section of the Dashboard User Guide details conceptual topics of the application; the major components, what they do, and how how you interact with them.
-=== Modules ===
-A module is a package used in the Dashboard perspective, containing a SystemTap script and associated metadata.
-==== Module Families ====
-Modules are grouped in "module families", groups of modules that are related. One example is the Hard Disk module family which contains the module Disk Access:
-[[Image:moduleBrowser.png]]
-==== Multiple Graphs ====
-Often, as in the case of the Disk Access module, modules will spawn multiple graphs on execution.
-[[Image:runningDashboard.png]]
-There are a number of different module families constructed for different analysis sets.
-=== Modules Browser ===
-The Modules Browser displays all the modules available to run, categorized by module families. Modules in each family can be viewed by expanding the appropriate module family name.
-[[Image:moduleBrowser.png]]
-From the Modules Browser the following options are available on right-clicking a module:
-* '''View Script''' - Opens the module's SystemTap script in the IDE Perspective.
-To view the currently active modules, switch to the [[#Active_Modules_Browser | Active Modules Browser ]].
-=== Active Modules Browser ===
-The Active Modules Browser displays each module currently active.
-[[Image:activeModules.png]]
-The following right click options exist for the graphs embedded in each of the active modules:
-* '''Stop Graph''' - Stops the graph from updating.
-* '''Activate Graph''' - Instructs a formerly stopped graph to continue updating.
-To view all modules available, switch to the [[#Modules_Browser | Modules Browser ]].
-== Tasks ==
-This section of the Dashboard User Guild is intended to provide help pages for common tasks that the user may wish to perform in the Dashboard Perspective.
-=== Creating Modules ===
-SystemTap GUI allows for the creation of custom modules. In order to do this the user must have a script that returns data in a consistent pattern along with providing a regular expression to interpret it; the same requirements as any script run in the Graphics Perspective. Creating a module can be done in two ways
-==== Export Script ====
-Using the '''<u>E</u>xport Script'''
-option in the '''<u>F</u>ile''' menu of the IDE Perspective. This will create a module from a script that is currently open in the IDE. The module will consist of the script and metadata information stored as a '.dash' file on the local system(where SystemTapGUI is running).The user is first prompted
-for regular expression details (just like in the Graphing perspective) after which a
-dialog box similar to the following shows up:
-[[Image:exportScript.png]]
-The dialogue box has the following properties:
-* '''Display''' - This is the name of the module. This is the text that will show up under the specified
-module family.
-* '''Category''' - This field requires the name of the module family the module should be placed in.
-* '''Graphs''' - This box allows you to added one or more predefine graph types to spawn each time the
-module is ran.
-When you click ok your module will be added into the Module Browser in the Dashboard Perspective.
-[[Image:addedModule.png]]
-==== Create Module ====
-Using the '''<u>C</u>reate Module'''
-option in the dashboard or IDE toolbar. This will create a module from an example script that available on the remote System, Users will have to specify the location of the examples directory and the path to the script.The module will consist of only the metadata information stored as a '.dash' file on the local system(where SystemTapGUI is running). The script will not be packaged with the module, the location specified will be used to run the script directly on the remote system. The user would have to first enter the script details,
-and then follow the same set of steps as in the previous option.
-[[Image:script_details.gif]]
-==== Tips ====
-Make sure your script works fine with the regular expression and the graphs are as desired using the IDE/Graphing perspectives before creating a dashboard module using the script.
-==== Constraints ====
-The script should adhere to the below constraints to add it to the dashboard:
-*  The script should regularly output rows/tables of data that will confirm to the same regular expression, i.e, you cannot have two sets of output in the same script
-*  The script should not have exit() statements
-*  Since the dashboard supports dynamic graphs the script should output data periodically
-*  Users should remember that the dashboard currently does not support any processing of the output data.
-=== Importing Modules ===
-The Dashboard Perspective allows for the import of modules by using the option '''<u>F</u>ile-><u>I</u>mport
-Module Location'''. Simply navigate to and select the module file you wish to import, and SystemTap GUI will
-add the module to the [[#Modules_Browser | Modules Browser ]] in the Dashboard Perspective.
-[[Image:importDialogue.png]]
-=== Running Modules ===
-The [[#Modules_Browser | Modules Browser ]] contains a list of modules available to run.
-Running modules in the Dashboard Perspective can be accomplished in three different ways. You may select it and '''<u>R</u>un-><u>R</u>un Script'''. You can alternatively click the '''Run Script''' button in the Toolbar. SystemTap GUI will request the details of the remote system(IPAddress,username,password).Enter these details and make sure that the username has sufficient access to execute SystemTap scripts You should see a display similar to the following, graphs differing based on what module you chose to run and Module Browser differences based off of your current module include list:
-[[Image:runningDashboard.png]]
-==== Multiple Module Execution ====
-SystemTap GUI supports the execution of more than one module at one time. The currently running script does not not to be halted and the currently open graphs do not need to be closed, though they may be if desired. To execute another module, simply select and run it using  one of the two methods described above.
-Up to 8 graphs may be open at one given time in any given tab. Stopping the script will halt the running script of that module and remove the graphs entirely from the view pane. It will not affect graphs or scripts associated with any other modules. If at any time you are unsure of which modules are currently active you can check this by navigating to the [[#Active_Modules_Browser | Active Modules Browser ]]
-=== Graph Interaction ===
-The graphical options used in the Dashboard perspective:
-* [[Image:zoom.png]]'''Zoom Bar''' - This enables the user to zoom in and out on the current graph by sliding the bar to the left and right. The current magnification is shown at the top of the bar. Zooming would increase the no of x-axis ticks therefore allowing the user to see more(or less) data at a point in time.
-* [[Image:expandButton.png]] - '''Show Zoom bar''' - This displays the zoom bar.
-* [[Image:rightleft.png]] - '''Close Zoom bar''' - This hides the zoom bar.
-* [[Image:closeButton.png]] - '''Close Graph''' - This removes the graph from the viewer pane.
 == Reference ==
-This section of the Dashboard User Guild is intended to provide the following resources should you have any
-very specific questions regarding the Dashboard Perspective 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 the Dashboard Perspective.
+This section details frequently asked questions relating to graphing script output.
-'''Can more than one module be open at any given time?'''
+'''Can I make more than one graph at one time? Do they update concurrently?'''
-A: SystemTap GUI supports the execution of more than one module at one time. The currently running script does not
+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.
-not to be halted and the currently open graphs do not need to be closed, though they may be if desired. To
-execute another module, simply select and run it as described previously . If you were to
-run the Page Faults module in the Memory module family for example, an additional tab will be created for
-the Memory module family
-'''How many graphs may be opened at one time?'''
+'''Can I increase the rate at which graphs are updated?'''
-A: Currently, 8 in each tab(i.e, 8 per module family). You may close graphs to make more room by using the closebox. [[Image:closeButton.png]]
+A: Yes. By default it is set to once per second, but you can increase this in [[#Preferences | Preferences]].
-'''Is there an option to pause specific graphs?'''
+'''Is there any way to save or export the graph images?'''
-A: No. You can pause or stop a specific module, which will in turn pause or stop the specific graphs associated
+A: Yes. A '''Save Graph''' button appears in the toolbar whenever you are viewing a graph. Clicking it will allow you to save the graph currently in focus.
-with it, but you cannot pause or stop just one graph unless that module produces just one graph or you close all
-but that graph.
-=== Menus ===
-What follows is a comprehension list of the menu options available within the Systemtap GUI Dashboard Perspective.
-==== File ====
+'''What if I want to preserve this data for manipulation later?'''
-* '''<u>I</u>mport Module Location''' - This option allows brings up a dialogue box prompting the user with the location of a module file which is then loaded into the [[#Modules_Browser | Modules Browser ]].
-[[Image:importDialogue.png]]
-* '''E<u>x</u>it''' - Exits Systemtap GUI.
-==== Run ====
-* '''<u>R</u>un''' - This option runs the selected module in the [[#Modules_Browser | Modules Browser ]].
-* '''<u>P</u>ause''' - This option pauses the selected module in the [[#Modules_Browser | Modules Browser ]]. Know that this method of pausing is an illusion; the graph data is simply not updated while the script continues to run. This inability to truly pause is inherent in SystemTap itself.
-* '''<u>S</u>top''' - This option stops the selected module in the [[#Modules_Browser | Modules Browser ]].
-==== Window ====
-* '''Open in <u>N</u>ew Window''' - This option opens a new instance of SystemTap GUI.
-* '''<u>O</u>pen Perspective''' - This submenu lists each of the available perspectives to open:
-** IDE Perspective
-** Graphing Perspective
-** Dashboard Perspective
-* '''Show <u>V</u>iews''' - This submenus lists each of the available views to open:
-** Console
-** Error Log
-** Functions
-** Kernel Source
-** Probe Alias
-** Other - Lists all views in the application.
-[[Image:viewbox1.png]]
-* '''<u>P</u>references''' - Due to the breath of this topic it is covered in another section. Please see [[#Preferences | Preferences ]]
-=== Toolbars ===
-SystemTap GUI currently has two toolbars built in; an Action Bar for file and execution operations and a Perspective Selector to jump to different perspectives.
-==== Action Bar ====
-* [[Image:import_wiz.gif]] '''Import Dashboard Module Location''' - This option brings up a dialogue box prompting the user for a module file which is then loaded into the [[Linux_Tools_Project/Systemtap/User_Guide/dashboard/modulesBrowser.html | Modules Browser ]].
-* [[Image:start_script.gif]] '''Run''' - This option runs the selected module in the [[Linux_Tools_Project/Systemtap/User_Guide/dashboard/modulesBrowser.html | Modules Browser ]].
-* [[Image:pause_script.gif]] '''Pause''' - This option pauses the selected module in the [[Linux_Tools_Project/Systemtap/User_Guide/dashboard/modulesBrowser.html | Modules Browser ]]. Know that this method of pausing is an illusion; the graph data is simply not updated while the script continues to run. This inability to truly pause is inherent in SystemTap itself.
-* [[Image:stop_obj.gif]] '''Stop''' - This option stops the selected module in the [[Linux_Tools_Project/Systemtap/User_Guide/dashboard/modulesBrowser.html | Modules Browser ]].
-* [[Image:mod_obj.gif]] '''Create a New Dashboard module''' - This option creates a new module in the [[Linux_Tools_Project/Systemtap/User_Guide/dashboard/modulesBrowser.html | Modules Browser ]].
-==== Perspective Selector ====
+A: While viewing a Data Table or one of the graphs it provides data to, the '''Export Data Set''' toolbar button is available. Click this button to save the focused Data Table's contents into a .set file. Such files can be loaded back later with the '''Import Data Set''' button on the toolbar (which is always available).
-* [[Image:ide.png]] '''IDE Perspective''' - This launches the IDE Perspective, useful for writing and executing scripts.
-* [[Image:graphing.png]] '''Graphing Perspective''' - This launches the Graphing Perspective, useful for graphing scripts.
-* [[Image:dash.png]] '''Dashboard Perspective''' - This launches the Dashboard Perspective, useful for multiple graphing.
+= Copyright Information =
 <p class="copyright">
 &#169; Copyright IBM Corporation 2012<br>

Breadcrumbs

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Difference between revisions of "Linux Tools Project/Systemtap/User Guide"

Revision as of 17:11, 29 May 2014

Contents

Overview

The SystemTap Plugin

SystemTap

Installing

Requirements

Kernel Source Location

Tutorials

Preferences (Optional)

Links to SystemTap Resources

SystemTap IDE

Getting Started

IDE Tutorial

Lesson 1: Getting Started

Lesson 2: Writing Your First Script

Lesson 3: Running Your Script

Concepts

SystemTap IDE Perspective

STP Editor

Function Browser

Kernel Browser

Probe Alias Browser

Tasks

Creating SystemTap Scripts

Using the STP Editor

Creating Run Configurations

Local/Remote Runs

SystemTap Options

Graphing

Viewing Data Charts

Reference

Views and Editors

Views

Editors

Menus

Edit

Navigate

Run

Window

Toolbars

Action Bar

Preferences

Frequently Asked Questions

Example SystemTap Scripts

top.stp - Prints the top 20 system calls (http://sourceware.org/systemtap/examples/top.stp)

prof.stp - Simple profiling (http://sourceware.org/systemtap/examples/prof.stp)

keyhack.stp - Modifying variables in the kernel. (http://sourceware.org/systemtap/examples/keyhack.stp)

kmalloc.stp - Statistics example. (http://sourceware.org/systemtap/examples/kmalloc.stp)

kmalloc2.stp - Example using arrays of statistics. (http://sourceware.org/systemtap/examples/kmalloc2.stp)

Guide to Regular Expressions

SystemTap Graphing

Getting Started

Introduction

Graphing Tutorial

Create Graph Wizard

Concepts

Data Table

Data Graph Types

Scatter Graph

Line Graph

Area Graph

Bar Graph

Pie Graph

Filters

Graph Interaction

Graph Options

Graph Coordinate Tooltips

Graphing Tasks

Importing/Exporting Data Sets

Saving a Graph Image

Reference

Frequently Asked Questions

Copyright Information