Debian Codegraph @

doc/SystemTap_Beginners_Guide/en-US/Introduction.xml

raw
1 <?xml version='1.0'?>
2 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
3 <!ENTITY % BOOK_ENTITIES SYSTEM "SystemTap_Beginners_Guide.ent"> %BOOK_ENTITIES;
4 ]>
5
6 <chapter id="introduction">
7 <title>Introduction</title>
8 <indexterm>
9 <primary>Introduction</primary>
10 <secondary>performance monitoring</secondary>
11 </indexterm>
12
13 <indexterm>
14 <primary>performance monitoring</primary>
15 <secondary>Introduction</secondary>
16 </indexterm>
17 <!-- next 2 indexterms for documentation goals -->
18
19 <para>
20 SystemTap is a tracing and probing tool that allows
21 users to study and monitor the activities of the
22 computer system (particularly, the kernel) in fine
23 detail. It provides information similar to the output
24 of tools like <command>netstat</command>,
25 <command>ps</command>, <command>top</command>, and
26 <command>iostat</command>, but is
27 designed to provide more filtering and analysis
28 options for collected information.
29 </para>
30
31
32
33 <!--
34 <para>
35 SystemTap was developed as a Linux version of the DTrace tool (for <trademark>Sun Solaris</trademark>).
36 </para>
37 -->
38 <section id="goals">
39 <title>Documentation Goals</title>
40
41 <indexterm>
42 <primary>Introduction</primary>
43 <secondary>documentation goals</secondary>
44 </indexterm>
45
46 <indexterm>
47 <primary>documentation goals</primary>
48 <secondary>Introduction</secondary>
49 </indexterm>
50 <indexterm>
51 <primary>Introduction</primary>
52 <secondary>goals, documentation</secondary>
53 </indexterm>
54
55 <indexterm>
56 <primary>goals, documentation</primary>
57 <secondary>Introduction</secondary>
58 </indexterm>
59
60
61 <para>SystemTap provides the infrastructure to monitor the running Linux kernel for detailed analysis. This can assist administrators and developers in identifying the underlying cause of a bug or performance problem.</para>
62
63 <para>Without SystemTap, monitoring the activity of a running kernel would require a tedious instrument, recompile, install, and reboot sequence. SystemTap is designed to eliminate this and allows users to gather the same information by running user-written SystemTap scripts.</para>
64
65 <para>SystemTap was initially designed for users with intermediate to advanced knowledge of the kernel. As a consequence, it is less useful to administrators or developers with limited knowledge of and experience with the Linux kernel. Moreover, much of the existing SystemTap documentation is aimed at knowledgeable and experienced users, which makes learning the tool similarly difficult.</para>
66
67 <para>To lower these barriers, the SystemTap Beginners Guide was written with the following goals:</para>
68 <!--
69 <para>However, SystemTap was initially designed for users with intermediate to advanced knowledge of the kernel. As such, much of the existing documentation for SystemTap is primarily for advanced users. This could present a steep learning curve for administrators or developers with limited knowledge of and experience with the Linux kernel.</para>
70
71 <para>In line with that, the main goals of the <citetitle>SystemTap Beginner's Guide</citetitle> are as follows:</para>
72 -->
73 <itemizedlist>
74 <listitem><para>to introduce users to SystemTap, familiarize
75 them with its architecture, and provide setup
76 instructions;</para></listitem>
77
78 <listitem><para>to provide pre-written SystemTap scripts for monitoring detailed activity in different components of the system, along with instructions on how to run them and analyze their output.</para></listitem>
79 </itemizedlist>
80 <!-- </formalpara> -->
81 <remark>above, Short description on the underlying goals of SystemTap_Beginners_Guide, what we want to teach users.</remark>
82
83 </section>
84 <!--
85 <section id="intro-usage">
86 <title>Usage</title>
87 <remark>
88 This section describes the practical uses of SystemTap, at a conceptual level. What a beginner can use SystemTap for, and what an advanced user can use SystemTap for.
89 </remark>
90 </section>
91 -->
92 <section id="intro-systemtap-vs-others">
93 <!-- <title>SystemTap Versus Other Monitoring Tools</title> -->
94 <title>SystemTap Capabilities</title>
95 <remark>
96 ** Short summary; when is SystemTap suitable vs other popular monitoring tools such as top, Oprofile or /proc
97 </remark>
98 <indexterm>
99 <primary>Introduction</primary>
100 <secondary>capabilities of SystemTap</secondary>
101 </indexterm>
102
103 <indexterm>
104 <primary>capabilities of SystemTap</primary>
105 <secondary>Introduction</secondary>
106 </indexterm>
107
108 <!--
109 <para>SystemTap was originally developed as a working &PROD; version of old Linux probing tools such as <application>dprobes</application> and the Linux Trace Toolkit. Further, SystemTap can also be considered the Linux answer to <firstterm>Dtrace</firstterm>. Dtrace is a Sun Microsystems "dynamic tracing" framework that assists administrators in monitoring and troubleshooting kernel and user-space applications in real time.</para>
110
111 <para>SystemTap aims to supplement the existing suite of Linux monitoring tools by providing users with the infrastructure to track kernel activity. In addition, SystemTap combines this capability with two things:</para>-->
112
113 <itemizedlist>
114 <listitem><para><emphasis role="strong">Flexibility:</emphasis> SystemTap's framework allows users to develop simple scripts for investigating and monitoring a wide variety of kernel functions, system calls, and other events that occur in kernel space. As a result, SystemTap is not so much a <emphasis>tool</emphasis> as it is a system that allows you to develop your own kernel-specific forensic and monitoring tools.</para></listitem>
115
116 <listitem><para><emphasis role="strong">Ease of use</emphasis>: as mentioned earlier, SystemTap allows users to probe kernel-space events without having to resort to instrument, recompile, install, and reboot the kernel.</para></listitem>
117 </itemizedlist>
118
119 <para>Most of the SystemTap scripts enumerated in <xref linkend="useful-systemtap-scripts"/> demonstrate system forensics and monitoring capabilities not natively available with other similar tools (such as <command>top</command>, <command>oprofile</command>, or <command>ps</command>). These scripts are provided to give readers extensive examples of the application of SystemTap and to educate them further on the capabilities they can employ when writing their own SystemTap scripts.</para>
120 <!--
121 <example id="introstory">
122 <title>A Simple SystemTap Case Study</title>
123 <para>The entire system is running slow. You suspect that this could be caused by a process (or multiple processes) performing an excessive amount of reads or writes to disk.</para>
124
125 <para>To test your theory, you write a simple SystemTap script that tracks how many reads and writes the system did in a 5-second time period. Once you prove your theory right, you then write another SystemTap script that tracks which processes are performing excessive reads/writes.</para>
126
127 <para>With a list of processes performing excessive reads/writes, you can then examine which ones are generating more I/O activity than expected.</para>
128
129 -->
130
131
132 <!--
133 <formalpara>
134 <title>Advantages</title>
135 <para>TBD</para>
136 </formalpara>
137 -->
138 </section>
139 <section id="intro-systemtap-limitations">
140 <title>Limitations of SystemTap</title>
141 <indexterm>
142 <primary>Introduction</primary>
143 <secondary>limitations of SystemTap</secondary>
144 </indexterm>
145
146 <indexterm>
147 <primary>limitations of SystemTap</primary>
148 <secondary>Introduction</secondary>
149 </indexterm>
150
151
152 <para>The current iteration of SystemTap allows for a multitude of
153 options when probing kernel-space events for a wide range of kernels.
154 However, SystemTap's ability to probe user-space events depends
155 on kernel support (the Utrace mechanism) that is not available in many kernels.
156 As a consequence, only some kernel versions support user-space probing.</para>
157
158 <para>At present, the developmental efforts of the SystemTap community
159 are geared towards improving SystemTap's user-space probing
160 capabilities.</para>
161
162
163 </section>
164
165 </chapter>
166