<?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>Chapter 4. User-Space Probing</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 name="generator" content="publican 2.8" /><meta name="package" content="Systemtap-SystemTap_Beginners_Guide-2.1-en-US-2.1-2" /><link rel="home" href="index.html" title="SystemTap Beginners Guide" /><link rel="up" href="index.html" title="SystemTap Beginners Guide" /><link rel="prev" href="understanding-tapsets.html" title="3.6. Tapsets" /><link rel="next" href="utargetvariable.html" title="4.2. Accessing User-Space Target Variables" /></head><body><p id="title"><a class="left" href="http://www.fedoraproject.org"><img src="Common_Content/images/image_left.png" alt="Product Site" /></a><a class="right" href="http://docs.fedoraproject.org"><img src="Common_Content/images/image_right.png" alt="Documentation Site" /></a></p><ul class="docnav"><li class="previous"><a accesskey="p" href="understanding-tapsets.html"><strong>Prev</strong></a></li><li class="next"><a accesskey="n" href="utargetvariable.html"><strong>Next</strong></a></li></ul><div xml:lang="en-US" class="chapter" id="userspace-probing" lang="en-US"><div class="titlepage"><div><div><h2 class="title">Chapter 4. User-Space Probing</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="userspace-probing.html#uevents">4.1. User-Space Events</a></span></dt><dt><span class="section"><a href="utargetvariable.html">4.2. Accessing User-Space Target Variables</a></span></dt><dt><span class="section"><a href="ustack.html">4.3. User-Space Stack Backtraces</a></span></dt></dl></div><div class="para">
SystemTap initially focused on kernel-space probing. However, there are many instances where user-space probing can help diagnose a problem. SystemTap 0.6 added support to allow probing user-space processes. SystemTap includes support for probing the entry into and return from a function in user-space processes, probing predefined markers in user-space code, and monitoring user-process events.
</div><div class="para">
The SystemTap user-space probing requires the utrace kernel extensions which provide an API for tracking various user-space events. More details about the utrace infrastructure are available at <a href="http://sourceware.org/systemtap/wiki/utrace">http://sourceware.org/systemtap/wiki/utrace</a>. The following command determines whether the currently running Linux kernel provides the needed utrace support:
</div><pre class="screen">grep CONFIG_UTRACE /boot/config-`uname -r`</pre><div class="para">
If the Linux kernel support user-space probing, the following output is printed:
</div><pre class="screen">CONFIG_UTRACE=y</pre><div class="para">
The SystemTap user-space probing also needs the uprobes kernel module. If the uprobes kernel module is not available, you will see an error message like the following when attempting to run a script that requires the uprobes kernel module:
</div><pre class="screen">SystemTap's version of uprobes is out of date.
As root, or a member of the 'root' group, run
"make -C /usr/share/systemtap/runtime/uprobes".
Pass 4: compilation failed. Try again with another '--vp 0001' option.</pre><div class="para">
If this occurs, you need to generate a uprobes.ko module for the kernel as directed.
</div><div class="section" id="uevents"><div class="titlepage"><div><div keep-together.within-column="always"><h2 class="title" id="uevents">4.1. User-Space Events</h2></div></div></div><a id="idm9580528" class="indexterm"></a><div class="para">
All user-space event probes begin with <span class="emphasis"><em>process</em></span>. The process events can be limited to a specific running process by specifying the process ID. The process events can also be limited to monitoring a particular executable by specifying the path to executable (PATH). SystemTap makes use of the <code class="command">PATH</code> environment variable, so both the name used on the command-line to start the executable and the absolute path to the executable can be used. Several of user-space probe events limit their scope to a particular executable name (PATH) because SystemTap must use debug information to statically analyzed where to places the probes, but for many user-space probes events the process ID and executable name are optional. Any <code class="command">process</code> event in the list below that include process ID or the path to the executable must include those arguments. The process ID and path to the executable are optional for the <code class="command">process</code> events that do not list them:
</div><div class="variablelist"><dl><dt class="varlistentry"><span class="term">process("<em class="replaceable"><code>PATH</code></em>").function("<em class="replaceable"><code>function</code></em>")</span></dt><dd><div class="para">
The entry to the user-space function <em class="replaceable"><code>function</code></em> for the executable <em class="replaceable"><code>PATH</code></em>. This event is the user-space analogue of the <code class="command">kernel.function("<em class="replaceable"><code>function</code></em>")</code> event. It allows wildcards for the function <em class="replaceable"><code>function</code></em> and <code class="command">.return</code> suffix.
</div></dd><dt class="varlistentry"><span class="term">process("<em class="replaceable"><code>PATH</code></em>").statement("<em class="replaceable"><code>statement</code></em>")</span></dt><dd><div class="para">
The earliest instruction in the code for <em class="replaceable"><code>statement</code></em>. This is the user-space analogue of <code class="command">kernel.statement("<em class="replaceable"><code>statement</code></em>")</code>.
</div></dd><dt class="varlistentry"><span class="term">process("<em class="replaceable"><code>PATH</code></em>").mark("<em class="replaceable"><code>marker</code></em>")</span></dt><dd><div class="para">
The static probe point <em class="replaceable"><code>marker</code></em> defined in <em class="replaceable"><code>PATH</code></em>. Wildcards can be used for <em class="replaceable"><code>marker</code></em> to specify mutiple marks with a single probe. The static probe points may also have numbered arguments ($1, $2, etc.) available to the probe. A variety of user-space packages such as Java include these static probe points. Most packages that provide static probe points also provide aliases for the raw user-space mark events. Below is one such alias for the x86_64 Java hotspot JVM:
</div><pre class="screen">probe hotspot.gc_begin =
process("/usr/lib/jvm/java-1.6.0-openjdk-1.6.0.0.x86_64/jre/lib/amd64/server/libjvm.so").mark("gc__begin")</pre></dd><dt class="varlistentry"><span class="term">process.begin</span></dt><dd><div class="para">
User-space process is created. This can be limited to a particular process ID or a full path to the executable.
</div></dd><dt class="varlistentry"><span class="term">process.thread.begin</span></dt><dd><div class="para">
User-space thread is created. This can be limited to a particular process ID or a full path to the executable.
</div></dd><dt class="varlistentry"><span class="term">process.end</span></dt><dd><div class="para">
User-space process died. This can be limited to a particular process ID or a full path to the executable.
</div></dd><dt class="varlistentry"><span class="term">process.thread.end</span></dt><dd><div class="para">
User-space thread is destroyed. This can be limited to a particular process ID or a full path to the executable.
</div></dd><dt class="varlistentry"><span class="term">process.syscall</span></dt><dd><div class="para">
User-space process makes a system call. The system call number is available via $syscall context variable, and the fist six arguments are available via $arg1 through $arg6. The ".return" suffix will place the probe at the return from the system call. For the "syscall.return" the return value is available through the $return context variable. This can be limited to a particular process ID or a full path to the executable.
</div></dd></dl></div></div></div><ul class="docnav"><li class="previous"><a accesskey="p" href="understanding-tapsets.html"><strong>Prev</strong>3.6. Tapsets</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="utargetvariable.html"><strong>Next</strong>4.2. Accessing User-Space Target Variables</a></li></ul></body></html>
