1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 | <?xml version="1.0" encoding="UTF-8" standalone="no"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title xmlns:d="http://docbook.org/ns/docbook">Chapter 2. Using SystemTap</title><link rel="stylesheet" type="text/css" href="Common_Content/css/default.css" /><link rel="stylesheet" media="print" href="Common_Content/css/print.css" type="text/css" /><meta xmlns:d="http://docbook.org/ns/docbook" name="generator" content="not publican" /><meta xmlns:d="http://docbook.org/ns/docbook" name="package" content="" /><link rel="home" href="index.html" title="SystemTap Beginners Guide" /><link rel="up" href="index.html" title="SystemTap Beginners Guide" /><link rel="prev" href="intro-systemtap-limitations.html" title="1.3. Limitations of SystemTap" /><link rel="next" href="cross-compiling.html" title="2.2. Generating Instrumentation for Other Computers" /></head><body><p id="title"></p><ul class="docnav top"><li class="previous"><a accesskey="p" href="intro-systemtap-limitations.html"><strong>Prev</strong></a></li><li class="home">SystemTap Beginners Guide</li><li class="next"><a accesskey="n" href="cross-compiling.html"><strong>Next</strong></a></li></ul><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="using-systemtap"> </a>Chapter 2. Using SystemTap</h1></div></div></div><div class="toc"><dl class="toc"><dt><span class="section"><a href="using-systemtap.html#using-setup">2.1. Installation and Setup</a></span></dt><dd><dl><dt><span class="section"><a href="using-systemtap.html#installproper">2.1.1. Installing SystemTap</a></span></dt><dt><span class="section"><a href="using-systemtap.html#install-kinfo">2.1.2. Installing Required Kernel Information Packages Manually</a></span></dt><dt><span class="section"><a href="using-systemtap.html#testing">2.1.3. Initial Testing</a></span></dt></dl></dd><dt><span class="section"><a href="cross-compiling.html">2.2. Generating Instrumentation for Other Computers</a></span></dt><dt><span class="section"><a href="using-usage.html">2.3. Running SystemTap Scripts</a></span></dt><dd><dl><dt><span class="section"><a href="using-usage.html#flight-recorder">2.3.1. SystemTap Flight Recorder Mode</a></span></dt></dl></dd></dl></div><a id="id1576" class="indexterm"></a><div class="para"> This chapter documents how to install SystemTap in the system and explains how to use the <code class="command">stap</code> utility to run SystemTap scripts. </div><div class="section"><div class="titlepage"><div><div><h2 class="title"><a id="using-setup"> </a>2.1. Installation and Setup</h2></div></div></div><a id="id1584" class="indexterm"></a><a id="id1587" class="indexterm"></a><div class="para">To deploy SystemTap, install the SystemTap packages along with the corresponding set of <span class="package">-devel</span>, <span class="package">-debuginfo</span>, and <span class="package">-debuginfo-common</span> packages for your kernel. If your system has multiple kernels installed and you intend to use SystemTap on more than one of them, also install the <span class="package">-devel</span> and <span class="package">-debuginfo</span> packages for <span class="emphasis"><em>each</em></span> of those kernel versions. </div><div class="para">The following sections discuss the installation procedures in greater detail. </div><div xmlns:d="http://docbook.org/ns/docbook" class="important"><div class="admonition_header"><p><strong>Important</strong></p></div><div class="admonition"><div class="para">Many users confuse <span class="package">-debuginfo</span> with <span class="package">-debug</span>. Remember that the deployment of SystemTap requires the installation of the <span class="package">-debuginfo</span> package of the kernel, not the <span class="package">-debug</span> version of the kernel.</div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="installproper"> </a>2.1.1. Installing SystemTap</h3></div></div></div><div class="para">To deploy SystemTap, install the following RPM packages: </div><a id="id1607" class="indexterm"></a><a id="id1610" class="indexterm"></a><a id="id1612" class="indexterm"></a><a id="id1615" class="indexterm"></a><div xmlns:d="http://docbook.org/ns/docbook" class="itemizedlist"><ul><li class="listitem"><div class="para"><span class="package">systemtap</span></div></li><li class="listitem"><div class="para"><span class="package">systemtap-runtime</span></div></li></ul></div><div class="para"> To do so, run the following command as root: </div><pre class="screen"><code class="command">yum install systemtap systemtap-runtime</code></pre><div class="para"> Note that before using SystemTap, you still need to install the required kernel information packages. On modern systems, run the following command as root to install these packages: </div><pre class="screen"><code class="command">stap-prep</code></pre><div class="para"> If this command does not work, try manual installation as described below. </div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="install-kinfo"> </a>2.1.2. Installing Required Kernel Information Packages Manually</h3></div></div></div><a id="id1633" class="indexterm"></a><a id="id1636" class="indexterm"></a><a id="id1638" class="indexterm"></a><a id="id1640" class="indexterm"></a><a id="id1642" class="indexterm"></a><a id="id1645" class="indexterm"></a><div class="para"> SystemTap needs information about the kernel in order to place instrumentation in it (in other words, probe it). This information also allows SystemTap to generate the code for the instrumentation. </div><div class="para"> The required information is contained in the matching <span class="package">-devel</span>, <span class="package">-debuginfo</span>, and <span class="package">-debuginfo-common</span> packages for your kernel. The necessary <span class="package">-devel</span> and <span class="package">-debuginfo</span> packages for the ordinary "vanilla" kernel are as follows: </div><div xmlns:d="http://docbook.org/ns/docbook" class="itemizedlist"><ul><li class="listitem"><div class="para"><span class="package">kernel-debuginfo</span></div></li><li class="listitem"><div class="para"><span class="package">kernel-debuginfo-common</span></div></li><li class="listitem"><div class="para"><span class="package">kernel-devel</span></div></li></ul></div><div class="para"> Likewise, the necessary packages for the PAE kernel are <span class="package">kernel-PAE-debuginfo</span>, <span class="package">kernel-PAE-debuginfo-common</span>, and <span class="package">kernel-PAE-devel</span>. </div><a id="id1668" class="indexterm"></a><a id="id1671" class="indexterm"></a><a id="id1673" class="indexterm"></a><a id="id1675" class="indexterm"></a><div class="para"> To determine what kernel your system is currently using, use:</div><pre class="screen">uname -r</pre><div class="para"> For example, if you intend to use SystemTap on kernel version <span class="emphasis"><em>2.6.18-53.el5</em></span> on an <span class="emphasis"><em>i686</em></span> machine, download and install the following RPM packages: </div><div xmlns:d="http://docbook.org/ns/docbook" class="itemizedlist"><ul><li class="listitem"><div class="para"><span class="package">kernel-debuginfo-2.6.18-53.1.13.el5.i686.rpm</span></div></li><li class="listitem"><div class="para"><span class="package">kernel-debuginfo-common-2.6.18-53.1.13.el5.i686.rpm</span></div></li><li class="listitem"><div class="para"><span class="package">kernel-devel-2.6.18-53.1.13.el5.i686.rpm</span></div></li></ul></div><div xmlns:d="http://docbook.org/ns/docbook" class="important"><div class="admonition_header"><p><strong>Important</strong></p></div><div class="admonition"><div class="para"> The version, variant, and architecture of the <span class="package">-devel</span>, <span class="package">-debuginfo</span> and <span class="package">-debuginfo-common</span> packages must match the kernel you wish to probe with SystemTap <span class="emphasis"><em>exactly</em></span>. </div></div></div><div class="para"> The easiest way to install the required kernel information packages is through <code class="command">yum install</code> and <code class="command">debuginfo-install</code> commands. The <code class="command">debuginfo-install</code> command is included with later versions of the <span class="package">yum-utils</span> package (for example, version 1.1.10) and also requires an appropriate <code class="command">yum</code> repository from which to download and install <span class="package">-debuginfo</span> and <span class="package">-debuginfo-common</span> packages. You can install the required <span class="package">-devel</span>, <span class="package">-debuginfo</span>, and <span class="package">-debuginfo-common</span> packages for your kernel. </div><div class="para"> When the appropriate software repositories are enabled, install the corresponding packages for a specific kernel with the following commands: </div><pre class="screen"><code class="command">yum install <em class="replaceable">kernelname</em>-devel-<em class="replaceable">version</em></code> <code class="command">debuginfo-install <em class="replaceable">kernelname</em>-<em class="replaceable">version</em></code></pre><div class="para"> Replace <em class="replaceable">kernelname</em> with the appropriate kernel variant name (for example, <code class="option">kernel-PAE</code>), and <em class="replaceable">version</em> with the target kernel's version. For example, to install the required kernel information packages for the <code class="systemitem">kernel-PAE-2.6.18-53.1.13.el5</code> kernel, run: </div><pre class="screen"><code class="command">yum install kernel-PAE-devel-2.6.18-53.1.13.el5</code> <code class="command">debuginfo-install kernel-PAE-2.6.18-53.1.13.el5</code></pre><div class="para"> Once you have manually downloaded the required packages to the machine, run the following command as root to install them: </div><pre class="screen"><code class="command">rpm --force -ivh <em class="replaceable">package_names</em></code></pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="testing"> </a>2.1.3. Initial Testing</h3></div></div></div><a id="id1732" class="indexterm"></a><a id="id1735" class="indexterm"></a><a id="id1737" class="indexterm"></a><div class="para">If you are currently using the kernel you intend to probe with SystemTap, you can immediately test whether the deployment was successful. If not, you restart the system and load the appropriate kernel. </div><div class="para"> To start the test, run the following command: </div><pre class="screen"><code class="command">stap -v -e 'probe vfs.read {printf("read performed\n"); exit()}'</code></pre><div class="para"> This command instructs SystemTap to print <code class="computeroutput">read performed</code> and then exit properly once a virtual file system read is detected. If the SystemTap deployment was successful, it prints output similar to the following: </div><pre class="screen">Pass 1: parsed user script and 45 library script(s) in 340usr/0sys/358real ms. Pass 2: analyzed script: 1 probe(s), 1 function(s), 0 embed(s), 0 global(s) in 290usr/260sys/568real ms. Pass 3: translated to C into "/tmp/stapiArgLX/stap_e5886fa50499994e6a87aacdc43cd392_399.c" in 490usr/430sys/938real ms. Pass 4: compiled C into "stap_e5886fa50499994e6a87aacdc43cd392_399.ko" in 3310usr/430sys/3714real ms. Pass 5: starting run. read performed Pass 5: run completed in 10usr/40sys/73real ms.</pre><div class="para"> The last three lines of the output (beginning with <code class="computeroutput">Pass 5</code>) indicate that SystemTap was able to successfully create the instrumentation to probe the kernel, run the instrumentation, detect the event being probed (in this case, a virtual file system read), and execute a valid handler (print text then close it with no errors). </div></div></div></div><ul class="docnav"><li class="previous"><a accesskey="p" href="intro-systemtap-limitations.html"><strong>Prev</strong>1.3. Limitations of SystemTap</a></li><li class="up"><a accesskey="u" href="#"><strong>Up</strong></a></li><li class="home"><a accesskey="h" href="index.html"><strong>Home</strong></a></li><li class="next"><a accesskey="n" href="cross-compiling.html"><strong>Next</strong>2.2. Generating Instrumentation for Other Compute...</a></li></ul></body></html>
|
