From d706e984ee8c60d278859a15c74b5a60829789f7 Mon Sep 17 00:00:00 2001 From: ddomingo Date: Wed, 5 Nov 2008 10:35:18 +1000 Subject: proofreading run 1 --- .../en-US/CrossInstrumenting.xml | 30 ++++--------- .../en-US/Installation.xml | 50 +++++++++------------- .../en-US/Introduction.xml | 9 +++- .../en-US/Useful_Scripts-inodewatch.xml | 3 ++ 4 files changed, 39 insertions(+), 53 deletions(-) (limited to 'doc/SystemTap_Beginners_Guide/en-US') diff --git a/doc/SystemTap_Beginners_Guide/en-US/CrossInstrumenting.xml b/doc/SystemTap_Beginners_Guide/en-US/CrossInstrumenting.xml index a16e4f48..8a772f15 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/CrossInstrumenting.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/CrossInstrumenting.xml @@ -23,22 +23,11 @@ - Normally, however, SystemTap scripts can only be run on systems where - SystemTap is deployed (as in ). This could - mean that if you want to run SystemTap on ten systems, you would need to - deploy SystemTap on all those systems. In some cases, - this may be neither feasible nor desired to fully deploy SystemTap on those - systems. For instance corporate policy may prohibit an administrator from - installing RPMs that provide compilers or debug information on specific - machines, which will prevent the deployment of SystemTap. + Normally, however, SystemTap scripts can only be run on systems where SystemTap is deployed (as in ). This could mean that if you want to run SystemTap on ten systems, you would need to deploy SystemTap on all those systems. In some cases, this may be neither feasible nor desired. For instance, corporate policy may prohibit an administrator from installing RPMs that provide compilers or debug information on specific machines, which will prevent the deployment of SystemTap. - To work around this, you can resort to - cross-instrumentation. Cross-instrumentation is the - process of generating SystemTap instrumentation module from a SystemTap - script on one computer to be used on another computer. This process offers - the following benefits: + To work around this, you can resort to cross-instrumentation. Cross-instrumentation is the process of generating SystemTap instrumentation module from a SystemTap script on one computer to be used on another computer. This process offers the following benefits: @@ -186,10 +175,9 @@ appropriate values): - - stap -r kernel_version script -m - module_name - + +stap -r kernel_version script -m module_name + Here, kernel_version refers to @@ -214,9 +202,9 @@ it to the target system and load it using: - - staprun module_name.ko - + +staprun module_name.ko + For example, to create the instrumentation module @@ -249,7 +237,7 @@ The host system must be the same architecture and running the same distribution of Linux as the target - system in order for the instrumentation + system in order for the built instrumentation module to work. diff --git a/doc/SystemTap_Beginners_Guide/en-US/Installation.xml b/doc/SystemTap_Beginners_Guide/en-US/Installation.xml index f2c0cd92..80ee8bd7 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Installation.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Installation.xml @@ -121,42 +121,34 @@ - If the yum-utils package is installed on the computer and has access to - the yum repositories, - the stapprep.sh script can be run - by root to download and install the needed kernel packages via - yum and rpm commands. Thus, the - system administrator should be able to install the needed RPMs with the - script on the machine: + If the yum-utils package is installed and the yum repositories are set up properly, you can run the script as root. will automatically download and install the required packages via yum and rpm commands (assuming that the kernel you wish to probe is currently loaded). - - ./stapprep.sh - - - If yum is not available on a Red Hat Enterprise Linux - 5 machine, the following lines of bash script will generate the URL for - the debuginfo RPM directory: - - - + + If you do not have yum installed and you are unable to install it, you will have to manually download and install the required packages. To generate the URL from which to download the required packages, use the following script: + + + + systemtapurl.sh + + pkg=`grep distroverpkg /etc/yum.conf |awk -F= '{print $2}'` releasever=`rpm -q --qf "%{version}" $pkg` base=`uname -m` echo "ftp://ftp.redhat.com/pub/redhat/linux/enterprise/$releasever/en/os/$base" - + + + - - If yum in not available on a Fedora system, the - following lines of bash script will generate the URL for the location to - find the needed kernel RPMs: - - + + systemtapurl.sh + + echo -n "Enter nvr of kernel-debuginfo (e.g. 2.6.25-14.fc9.x86_64) " ; \ read NVR; \ BASE=`uname -m` ; \ @@ -165,13 +157,11 @@ VERSION=`echo $NVR | awk -F- '{print $1}'` ; \ RELEASE=`echo $NVR | awk -F- '{print $2}'` ; \ echo "http://kojipkgs.fedoraproject.org/\ packages/kernel/$VERSION/$RELEASE/$BASE/" - - + + + - The package RPMs can be manually downloaded and copied to the - machine. Once you have manually copied the packages to the - machine, install the RPMs by running rpm --force -ivh - package_names. +Once you have manually downloaded the required packages to the machine, install the RPMs by running rpm --force -ivh package_names. diff --git a/doc/SystemTap_Beginners_Guide/en-US/Introduction.xml b/doc/SystemTap_Beginners_Guide/en-US/Introduction.xml index 36dd3c44..dbca02fc 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Introduction.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Introduction.xml @@ -8,11 +8,16 @@ SystemTap is a tracing and probing tool that allows users to study and monitor the activities of the operating system (particularly, the kernel) in fine detail. It provides information similar to the output of tools like netstat, ps, top, and iostat; however, SystemTap is designed to provide more filtering and analysis options for collected information. - + For system administrators, SystemTap can be used as a performance monitoring tool for ∏. It is most useful when other similar tools cannot precisely pinpoint a bottleneck in the system, requiring a deep analysis of kernel activity. In the same manner, application developers can also use SystemTap to monitor, in finer detail, how their application behaves within the Linux system. + + For system administrators, SystemTap can be used as a performance monitoring tool for &PROD2;. It is most useful when other similar tools cannot precisely pinpoint a bottleneck in the system, requiring a deep analysis of kernel activity. In the same manner, application developers can also use SystemTap to monitor, in finer detail, how their application behaves within the Linux system. + + +
Documentation Goals - SystemTap provides the infrastructure to monitor the running Linux kernel for detailed analysis. This can assist administrators and developers in identifying the underlying cause of a performance or functional problem. + SystemTap provides the infrastructure to monitor the running Linux kernel for detailed analysis. This can assist administrators and developers in identifying the underlying cause of a bug or performance problem. Without SystemTap, monitoring the activity of a running kernel would require a tedious instrument, recompile, install, and reboot sequence. SystemTap is designed to eliminate this, allowing users to gather the same information by simply running user-written SystemTap scripts. diff --git a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-inodewatch.xml b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-inodewatch.xml index 2ac1366d..e747771b 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-inodewatch.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Useful_Scripts-inodewatch.xml @@ -27,6 +27,9 @@ no script in examples +need to add references to sources/man pages that explain how "dev_nr = $file->f_dentry->d_inode->i_sb->s_dev" and "($1 << 20 | $2)". + + takes the following information about the file as an argument: -- cgit From cb832b7130a189173df1d00b5d52f50350247e08 Mon Sep 17 00:00:00 2001 From: ddomingo Date: Wed, 5 Nov 2008 11:17:37 +1000 Subject: proofreading run 2 --- .../en-US/Installation.xml | 72 ++++++++++------------ 1 file changed, 34 insertions(+), 38 deletions(-) (limited to 'doc/SystemTap_Beginners_Guide/en-US') diff --git a/doc/SystemTap_Beginners_Guide/en-US/Installation.xml b/doc/SystemTap_Beginners_Guide/en-US/Installation.xml index 80ee8bd7..e5384abc 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Installation.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Installation.xml @@ -34,10 +34,9 @@
- Installating SystemTap + Installing SystemTap - For the Systemtap Beginner's Guide the following two SystemTap RPMs - need to be installed: + To deploy Systemtap, you will need to to install the following RPMs: @@ -45,24 +44,15 @@ systemtap-runtime - Assuming that the computer system has been configured to use Red Hat - Network (RHN) or yum is available, - the two rpms can be installed with yum install - systemtap systemtap-runtime. Before you use SystemTap the - additional kernel information will need to be installed as described in - the following section. + Assuming that your system is configured to use Red Hat Network (RHN) or yum is available, these two rpms can be installed with yum install systemtap systemtap-runtime. Note that before you can use SystemTap, you will still need to install the required kernel information RPMs.
- Installing Needed Kernel Information + Installing Required Kernel Information RPMs - SystemTap makes use of the information in additional kernel RPMs to - determine where to place instrumentation in the kernel and how to generate - code for the instrumentation. You will need to download and install the - necessary -devel and -debuginfo - packages for your kernel. The necessary -devel and + SystemTap needs information about the kernel in order to place instrumentation in it (i.e. probe it). This information also allows SystemTap to generate the code for the instrumentation. This information is contained in the matching -devel and -debuginfo packages for your kernel. The necessary -devel and -debuginfo packages for the ordinary "vanilla" kernel are as follows: @@ -75,14 +65,11 @@ To determine what kernel your system is currently using, use: - - uname -r - - - For example, if you wish to use SystemTap on kernel version - 2.6.18-53.el5 on an i686 machine, - then you would need to download and - install the following RPMs: + +uname -r + + + For example, if you wish to use SystemTap on kernel version 2.6.18-53.el5 on an i686 machine, then you would need to download and install the following RPMs: @@ -95,21 +82,30 @@ Important - The version and architecture of the -devel, - -debuginfo and - -debuginfo-common packages must match the kernel - you wish to probe with SystemTap exactly. + The version and architecture of the -devel, -debuginfo and -debuginfo-common packages must match the kernel you wish to probe with SystemTap exactly. - The script can be used by normal users to - determine what supporting kernel RPMs need to be installed on the - machine to use SystemTap with a particular kernel. The script run - without any arguments detemines the RPMs needed for the currently - running kernel. The script can also accept one argument, the output - uname -r, to determine the related RPMs required - for a kernel that may not be currently running on the machine. - + + To help ease your deployment of SystemTap, you can use . You can use to detemine the kernel information packages you need to install in order to run SystemTap. If you run (as an ordinary, non-root user) without any arguments, it will display the kernel information packages required for the loaded kernel. You can also pass a specific kernel version to (e.g. 2.6.18-92.el5) if you wish to probe a kernel that is not currently loaded. + + + + Note + Running as root will display the required kernel packages and install them as well, provided that yum and yum-utils are configured properly. + + + + + stapprep.sh @@ -119,17 +115,17 @@ - + - If you do not have yum installed and you are unable to install it, you will have to manually download and install the required packages. To generate the URL from which to download the required packages, use the following script: + If you do not have yum and yum-utils installed (and you are unable to install them), you will have to manually download and install the required kernel information packages. To generate the URL from which to download the required packages, use the following script: -- cgit From 73805e7c1b9ac98db04c4b2e524c5bbb409c8aeb Mon Sep 17 00:00:00 2001 From: ddomingo Date: Wed, 5 Nov 2008 16:29:20 +1000 Subject: proofread run 3 --- .../en-US/CrossInstrumenting.xml | 7 +-- .../en-US/Using_SystemTap.xml | 63 +++++++++++----------- 2 files changed, 35 insertions(+), 35 deletions(-) (limited to 'doc/SystemTap_Beginners_Guide/en-US') diff --git a/doc/SystemTap_Beginners_Guide/en-US/CrossInstrumenting.xml b/doc/SystemTap_Beginners_Guide/en-US/CrossInstrumenting.xml index 8a772f15..5e29307c 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/CrossInstrumenting.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/CrossInstrumenting.xml @@ -33,16 +33,13 @@ - The debug RPMs for various machines can be installed on a single system: - the host machine. + The kernel information packages for various machines can be installed on a single host machine. - Each target machine only needs one RPM to installed to use - the generated SystemTap instrumentation module: - systemtap-runtime. + Each target machine only needs one RPM to installed to use the generated SystemTap instrumentation module: systemtap-runtime. diff --git a/doc/SystemTap_Beginners_Guide/en-US/Using_SystemTap.xml b/doc/SystemTap_Beginners_Guide/en-US/Using_SystemTap.xml index 447f3d62..1a21dbcb 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/Using_SystemTap.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/Using_SystemTap.xml @@ -28,14 +28,44 @@ SystemTap scripts are run through the command stap. stap can run SystemTap scripts from standard input or from file. - + + + + Running stap and staprun requires elevated privileges to the system. However, not all users can be granted root access just to run SystemTap. In some cases, for instance, you may want to allow a non-privileged user to run SystemTap instrumentation on his machine. + + +To allow ordinary users to run SystemTap without root access, add them to one of these user groups: + + + + + stapdev + + + Members of this group can use stap to run SystemTap scripts, or staprun to run SystemTap instrumentation modules. + + + + + + stapusr + + + Members of this group can only run staprun to run SystemTap instrumentation modules. In addition, they can only run those modules from /lib/modules/kernel_version/systemtap/. Note that this directory must be owned only by the root user, and must only be writable by the root user. + + + + + + + Below is a list of commonly used stap options: @@ -117,33 +147,6 @@ echo "probe timer.s(1) {exit()}" | stap - The stap options -v and -o also work for staprun. For more information about staprun, refer to man staprun. - - stapdev and stapusr - Running stap and staprun requires elevated privileges to the system. However, not all users can be granted root access just to run SystemTap. In some cases, for instance, you may want to allow a non-privileged user to run SystemTap instrumentation on his machine. - - -To allow ordinary users to run SystemTap without root access, add them to one of these user groups: - - - - - stapdev - - - Members of this group can use stap to run SystemTap scripts, or staprun to run SystemTap instrumentation modules. - - - - - - stapusr - - - Members of this group can only run staprun to run SystemTap instrumentation modules. In addition, they can only run those modules from /lib/modules/kernel_version/systemtap/. Note that this directory must be owned only by the root user, and must only be writable by the root user. - - - -
-- cgit