summaryrefslogtreecommitdiffstats
path: root/SystemTap_Beginners_Guide/using-usage.html
diff options
authorfche <fche>2014-12-22 17:41:44 +0000
committerfche <fche>2014-12-22 17:41:44 +0000
commitfa0b125acdd92ee719deebaa374015f10e42d284 (patch)
tree5194dea5881e7c30a1e69cbd28e77e1740afbebb /SystemTap_Beginners_Guide/using-usage.html
parentadd new langref/*.html (diff)
removed man pages
Diffstat (limited to 'SystemTap_Beginners_Guide/using-usage.html')
-rw-r--r--SystemTap_Beginners_Guide/using-usage.html18
1 files changed, 9 insertions, 9 deletions
diff --git a/SystemTap_Beginners_Guide/using-usage.html b/SystemTap_Beginners_Guide/using-usage.html
index f86cd020..25de7b1b 100644
--- a/SystemTap_Beginners_Guide/using-usage.html
+++ b/SystemTap_Beginners_Guide/using-usage.html
@@ -1,22 +1,22 @@
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">2.3. Running SystemTap Scripts</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.7-en-US-2.0-1" /><link rel="home" href="index.html" title="SystemTap Beginners Guide" /><link rel="up" href="using-systemtap.html" title="Chapter 2. Using SystemTap" /><link rel="prev" href="cross-compiling.html" title="2.2. Generating Instrumentation for Other Computers" /><link rel="next" href="understanding-how-systemtap-works.html" title="Chapter 3. Understanding How SystemTap Works" /></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="cross-compiling.html"><strong>Prev</strong></a></li><li class="home">SystemTap Beginners Guide</li><li class="next"><a accesskey="n" href="understanding-how-systemtap-works.html"><strong>Next</strong></a></li></ul><div class="section"><div class="titlepage"><div><div><h2 class="title"><a id="using-usage"> 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">2.3. Running SystemTap Scripts</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.7-en-US-2.0-1" /><link rel="home" href="index.html" title="SystemTap Beginners Guide" /><link rel="up" href="using-systemtap.html" title="Chapter 2. Using SystemTap" /><link rel="prev" href="cross-compiling.html" title="2.2. Generating Instrumentation for Other Computers" /><link rel="next" href="understanding-how-systemtap-works.html" title="Chapter 3. Understanding How SystemTap Works" /></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="cross-compiling.html"><strong>Prev</strong></a></li><li class="home">SystemTap Beginners Guide</li><li class="next"><a accesskey="n" href="understanding-how-systemtap-works.html"><strong>Next</strong></a></li></ul><div class="section"><div class="titlepage"><div><div><h2 class="title"><a id="using-usage">
3 ⁠</a>2.3. Running SystemTap Scripts</h2></div></div></div><a id="idm47650183681376" class="indexterm"></a><a id="idm47650199427408" class="indexterm"></a><a id="idm47650199426000" class="indexterm"></a><a id="idm47650154346512" class="indexterm"></a><a id="idm47650151205968" class="indexterm"></a><a id="idm47650151204528" class="indexterm"></a><div class="para"> 3 ⁠</a>2.3. Running SystemTap Scripts</h2></div></div></div><a id="idm47748224207312" class="indexterm"></a><a id="idm47748176153536" class="indexterm"></a><a id="idm47748176152128" class="indexterm"></a><a id="idm47748188355600" class="indexterm"></a><a id="idm47748181146624" class="indexterm"></a><a id="idm47748181145184" class="indexterm"></a><div class="para">
4 SystemTap is distributed with a number of command line tools that allow you to monitor the activities of the system. The <code class="command">stap</code> command reads probing instructions from a SystemTap script, translates these instructions into C code, builds a kernel module, and loads it into the running Linux kernel. The <code class="command">staprun</code> command runs SystemTap instrumentation, that is, a kernel module built from SystemTap scripts during a cross-instrumentation. 4 SystemTap is distributed with a number of command line tools that allow you to monitor the activities of the system. The <code class="command">stap</code> command reads probing instructions from a SystemTap script, translates these instructions into C code, builds a kernel module, and loads it into the running Linux kernel. The <code class="command">staprun</code> command runs SystemTap instrumentation, that is, a kernel module built from SystemTap scripts during a cross-instrumentation.
5 </div><a id="idm47650151217280" class="indexterm"></a><div class="para"> 5 </div><a id="idm47748181116864" class="indexterm"></a><div class="para">
6 Running <code class="command">stap</code> and <code class="command">staprun</code> requires elevated privileges to the system. Because not all users can be granted root access just to run SystemTap, you can allow a non-privileged user to run SystemTap instrumentation on their machine by adding them to one of the following user groups: 6 Running <code class="command">stap</code> and <code class="command">staprun</code> requires elevated privileges to the system. Because not all users can be granted root access just to run SystemTap, you can allow a non-privileged user to run SystemTap instrumentation on their machine by adding them to one of the following user groups:
7 </div><div class="variablelist"><dl class="variablelist"><dt><span class="term">stapdev</span></dt><dd><a id="idm47650191474048" class="indexterm"></a><a id="idm47650197246528" class="indexterm"></a><div class="para"> 7 </div><div class="variablelist"><dl class="variablelist"><dt><span class="term">stapdev</span></dt><dd><a id="idm47748234386864" class="indexterm"></a><a id="idm47748234385904" class="indexterm"></a><div class="para">
8 Members of this group can use the <code class="command">stap</code> command to run SystemTap scripts, or <code class="command">staprun</code> to run SystemTap instrumentation modules. 8 Members of this group can use the <code class="command">stap</code> command to run SystemTap scripts, or <code class="command">staprun</code> to run SystemTap instrumentation modules.
9 </div><div class="para"> 9 </div><div class="para">
10 Running the <code class="command">stap</code> command involves compiling SystemTap scripts into kernel modules and loading them into the kernel. This operation requires elevated privileges to the system, which are granted to <code class="systemitem">stapdev</code> members. Unfortunately, such privileges also grant effective root access to <code class="systemitem">stapdev</code> members. As a consequence, only grant <code class="systemitem">stapdev</code> group membership to users whom you can trust with root access. 10 Running the <code class="command">stap</code> command involves compiling SystemTap scripts into kernel modules and loading them into the kernel. This operation requires elevated privileges to the system, which are granted to <code class="systemitem">stapdev</code> members. Unfortunately, such privileges also grant effective root access to <code class="systemitem">stapdev</code> members. As a consequence, only grant <code class="systemitem">stapdev</code> group membership to users whom you can trust with root access.
11 </div></dd><dt><span class="term">stapusr</span></dt><dd><a id="idm47650191423376" class="indexterm"></a><a id="idm47650191422416" class="indexterm"></a><div class="para"> 11 </div></dd><dt><span class="term">stapusr</span></dt><dd><a id="idm47748219971440" class="indexterm"></a><a id="idm47748175252592" class="indexterm"></a><div class="para">
12 Members of this group can only use the <code class="command">staprun</code> command to run SystemTap instrumentation modules. In addition, they can only run modules from the <code class="filename">/lib/modules/<em class="replaceable">kernel_version</em>/systemtap/</code> directory. Note that this directory must be owned only by the root user, and must only be writable by the root user. 12 Members of this group can only use the <code class="command">staprun</code> command to run SystemTap instrumentation modules. In addition, they can only run modules from the <code class="filename">/lib/modules/<em class="replaceable">kernel_version</em>/systemtap/</code> directory. Note that this directory must be owned only by the root user, and must only be writable by the root user.
13 </div></dd></dl></div><div class="para"> 13 </div></dd></dl></div><div class="para">
14 The <code class="command">stap</code> command reads a SystemTap script either from a file, or from standard input. To tell <code class="command">stap</code> to read a SystemTap script from a file, specify the file name on the command line: 14 The <code class="command">stap</code> command reads a SystemTap script either from a file, or from standard input. To tell <code class="command">stap</code> to read a SystemTap script from a file, specify the file name on the command line:
15 </div><pre class="screen"><code class="command">stap <em class="replaceable">file_name</em></code></pre><a id="idm47650150699952" class="indexterm"></a><a id="idm47650150698544" class="indexterm"></a><a id="idm47650187363424" class="indexterm"></a><div class="para"> 15 </div><pre class="screen"><code class="command">stap <em class="replaceable">file_name</em></code></pre><a id="idm47748228620736" class="indexterm"></a><a id="idm47748215175952" class="indexterm"></a><a id="idm47748215174544" class="indexterm"></a><div class="para">
16 To instruct <code class="command">stap</code> to read a SystemTap script from standard input, use the <code class="option">-</code> switch instead of the file name. Note that any command-line options you wish to use must be inserted before the <code class="option">-</code> switch. For example, to make the output of the <code class="command">stap</code> command more verbose, type: 16 To instruct <code class="command">stap</code> to read a SystemTap script from standard input, use the <code class="option">-</code> switch instead of the file name. Note that any command-line options you wish to use must be inserted before the <code class="option">-</code> switch. For example, to make the output of the <code class="command">stap</code> command more verbose, type:
17 </div><pre class="screen"><code class="command">echo "probe timer.s(1) {exit()}" | stap -v -</code></pre><div class="para"> 17 </div><pre class="screen"><code class="command">echo "probe timer.s(1) {exit()}" | stap -v -</code></pre><div class="para">
18 Below is a list of commonly used <code class="command">stap</code> options: 18 Below is a list of commonly used <code class="command">stap</code> options:
19 </div><a id="idm47650193599296" class="indexterm"></a><a id="idm47650190268320" class="indexterm"></a><div class="variablelist"><a id="idm47650190266560" class="indexterm"></a><dl class="variablelist"><dt><span class="term">-v</span></dt><dd><div class="para"> 19 </div><a id="idm47748220329952" class="indexterm"></a><a id="idm47748220328512" class="indexterm"></a><div class="variablelist"><a id="idm47748176235872" class="indexterm"></a><dl class="variablelist"><dt><span class="term">-v</span></dt><dd><div class="para">
20 Makes the output of the SystemTap session more verbose. You can repeat this option multiple times to provide more details on the script's execution, for example: 20 Makes the output of the SystemTap session more verbose. You can repeat this option multiple times to provide more details on the script's execution, for example:
21 </div><pre class="screen"><code class="command">stap -vvv script.stp</code></pre><div class="para"> 21 </div><pre class="screen"><code class="command">stap -vvv script.stp</code></pre><div class="para">
22 This option is particularly useful if you encounter any errors in running the script. For more information about common SystemTap script errors, refer to <a class="xref" href="errors.html">Chapter 6, <em>Understanding SystemTap Errors</em></a>. 22 This option is particularly useful if you encounter any errors in running the script. For more information about common SystemTap script errors, refer to <a class="xref" href="errors.html">Chapter 6, <em>Understanding SystemTap Errors</em></a>.
@@ -35,12 +35,12 @@
35 </div></dd></dl></div><div class="para"> 35 </div></dd></dl></div><div class="para">
36 For more information about the <code class="command">stap</code> command, refer to the <span class="citerefentry"><span class="refentrytitle">stap</span>(1)</span> man page. For more information about the <code class="command">staprun</code> command and cross-instrumentation, refer to <a class="xref" href="cross-compiling.html">Section 2.2, “Generating Instrumentation for Other Computers”</a> or the <span class="citerefentry"><span class="refentrytitle">staprun</span>(8)</span> man page. 36 For more information about the <code class="command">stap</code> command, refer to the <span class="citerefentry"><span class="refentrytitle">stap</span>(1)</span> man page. For more information about the <code class="command">staprun</code> command and cross-instrumentation, refer to <a class="xref" href="cross-compiling.html">Section 2.2, “Generating Instrumentation for Other Computers”</a> or the <span class="citerefentry"><span class="refentrytitle">staprun</span>(8)</span> man page.
37 </div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="flight-recorder"> 37 </div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="flight-recorder">
38 ⁠</a>2.3.1. SystemTap Flight Recorder Mode</h3></div></div></div><a id="idm47650196017024" class="indexterm"></a><div class="para"> 38 ⁠</a>2.3.1. SystemTap Flight Recorder Mode</h3></div></div></div><a id="idm47748224790032" class="indexterm"></a><div class="para">
39 SystemTap's flight recorder mode allows you to run a SystemTap script for long periods of time and just focus on recent output. The flight recorder mode limits the amount of output generated. 39 SystemTap's flight recorder mode allows you to run a SystemTap script for long periods of time and just focus on recent output. The flight recorder mode limits the amount of output generated.
40 </div><div class="para"> 40 </div><div class="para">
41 There are two variations of the flight recorder mode: <em class="firstterm">in-memory</em> and <em class="firstterm">file</em> mode. In both cases, the SystemTap script runs as a background process. 41 There are two variations of the flight recorder mode: <em class="firstterm">in-memory</em> and <em class="firstterm">file</em> mode. In both cases, the SystemTap script runs as a background process.
42 </div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="memory-flight-recorder"> 42 </div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="memory-flight-recorder">
43 ⁠</a>2.3.1.1. In-memory Flight Recorder</h4></div></div></div><a id="idm47650197177456" class="indexterm"></a><div class="para"> 43 ⁠</a>2.3.1.1. In-memory Flight Recorder</h4></div></div></div><a id="idm47748224178320" class="indexterm"></a><div class="para">
44 When flight recorder mode is used without a file name, SystemTap uses a buffer in kernel memory to store the output of the script. Once the SystemTap instrumentation module is loaded and the probes start running, the instrumentation detaches and is put in the background. When the interesting event occurs, you can reattach to the instrumentation to see the recent output in the memory buffer and any continuing output. 44 When flight recorder mode is used without a file name, SystemTap uses a buffer in kernel memory to store the output of the script. Once the SystemTap instrumentation module is loaded and the probes start running, the instrumentation detaches and is put in the background. When the interesting event occurs, you can reattach to the instrumentation to see the recent output in the memory buffer and any continuing output.
45 </div><div class="para"> 45 </div><div class="para">
46 To run a SystemTap script by using the flight recorder in-memory mode, run the <code class="command">stap</code> command with the <code class="option">-F</code> command line option: 46 To run a SystemTap script by using the flight recorder in-memory mode, run the <code class="command">stap</code> command with the <code class="option">-F</code> command line option:
@@ -52,7 +52,7 @@ To reconnect, type "staprun -A stap_5dd0073edcb1f13f7565d8c343063e68_19556"</pre
52 </div><pre class="screen"><code class="command">staprun -A stap_5dd0073edcb1f13f7565d8c343063e68_19556</code></pre><div class="para"> 52 </div><pre class="screen"><code class="command">staprun -A stap_5dd0073edcb1f13f7565d8c343063e68_19556</code></pre><div class="para">
53 By default, the kernel buffer is 1MB in size. You can increase this value by using the <code class="option">-s</code> option with the size in megabytes (rounded up to the next power over 2) for the buffer. For example, <code class="option">-s2</code> on the SystemTap command line would specify 2MB for the buffer. 53 By default, the kernel buffer is 1MB in size. You can increase this value by using the <code class="option">-s</code> option with the size in megabytes (rounded up to the next power over 2) for the buffer. For example, <code class="option">-s2</code> on the SystemTap command line would specify 2MB for the buffer.
54 </div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="file-flight-recorder"> 54 </div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="file-flight-recorder">
55 ⁠</a>2.3.1.2. File Flight Recorder</h4></div></div></div><a id="idm47650183027184" class="indexterm"></a><div class="para"> 55 ⁠</a>2.3.1.2. File Flight Recorder</h4></div></div></div><a id="idm47748180568960" class="indexterm"></a><div class="para">
56 The flight recorder mode can also store data to files. You can control the number and size of the files kept by using the <code class="option">-S</code> option followed by two numerical arguments separated by a comma: the first argument is the maximum size in megabytes for the each output file, the second argument is the number of recent files to keep. To specify the file name, use the <code class="option">-o</code> option followed by the name. SystemTap automatically adds a number suffix to the file name to indicate the order of the files. 56 The flight recorder mode can also store data to files. You can control the number and size of the files kept by using the <code class="option">-S</code> option followed by two numerical arguments separated by a comma: the first argument is the maximum size in megabytes for the each output file, the second argument is the number of recent files to keep. To specify the file name, use the <code class="option">-o</code> option followed by the name. SystemTap automatically adds a number suffix to the file name to indicate the order of the files.
57 </div><div class="para"> 57 </div><div class="para">
58 The following command starts SystemTap in file flight recorder mode with the output going to files named <code class="filename">/tmp/iotime.log.<em class="replaceable">[0-9]+</em></code>, each file 1MB or smaller, and keeping latest two files: 58 The following command starts SystemTap in file flight recorder mode with the output going to files named <code class="filename">/tmp/iotime.log.<em class="replaceable">[0-9]+</em></code>, each file 1MB or smaller, and keeping latest two files:
generated by cgit (git 2.34.1) at 2025-11-03 14:47:52 +0000