SystemTap IDE | ||
---|---|---|
![]() |
![]() |
|
SystemTap GUI User Guide | SystemTap Graphing |
In this tutorial we will orient you with IDE Perspective and its functions. At this point we assume that you are able to run Systemtap GUI and are unfamiliar with how to procede. If you cannot yet start the application, please refer to our 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 parse the tapsets.
The IDE Perspective'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 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.
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.
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 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.
Now type/copy the following:
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. 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 { /* * available variables on this probe: * argstr, buf_uaddr, count, fd, name */ }
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.
In 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.
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.
For this example enter the following:
Columns: 3 TITLE REGULAR EXPRESSION DELIMITER 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:
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.
SystemTap has three perspectives, each with its own purpose.
completion features that facilitate efficient development of scripts.
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.
See also: Menus , Example SystemTap Scripts , Toolbars
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.
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 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 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:
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.
Create a SystemTap script by selecting File->New 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.
A 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
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:
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 , Toolbars , Example SystemTap Scripts
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.
This section details the views and editor in relation to the IDE Perspective.
The IDE Perspective consists of 5 views and and two editors.
Three editors are available in Systemtap GUI.
What follows is a comprehension list of the menu options available within the IDE Perspective of Systemtap GUI.
(Shortcut: Crtl+F)
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.
This section details each of the options listed under Window->Preferences. 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.
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 different options as far as running your Systemtap script. Please visit the Menus to learn more about the four 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.
What follows is a few SystemTap Scripts that you may use in SystemTap GUI, 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
#!/usr/bin/env stap # # This script continuously lists the top 20 systemcalls 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 ()
#!/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
#! /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") }
#! /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)) }
#! /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"); } }
Regular expressions are used in SystemTap GUI to define how the GUI interprets information that it recieves from the script file. If the user wishes to change the regular expression during runtime they may do so by selecting Edit->Modify Parsing Expression.
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 GUI User Guide | SystemTap Graphing |