2.2. Generating Instrumentation for Other Computers
Normally, however, SystemTap scripts can only be run on systems where SystemTap is deployed (as in
Section 2.1, “Installation and Setup”). 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 RPM packages that provide compilers or debug information on specific machines, and thus prevent the deployment of SystemTap. To work around this problem, SystemTap allows you to use
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:
The kernel information packages for various machines can be installed on a single host machine.
Each target machine only needs one RPM package to be installed in order to use the generated SystemTap instrumentation module: the systemtap-runtime package.
For the sake of simplicity, the following terms are used throughout this section:
Instrumentation module — the kernel module built from a SystemTap script. 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
instrumentation modules from SystemTap scripts in order to load them on
target systems.
Target system — the system for which you are building the
instrumentation modules from SystemTap scripts.
Target kernel — the kernel of the
target system. This is the kernel on which you intend to load or run the
instrumentation module.
To configure a host system and target systems, complete the following steps:
Install the systemtap-runtime package on each target system.
Determine the kernel running on each target system by running the uname -r
command on each of these systems.
Install SystemTap on the
host system. You will be building the
instrumentation module for the
target systems on the
host system. For instructions on how to install SystemTap, refer to
Section 2.1.1, “Installing SystemTap”.
After completing these steps, you can now build the instrumentation module (for any target system) on the host system.
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 the uname -r
command on the target machine), script refers to the script to be converted into the instrumentation module, and module_name is the desired name of the instrumentation module.
To determine the architecture notation of a running kernel, you can run the following command:
uname -m
Once the instrumentation module is compiled, copy it to the target system and then 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 creates a module named simple.ko
. To use this instrumentation module, copy it to the target system and run the following command (on the target system):
staprun simple.ko
The host system must be the same architecture and running the same distribution of Linux as the target system in order for the built instrumentation module to work.