summaryrefslogtreecommitdiffstats
path: root/SystemTap_Beginners_Guide/userspace-probing.html
diff options
authorjistone <jistone>2014-08-08 23:22:55 +0000
committerjistone <jistone>2014-08-08 23:22:55 +0000
commitee0f63498a58a80413f9edf3dab13ba7049ee37e (patch)
treef63e372afe75a6718c077be48afbcf8899492b5f /SystemTap_Beginners_Guide/userspace-probing.html
parentadded new man pages (diff)
update SystemTap_Beginners_Guide
Diffstat (limited to 'SystemTap_Beginners_Guide/userspace-probing.html')
-rw-r--r--SystemTap_Beginners_Guide/userspace-probing.html18
1 files changed, 10 insertions, 8 deletions
diff --git a/SystemTap_Beginners_Guide/userspace-probing.html b/SystemTap_Beginners_Guide/userspace-probing.html
index 3c1362fb..7d12ca59 100644
--- a/SystemTap_Beginners_Guide/userspace-probing.html
+++ b/SystemTap_Beginners_Guide/userspace-probing.html
@@ -1,5 +1,6 @@
1<?xml version="1.0" encoding="UTF-8" standalone="no"?> 1<?xml version="1.0" encoding="UTF-8" standalone="no"?>
2<!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 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 xmlns:d="http://docbook.org/ns/docbook" name="generator" content="publican v4.0.0" /><meta xmlns:d="http://docbook.org/ns/docbook" name="package" content="SystemTap-SystemTap_Beginners_Guide-2.6-en-US-2.0-1" /><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="https://fedorahosted.org/publican"><img alt="Product Site" src="Common_Content/images//image_left.png" /></a><a class="right" href="https://fedorahosted.org/publican"><img alt="Documentation Site" src="Common_Content/images//image_right.png" /></a></p><ul class="docnav top"><li class="previous"><a accesskey="p" href="understanding-tapsets.html"><strong>Prev</strong></a></li><li class="home">SystemTap Beginners Guide</li><li class="next"><a accesskey="n" href="utargetvariable.html"><strong>Next</strong></a></li></ul><div xml:lang="en-US" class="chapter" lang="en-US"><div class="titlepage"><div><div><h1 class="title"><a id="userspace-probing"></a>Chapter 4. User-space Probing</h1></div></div></div><div class="toc"><dl class="toc"><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"> 2<!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 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 xmlns:d="http://docbook.org/ns/docbook" name="generator" content="publican v4.1.3" /><meta xmlns:d="http://docbook.org/ns/docbook" name="package" content="SystemTap-SystemTap_Beginners_Guide-2.6-en-US-2.0-1" /><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="https://fedorahosted.org/publican"><img alt="Product Site" src="Common_Content/images//image_left.png" /></a><a class="right" href="https://fedorahosted.org/publican"><img alt="Documentation Site" src="Common_Content/images//image_right.png" /></a></p><ul class="docnav top"><li class="previous"><a accesskey="p" href="understanding-tapsets.html"><strong>Prev</strong></a></li><li class="home">SystemTap Beginners Guide</li><li class="next"><a accesskey="n" href="utargetvariable.html"><strong>Next</strong></a></li></ul><div xml:lang="en-US" class="chapter" lang="en-US"><div class="titlepage"><div><div><h1 class="title"><a id="userspace-probing">
3 ⁠</a>Chapter 4. User-space Probing</h1></div></div></div><div class="toc"><dl class="toc"><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">
3 SystemTap initially focused on kernel-space probing. Because 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 can probe the entry into and return from a function in user-space processes, probe predefined markers in user-space code, and monitor user-process events. 4 SystemTap initially focused on kernel-space probing. Because 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 can probe the entry into and return from a function in user-space processes, probe predefined markers in user-space code, and monitor user-process events.
4 </div><div class="para"> 5 </div><div class="para">
5 SystemTap requires the uprobes module to perform user-space probing. If your Linux kernel is version 3.5 or higher, it already includes uprobes. To verify that the current kernel supports uprobes natively, run the following command: 6 SystemTap requires the uprobes module to perform user-space probing. If your Linux kernel is version 3.5 or higher, it already includes uprobes. To verify that the current kernel supports uprobes natively, run the following command:
@@ -9,16 +10,17 @@
9 If you are running a kernel prior to version 3.5, SystemTap automatically builds the uprobes module. However, you also need the utrace kernel extensions required by the SystemTap user-space probing to track 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>. To determine whether the currently running Linux kernel provides the needed utrace support, type the following at a shell prompt: 10 If you are running a kernel prior to version 3.5, SystemTap automatically builds the uprobes module. However, you also need the utrace kernel extensions required by the SystemTap user-space probing to track 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>. To determine whether the currently running Linux kernel provides the needed utrace support, type the following at a shell prompt:
10 </div><pre class="screen"><code class="command">grep CONFIG_UTRACE /boot/config-`uname -r`</code></pre><div class="para"> 11 </div><pre class="screen"><code class="command">grep CONFIG_UTRACE /boot/config-`uname -r`</code></pre><div class="para">
11 If the Linux kernel supports user-space probing, the command produces the following output: 12 If the Linux kernel supports user-space probing, the command produces the following output:
12 </div><pre class="screen">CONFIG_UTRACE=y</pre><div class="section"><div class="titlepage"><div><div><h2 class="title"><a id="uevents"></a>4.1. User-Space Events</h2></div></div></div><a id="idm47951420330640" class="indexterm"></a><div class="para"> 13 </div><pre class="screen">CONFIG_UTRACE=y</pre><div class="section"><div class="titlepage"><div><div><h2 class="title"><a id="uevents">
14 ⁠</a>4.1. User-Space Events</h2></div></div></div><a id="idm213974235040" class="indexterm"></a><div class="para">
13 All user-space event probes begin with <span class="emphasis"><em>process</em></span>. You can limit the process events to a specific running process by specifying the process ID. You can also limit the process events to monitor a particular executable by specifying the path to the executable (PATH). SystemTap makes use of the <code class="envar">PATH</code> environment variable, which allows you to use both the name used on the command-line to start the executable and the absolute path to the executable. 15 All user-space event probes begin with <span class="emphasis"><em>process</em></span>. You can limit the process events to a specific running process by specifying the process ID. You can also limit the process events to monitor a particular executable by specifying the path to the executable (PATH). SystemTap makes use of the <code class="envar">PATH</code> environment variable, which allows you to use both the name used on the command-line to start the executable and the absolute path to the executable.
14 </div><div class="para"> 16 </div><div class="para">
15 Several of the user-space probe events limit their scope to a particular executable name (PATH), because SystemTap must use debug information to statically analyze where to place the probes. But for many user-space probe 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: 17 Several of the user-space probe events limit their scope to a particular executable name (PATH), because SystemTap must use debug information to statically analyze where to place the probes. But for many user-space probe 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:
16 </div><div class="variablelist"><dl class="variablelist"><dt><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"> 18 </div><div class="variablelist"><dl class="variablelist"><dt><span class="term">process("<em class="replaceable">PATH</em>").function("<em class="replaceable">function</em>")</span></dt><dd><div class="para">
17 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="literal">.return</code> suffix. 19 The entry to the user-space function <em class="replaceable">function</em> for the executable <em class="replaceable">PATH</em>. This event is the user-space analogue of the <code class="command">kernel.function("<em class="replaceable">function</em>")</code> event. It allows wildcards for the function <em class="replaceable">function</em> and <code class="literal">.return</code> suffix.
18 </div></dd><dt><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"> 20 </div></dd><dt><span class="term">process("<em class="replaceable">PATH</em>").statement("<em class="replaceable">statement</em>")</span></dt><dd><div class="para">
19 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>. 21 The earliest instruction in the code for <em class="replaceable">statement</em>. This is the user-space analogue of <code class="command">kernel.statement("<em class="replaceable">statement</em>")</code>.
20 </div></dd><dt><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"> 22 </div></dd><dt><span class="term">process("<em class="replaceable">PATH</em>").mark("<em class="replaceable">marker</em>")</span></dt><dd><div class="para">
21 The static probe point <em class="replaceable"><code>marker</code></em> defined in <em class="replaceable"><code>PATH</code></em>. You can use wildcards for <em class="replaceable"><code>marker</code></em> to specify multiple marks with a single probe. The static probe points may also have numbered arguments ($1, $2, and so on) available to the probe. 23 The static probe point <em class="replaceable">marker</em> defined in <em class="replaceable">PATH</em>. You can use wildcards for <em class="replaceable">marker</em> to specify multiple marks with a single probe. The static probe points may also have numbered arguments ($1, $2, and so on) available to the probe.
22 </div><div class="para"> 24 </div><div class="para">
23 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: 25 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:
24 </div><pre class="programlisting">probe hotspot.gc_begin = 26 </div><pre class="programlisting">probe hotspot.gc_begin =
generated by cgit (git 2.34.1) at 2025-11-01 09:07:31 +0000