From 5340b57d969f027695befa58909d5eb9ff59d006 Mon Sep 17 00:00:00 2001 From: ddomingo Date: Fri, 26 Sep 2008 14:28:21 +1000 Subject: added Usage item --- doc/SystemTap_Beginners_Guide/en-US/Scripts.xml | 32 ++++++++++--- .../en-US/Using_SystemTap.xml | 52 ++++++++++++++++++++-- 2 files changed, 75 insertions(+), 9 deletions(-) (limited to 'doc/SystemTap_Beginners_Guide/en-US') diff --git a/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml b/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml index e8f9c3cb..160597bf 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Scripts.xml @@ -45,7 +45,7 @@ probe [event], exit() } - The exit() condition is optional, but it is recommended since it safely terminates the session once the script successfully traps the required information. + The exit() condition is optional; this condition safely terminates the session once the script successfully traps the required information the first time. Important @@ -68,7 +68,7 @@ probe [event], kernel.function("[function]") - The entry to the kernel function function. For example, kernel.function("sys_open") refers to the "event" that the kernel function sys_open is used. To specify the return of the kernel function sys_open, append the return string to the event statement; i.e. kernel.function("sys_open").return. + The entry to the kernel function function. For example, kernel.function("sys_open") refers to the "event" that occurs when the kernel function sys_open is called by any thread in the system. To specify the return of the kernel function sys_open, append the return string to the event statement; i.e. kernel.function("sys_open").return. When defining functions, you can use asterisk (*) for wildcards. You can also trace the entry/exit of a function in a kernel source file. Consider the following example: Wildcards and Kernel Source Files in an Event @@ -142,7 +142,7 @@ probe kernel.function("*@net/socket.c").return { } - timer.ms() + timer events An event that specifies a handler to be executed "after X number of milliseconds". For example: @@ -156,7 +156,23 @@ probe timer.ms(4000) - is an example of a probe that allows you to terminate the script after 4000 milliseconds (or 4 seconds). When used in conjunction with another probe that traps a large quantity of data, a probe using timer.ms() allows you to limit the information your script is collecting (and printing out). + is an example of a probe that allows you to terminate the script after 4000 milliseconds. Note that you can also use the following timer events: + + + +timer.s([seconds]) + +timer.us([microseconds]) + +timer.ns([nanoseconds]) + +timer.hz([hertz]) + +timer.jiffies([jiffies]) + + + + When used in conjunction with another probe that traps a large quantity of data, timer events allow you to limit the information your script is collecting (and printing out). @@ -215,11 +231,10 @@ probe begin printf ( ) Statements - The printf () statement is one of the simplest handler tools for printing data. printf () can also be used to trap data using a wide variety of SystemTap handler functions using the following format: + The printf () statement is one of the simplest functions for printing data. printf () can also be used to trap data using a wide variety of SystemTap handler functions using the following format: -is "handler tool" appropriate? @@ -234,6 +249,11 @@ printf ("[format string]\n", [argument]< You can use the variables %s (for strings) and %d (for numbers) in format strings, depending on your list of arguments. Format strings can have multiple variables, each matching a corresponding argument; multiple arguments are delimited by a comma (,) and space. + + Note + Semantically, the SystemTap printf function is very similar to its C language counterpart. The aforementioned syntax and format for SystemTap's printf function is identical to that of the C-style printf. + + To illustrate this, consider the following probe example: diff --git a/doc/SystemTap_Beginners_Guide/en-US/Using_SystemTap.xml b/doc/SystemTap_Beginners_Guide/en-US/Using_SystemTap.xml index da6d4d4c..38f8d018 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Using_SystemTap.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Using_SystemTap.xml @@ -108,14 +108,60 @@ uname -r
Usage - basic commands (e.g. stap), useful options per command (e.g. stap -vv), tool references (man pages, related kernel-doc), references within book (i.e. errors chapter) + - basic commands (e.g. stap), useful options per command (e.g. stap -vv), tool references (man pages, related kernel-doc), references within book (i.e. errors chapter) - running systemtap scripts + - running systemtap scripts + + + SystemTap scripts are run through the command stap. stap can run SystemTap scripts from standard input or from file. Below is a list of common options available to you: + - Tapsets: short intro on usage + + + + -v + + Makes the output of the SystemTap session more verbose. You can repeat this option to (for example, stap -vvv script.stp); provide more details on the script's execution. This option is particularly useful if you encounter any errors in running the script. + + For more information about common SystemTap script errors, refer to . + + + + + -I [directory] + + Check the script against additional tapsets found in [directory]. This is useful if you have additional tapsets that are not included in /usr/share/systemtap/tapset/; for more information about tapsets, refer to . + + + + + -o [filename] + + Sends the standard output to file ([filename]). + + + + + + +any other useful options worth noting here for beginners? + +For more information about stap, refer to man stap. + +To run SystemTap instrumentation (i.e. the kernel module built from SystemTap scripts during a cross-instrumentation), use staprun instead. For more information about staprun and cross-instrumentation, refer to . +
-- cgit