From ba7f87bf8ef0723ca462a8f7eaf0d36093822bdc Mon Sep 17 00:00:00 2001 From: ddomingo Date: Thu, 4 Dec 2008 10:44:33 +1000 Subject: revised as per wcohen, added new section iotime --- doc/SystemTap_Beginners_Guide/en-US/Book_Info.xml | 7 +- .../en-US/Revision_History.xml | 15 +++ .../en-US/Useful_Scripts-disktop.xml | 9 +- .../en-US/Useful_Scripts-iotime.xml | 140 +++++++++++++++++++++ .../en-US/Useful_Scripts-iotop.xml | 2 +- .../en-US/Useful_Scripts-paracallgraph.xml | 13 +- .../en-US/Useful_Scripts-traceio.xml | 16 ++- .../en-US/Useful_Scripts-traceio2.xml | 6 +- .../en-US/Useful_SystemTap_Scripts.xml | 26 +++- 9 files changed, 217 insertions(+), 17 deletions(-) create mode 100644 doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-iotime.xml (limited to 'doc/SystemTap_Beginners_Guide') diff --git a/doc/SystemTap_Beginners_Guide/en-US/Book_Info.xml b/doc/SystemTap_Beginners_Guide/en-US/Book_Info.xml index 09530ccc..f2876aad 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Book_Info.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Book_Info.xml @@ -4,11 +4,12 @@ SystemTap Beginners Guide - For use with Red Hat Enterprise Linux 5 - 1.0 + Introduction to SystemTap (for Red Hat Enterprise Linux 5) + Introduction to SystemTap (for Fedora Core 10) + 2.0 Red Hat Enterprise Linux 5.3 - 1 + 2 This guide provides basic instructions on how to use SystemTap to monitor different subsystems of &PRODUCT; in finer detail. The SystemTap Beginners Guide is recommended for users who have taken RHCT or have a similar level of expertise in &PRODUCT;. diff --git a/doc/SystemTap_Beginners_Guide/en-US/Revision_History.xml b/doc/SystemTap_Beginners_Guide/en-US/Revision_History.xml index d03a597b..d708da4f 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Revision_History.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Revision_History.xml @@ -20,6 +20,21 @@ + + + 2.0 + December 1, 2008 + + Don + Domingo + ddomingo@redhat.com + + + + Content now complete, pending tech review and other feedback for one final push. Build also includes index. + + + diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-disktop.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-disktop.xml index b57486d9..42f1986b 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-disktop.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-disktop.xml @@ -108,7 +108,14 @@ The time and date in the output of is returned by the functions ctime() and gettimeofday_s(). ctime() derives calendar time in terms of seconds passed since the Unix epoch (January 1, 1970). gettimeofday_s() counts the actual number of seconds since Unix epoch, which gives a fairly accurate human-readable timestamp for the output. -needinfo: what does $return do? + + In this script, the $return is a local variable that stores the + actual number of bytes each process reads or writes from the virtual file system. + $return can only be used in return probes (e.g. + vfs.read.return and vfs.read.return). + + + <xref linkend="scriptdisktop"/> Sample Output diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-iotime.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-iotime.xml new file mode 100644 index 00000000..21b6db9d --- /dev/null +++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-iotime.xml @@ -0,0 +1,140 @@ + + + +
+ Tracking I/O Time For Each File Read or Write + +script examples +monitoring I/O time + + + +examples of SystemTap scripts +monitoring I/O time + + + +monitoring I/O time +examples of SystemTap scripts + + + +I/O time, monitoring +examples of SystemTap scripts + + + +time of I/O +examples of SystemTap scripts + + + + + + This section describes how to monitor the amount of time it takes for each process to read + from or write to any file. This is useful if you wish to determine what files are slow to + load on a given system. + + + + iotime.stp + + + + + + + + + tracks each time a system call opens, closes, reads from, and writes + to a file. For each file any system call accesses, counts the number + of microseconds it takes for any reads or writes to finish and tracks the amount of data (in + bytes) read from or written to the file. + + + + also uses the local variable $count to track the + amount of data (in bytes) that any system call attempts to read or + write. Note that $return (as used in from + ) stores the actual amount of data + read/written. $count can only be used on probes that track data reads or + writes (e.g. syscall.read and syscall.write). + + + + + + <xref linkend="iotime"/> Sample Output + +[...] +3123380 2460 (pcscd) access /dev/bus/usb/005/001 read: 0 write: 0 +825946 3364 (NetworkManager) access /sys/class/net/eth0/carrier read: 8190 write: 0 +825955 3364 (NetworkManager) iotime /sys/class/net/eth0/carrier time: 9 +117061 2460 (pcscd) access /dev/bus/usb/003/001 read: 43 write: 0 +117065 2460 (pcscd) iotime /dev/bus/usb/003/001 time: 7 +3973737 2886 (sendmail) access /proc/loadavg read: 4096 write: 0 +3973744 2886 (sendmail) iotime /proc/loadavg time: 11 +[...] + + + + + prints out the following data: + + + + A timestamp, in microseconds + Process ID and process name + An access or + iotime flag + The file accessed + + + + If a process was able to read or write any data, a pair of + access and iotime lines + should appear together. The access line's timestamp refer to + the time that a given process started accessing a file; at the end of the line, it will show + the amount of data read/written (in bytes). The iotime line + will show the amount of time (in microseconds) that the process took in order to perform the + read or write. + + + + If an access line is not followed by an + iotime line, it simply means that the process did not read + or write any data. + + + + + +
\ No newline at end of file diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-iotop.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-iotop.xml index 8ec2af90..c5bbb480 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-iotop.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-iotop.xml @@ -40,7 +40,7 @@ -what does $count do, specifically? + prints out the top ten executables generating I/O traffic every 5-second interval, in descending order. Its output contains the process name and the amount of data read or written by the process, in KB. For example: diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-paracallgraph.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-paracallgraph.xml index e05e2bcf..301042f5 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-paracallgraph.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-paracallgraph.xml @@ -92,8 +92,17 @@ examples of SystemTap scripts - A trigger function (@1), which enables or disables tracing on a per-thread basis. - The kernel function whose entry/exit call you'd like to trace (@2). + + + A trigger function (@1), which + enables or disables tracing on a per-thread basis. Tracing in each thread + will continue as long as the trigger function has not exited yet. + + + + The kernel function/s whose entry/exit call you'd like to trace + (@2). + please verify previous if correct; i'm particularly interested in finding out how to better describe "trigger function" diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-traceio.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-traceio.xml index 0f914447..ab260d63 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-traceio.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-traceio.xml @@ -46,10 +46,22 @@ + -what do $return, $length, and $count return, specifically? when i substituted $return for $length here, script still ran but gave me bigger numbers. errored out with $length. where documented? + + prints the top ten executables generating I/O traffic over time. In + addition, it also tracks the cumulative amount of I/O reads and writes done by those ten + executables. This information is tracked and printed out in 1-second intervals, and in + descending order. + + + + Note that also uses the local variable $return, + which is also used by from . + - is similar to (from ); both SystemTap scripts print out the top ten executables generating I/O traffic over time. However, tracks the cumulative amount of I/O reads and writes done by the system's top ten executables. This information is tracked and printed out in 1-second intervals and in descending order. + <xref linkend="traceio"/> Sample Output diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-traceio2.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-traceio2.xml index 6800adaa..4fc7ecc2 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-traceio2.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-traceio2.xml @@ -125,9 +125,9 @@ semantic error: field 'f_dentry' not found The usrdev2kerndev() function converts the whole device number into the format understood by the kernel. The output produced by usrdev2kerndev() is used in conjunction with the MKDEV(), MINOR(), and MAJOR() functions to determine the major and minor numbers of a specific device. -The output of includes the name and ID of any process performing a read/write, the function it is performing (i.e. vfs_read or vfs_write), and the device number (in hex format). - -please verify if "0x800005" is "device number (in hex format)", and why it needs to be stated buy +The output of includes the name and ID of any process performing a read/write, the function it is performing (i.e. vfs_read or vfs_write), and the kernel device number. + The following example is an excerpt from the full output of stap traceio2.stp 0x805, where 0x805 is the whole device number of /home. /home resides in /dev/sda5, which is the device we wish to monitor. diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_SystemTap_Scripts.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_SystemTap_Scripts.xml index c17605db..8e089af6 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Useful_SystemTap_Scripts.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_SystemTap_Scripts.xml @@ -36,22 +36,38 @@ case studies and more info on some scripts here - http://sourceware.org/systemtap/wiki/WarStories + + +
+ Disk + The following sections showcase scripts that monitor disk and I/O activity. + - + - - + +
+ +
+ Profiling + The following sections showcase scripts that profile kernel activity by monitoring function calls. + + +
- +
+ Network + The following sections showcase scripts that trace network-related functions and build a profile of network activity. - +
+