From 861bbf9582b1c8f8636bde926b37427e4b4d4c30 Mon Sep 17 00:00:00 2001
From: Sami Wagiaalla
Date: Tue, 4 Jun 2013 11:16:34 -0400
Subject: Update Systemtap Documentation
Change-Id: Ib1053174ae144c79f7944bdeee0db964f9b8cfa6
Reviewed-on: https://git.eclipse.org/r/13550
Reviewed-by: Jeff Johnston
What follows is a comprehension list of the menu options available within the Systemtap GUI Dashboard Perspective.
-What follows is a comprehension list of the menu options available within the Systemtap GUI Graphing Perspective.
-In this lesson we will open a new Systemtap script file to familiarize ourselves with the IDE Perspective. - Start by opening the File menu and selecting Open. A dialogue box will pop up and request the - location of the file you want to open. We've included a folder called "examples" right in the tar ball. You - may chose any of them to use; in this tutorial we will open top.stp. Go ahead and open the file.
-- -
-You'll see the file is loaded into the editor pane of Systemtap GUI. You'll also noticed different colored - text. Systemtap GUI supports syntax highlighting for the ease of the writer. Feel free to edit the file.
+ 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 @@ -61,13 +58,13 @@
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. + http://sourceware.org/systemtap/tutorial for up-to-date information on the latest version of Systemtap.
-Start by selecting File->New. 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.
-
Now type/copy the following:
+Now try writing a new script or type/copy the following example:
global read, write, start @@ -84,8 +81,8 @@ 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 +
+ 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. 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 syscall.read @@ -97,50 +94,89 @@ }-
-
Now insert the following line into the syscall.read probe:
++ 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. 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.
+ 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. +Another way to get assistance while writing a new probe is to press CTRL+Space at any point during editing. Doing so will provide autocompletion 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 in the IDE Perspective. + Lesson 3 you will learn how to run Systemtap scripts in the IDE Perspective.
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 Run->Run. 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.
+There are two ways to run a script. If you click on the run button in the tool bar that will run the current script as the current user on the local machine. For more control over running options you can create a Launch Configuration. To do so 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 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 ;. To do this select - Run->Run w/ Chart. 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. + 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... create a new SystemTap Launch Configuration as you did previously and switch to the graphing tab.
- + +
+Select + Graph the output of this script run and enter the parsing information below. That is the the number of columns for the chart, 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.
For this example enter the following:
Columns: 3 TITLE REGULAR EXPRESSION DELIMITER - Time \d+ .* \D+ - Read \d+ .* \D+ - Write \d+ .* \D+ + Time \d+ \D+ + Read \d+ \D+ + Write \d+ \D+-
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:
-- +
The title fields simply display the associated string in the column's header.
+Now to add a graph using the parsed output click the + Add... button in the + Graphs section. Select line graph and click + Next. You will be prompted to select a column of the X series and Y series; select "Time" "Read" and "Write" respectively. When the script is executed the + Graph Selector view is opened and it will contain a Data View and the graphs you have created. The 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:
-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:
- +
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.
-Those are the basics behind running a script in Systemtap GUI.
+If you click on + Data View you will see that the data table poplulates from live data parsed from the console: +
++ +
+Those are the basics behind running a script in Systemtap GUI.
SystemTap has three perspectives, each with its own purpose.
+completion features that facilitate efficient development of scripts.
-Create a SystemTap script by selecting - File->New in the IDE Perspective. You'll be prompted to enter a name for the file; + Select File -> New -> Other -> Systemtap -> Systemtap Script 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.
Your new file will be open and ready for coding in the Editor pane.
@@ -241,25 +266,16 @@There are certain features within the editor you may want to take advantage of:
colors. You can turn this on or off and change the colors in - Window->Preferences. -
-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 - Window->Preferences. -
-help page on a walk through use of the Run command. The Run command allows scripts to be executed directly - through SystemTap GUI.
See also: Menus , @@ -268,11 +284,11 @@
Viewing data charts from a SystemTap script is accomplished by running that script with the - Run->Run w/ Chart option. This is covered in the - 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. + Graph the output of this script run option. This is covered in the + Lesson 3: Running Your Script . After running a script with the graphing option, the user is presented with the Graph Selector View and the Data Table is loaded by default. The data table immediately begins populating as it receives input back through the console from the running SystemTap script.
- +
What follows is a comprehension list of the menu options available within the IDE Perspective of Systemtap GUI.
-- -
-- -
-- -
--
- -
-This section details each of the options listed under diff --git a/systemtap/org.eclipse.linuxtools.systemtap.ui.doc/Linux_Tools_Project/Systemtap/User_Guide/User-Guide.html b/systemtap/org.eclipse.linuxtools.systemtap.ui.doc/Linux_Tools_Project/Systemtap/User_Guide/User-Guide.html index c225e9b637..1d80d4428c 100644 --- a/systemtap/org.eclipse.linuxtools.systemtap.ui.doc/Linux_Tools_Project/Systemtap/User_Guide/User-Guide.html +++ b/systemtap/org.eclipse.linuxtools.systemtap.ui.doc/Linux_Tools_Project/Systemtap/User_Guide/User-Guide.html @@ -25,23 +25,13 @@
{{#eclipseproject:tools.linuxtools}}
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 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:
-Each perspective has full documentation associated with it and is packaged in the respective 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 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.
diff --git a/systemtap/org.eclipse.linuxtools.systemtap.ui.doc/Linux_Tools_Project/Systemtap/User_Guide/images/ContextAssist.png b/systemtap/org.eclipse.linuxtools.systemtap.ui.doc/Linux_Tools_Project/Systemtap/User_Guide/images/ContextAssist.png new file mode 100644 index 0000000000..3a78a0005b Binary files /dev/null and b/systemtap/org.eclipse.linuxtools.systemtap.ui.doc/Linux_Tools_Project/Systemtap/User_Guide/images/ContextAssist.png differ diff --git a/systemtap/org.eclipse.linuxtools.systemtap.ui.doc/Linux_Tools_Project/Systemtap/User_Guide/images/GraphingTab.png b/systemtap/org.eclipse.linuxtools.systemtap.ui.doc/Linux_Tools_Project/Systemtap/User_Guide/images/GraphingTab.png new file mode 100644 index 0000000000..b3371f6737 Binary files /dev/null and b/systemtap/org.eclipse.linuxtools.systemtap.ui.doc/Linux_Tools_Project/Systemtap/User_Guide/images/GraphingTab.png differ diff --git a/systemtap/org.eclipse.linuxtools.systemtap.ui.doc/Linux_Tools_Project/Systemtap/User_Guide/images/Newfile.png b/systemtap/org.eclipse.linuxtools.systemtap.ui.doc/Linux_Tools_Project/Systemtap/User_Guide/images/Newfile.png index 9b23dec081..3d4735c96e 100644 Binary files a/systemtap/org.eclipse.linuxtools.systemtap.ui.doc/Linux_Tools_Project/Systemtap/User_Guide/images/Newfile.png and b/systemtap/org.eclipse.linuxtools.systemtap.ui.doc/Linux_Tools_Project/Systemtap/User_Guide/images/Newfile.png differ diff --git a/systemtap/org.eclipse.linuxtools.systemtap.ui.doc/Linux_Tools_Project/Systemtap/User_Guide/images/SystemTapRunConfiguration.png b/systemtap/org.eclipse.linuxtools.systemtap.ui.doc/Linux_Tools_Project/Systemtap/User_Guide/images/SystemTapRunConfiguration.png new file mode 100644 index 0000000000..fecb6389e0 Binary files /dev/null and b/systemtap/org.eclipse.linuxtools.systemtap.ui.doc/Linux_Tools_Project/Systemtap/User_Guide/images/SystemTapRunConfiguration.png differ diff --git a/systemtap/org.eclipse.linuxtools.systemtap.ui.doc/Linux_Tools_Project/Systemtap/User_Guide/images/SystemtapGraphDataView.png b/systemtap/org.eclipse.linuxtools.systemtap.ui.doc/Linux_Tools_Project/Systemtap/User_Guide/images/SystemtapGraphDataView.png new file mode 100644 index 0000000000..228ee69096 Binary files /dev/null and b/systemtap/org.eclipse.linuxtools.systemtap.ui.doc/Linux_Tools_Project/Systemtap/User_Guide/images/SystemtapGraphDataView.png differ diff --git a/systemtap/org.eclipse.linuxtools.systemtap.ui.doc/Linux_Tools_Project/Systemtap/User_Guide/images/SystemtapGraphView.png b/systemtap/org.eclipse.linuxtools.systemtap.ui.doc/Linux_Tools_Project/Systemtap/User_Guide/images/SystemtapGraphView.png new file mode 100644 index 0000000000..a9f84b1399 Binary files /dev/null and b/systemtap/org.eclipse.linuxtools.systemtap.ui.doc/Linux_Tools_Project/Systemtap/User_Guide/images/SystemtapGraphView.png differ -- cgit v1.2.3