From 3266a355a8d41eee4e49ce6aa841a5166e3f6fe9 Mon Sep 17 00:00:00 2001 From: William Cohen Date: Tue, 4 Nov 2008 01:43:48 -0500 Subject: Include staprep.sh script and make use of it in describing Systemtap setup. --- .../en-US/CrossInstrumenting.xml | 295 ++++++++++++++------- 1 file changed, 201 insertions(+), 94 deletions(-) (limited to 'doc/SystemTap_Beginners_Guide/en-US/CrossInstrumenting.xml') diff --git a/doc/SystemTap_Beginners_Guide/en-US/CrossInstrumenting.xml b/doc/SystemTap_Beginners_Guide/en-US/CrossInstrumenting.xml index b0d712bd..6a91beab 100644 --- a/doc/SystemTap_Beginners_Guide/en-US/CrossInstrumenting.xml +++ b/doc/SystemTap_Beginners_Guide/en-US/CrossInstrumenting.xml @@ -2,35 +2,61 @@ -
- Cross-Instrumentation +
+ Generating Instrumentation for Other Computers -cross-compiling script from here: http://sources.redhat.com/ml/systemtap/2008-q3/msg00310.html + + cross-compiling script from here: + http://sources.redhat.com/ml/systemtap/2008-q3/msg00310.html + -above; add short description, significance, howto, script (test first) - - When users run a SystemTap script, SystemTap builds a kernel module out of that script. SystemTap then loads the module onto the kernel, allowing it to extract the specified data directly from the kernel (refer to in for more information). - + + above; add short description, significance, howto, script (test first) + + + + When users run a SystemTap script, SystemTap builds a kernel module out of + that script. SystemTap then loads the module onto the kernel, allowing it to + extract the specified data directly from the kernel (refer to + in + for more information). + - - 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'd need to deploy SystemTap on all those systems. - - - - In some cases, this may be neither feasible nor desired. For instance, running SystemTap on 25 systems — all of which are using a different kernel — may require fully deploying SystemTap on all 25 machines. This task may even increase in complexity if some (or all) systems are remote from the administrator. Sometimes, corporate policy may prohibit an administrator from installing a debug version of an RPM on specific machines, which will prevent the deployment of SystemTap altogether. - + + 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 proved debug information or compilers 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 compiling a kernel module (out of a SystemTap script) to be used on a different machine. 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 machine. This process offers + the following benefits: + - - The debug RPMs for all target machines can be installed into one system: the host machine. - - Each target machine only needs one RPM to load and use the compiled kernel module: systemtap-runtime. - - You do not need to restart any of the target machines. - + + + + The debug RPMs for various machines can be installed on a single system: + the host machine. + + + + + + Each target machine only needs one RPM to installed to use + the generated SystemTap instrumentation module: + systemtap-runtime. + + + - -Note -For the sake of simplicity, we will be using the following terms throughout this section: - - - instrumentation module — the kernel module built from a SystemTap script; i.e. the SystemTap module is built on the host system, and will be loaded on the target kernel of target system. + + Note + + + For the sake of simplicity, we will be using the following terms + throughout this section: + + + + + + instrumentation module — the + kernel module built from a SystemTap script; i.e. the + SystemTap module is built on the host + system, and will be loaded on the target + kernel of target + system. + + - host system — the system on which you compile the kernel modules (from SystemTap scripts), to be loaded on target systems. + + + host system — the system on + which you compile the instrumentation modules (from SystemTap + scripts), to be loaded on target + systems. + + - target system — the system for which you are building the instrumentation module (from SystemTap scripts). + + + target system — the system for which you + are building the instrumentation module (from + SystemTap scripts). + + - target kernel — the kernel of the target system. This is the kernel on which you wish to load/run the instrumentation module. - - + + + target kernel — the kernel of + the target system. This is the kernel on which + you wish to load/run the instrumentation + module. + + + + - - - Configuring a Host System and Target Systems - - - Configure yum on the host system to point to a repository containing the necessary debug RPMs for the target kernels. The following yum repository file (which you can add to /etc/yum.repos.d/ points to a popular debug RPM repository for i386 systems running Red Hat Enterprise Linux 5: - -[rhel-debuginfo] -name=Red Hat Enterprise Linux $releasever - $basearch - Debug - -baseurl=ftp://ftp.redhat.com/pub/redhat/linux/enterprise/5Client/en/os/i386/Debuginfo/ -enabled=1 - - - - - Deploy SystemTap on the host system. It is from this machine that you will be building the instrumentation module (to be used on target systems). For instructions on how to deploy SystemTap, refer to . - - - - Install the target kernel on the host system. If multiple target systems use different target kernel, you will need to install each target kernel. - - - - - Install the corresponding debug RPMs for the target kernel of each target system on the host system. - - - - Install yum-utils on the host system. - - - - Install systemtap-runtime on each target system. - - -After performing , you can now build the instrumentation module (for any target system) on the host system. + + Configuring a Host System and Target Systems -To build the instrumentation module, run the following command on the host system (be sure to specify the appropriate values): + + + Install the systemtap-runtime RPM on each + target system. + + -stap -r kernel version script -m module name + + + Determine the kernel running on each target system + by running the by running uname -r on each + target system: + + -Here, kernel version refers to the version of target kernel (including the architecture notation), script refers to the script to be converted into an instrumentation module, and instrumentation name is the desired name of the instrumentation module. + + + Install SystemTap on the host system. It is from + this machine that you will be building the instrumentation + module (to be used on target + systems). For instructions on how to install SystemTap, refer + to . + + - - Note - To determine the architecture notation of a running kernel, run uname -m. - - + + + Using the target kernel version determined earlier, + install the target kernel and related RPMs on the + host system by the method described in . If multiple target + systems use different target kernels, + you will need to repeat this step for each different kernel used on the + target systems. + + -Once the the instrumentation module is compiled, copy it to the target system and load it using: + -staprun instrumentation + + After performing , you can now build the + instrumentation module (for any target + system) on the host system. + - - For example, to create the instrumentation module simple.ko from a SystemTap script named simple.stp for the target kernel 2.6.25.9-76.fc9 (on i686 architecture), use the following command: - - -stap -r 2.6.25.9-76.fc9.x86_64 simple.stp -m module + + To build the instrumentation module, run the following + command on the host system (be sure to specify the + appropriate values): + + + + stap -r kernel_version + script -m + module_name + + + + Here, kernel_version refers to + the version of the target kernel (the output of + uname -r on the target machine), + script refers to the script to + be converted into an instrumentation module, and + module_name is the desired + name of the instrumentation module. + + + + Note + + To determine the architecture notation of a running kernel, run + uname -m. + + + + + Once the the instrumentation module is compiled, copy + it to the target system and load it using: + + + + staprun module_name.ko + + + + For example, to create the instrumentation module + simple.ko from a SystemTap script named + simple.stp for the target kernel + 2.6.18-92.1.10.el5 (on x86_64 architecture), use the following command: + + + + stap -r 2.6.18-92.1.10.el5 -e 'probe vfs.read {exit()}' -m simple + -This will create a module named simple.ko. To use the instrumentation module simple.ko, copy it to the target system and run the following command (on the target system): + + This will create a module named simple.ko. To use the + instrumentation module simple.ko, + copy it to the target system and run the following + command (on the target system): + -staprun simple.ko + staprun simple.ko - - Important - The host system must be the same architecture as the target system in order for the instrumentation module to work. - + + Important + + The host system must be the same architecture and + running the same distribution of Linux as the target + system in order for the instrumentation + module to work. + + -
\ No newline at end of file +
-- cgit