Debian Codegraph @

doc/SystemTap_Beginners_Guide/en-US/Understanding_How_SystemTap_Works.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 ]>
4
5 <chapter id="understanding-how-systemtap-works">
6 <title>Understanding How SystemTap Works</title>
7 <remark>
8 Short summary; probes, handlers, events
9 </remark>
10 <indexterm>
11 <primary>Understanding How SystemTap Works</primary>
12 </indexterm>
13
14
15 <para>
16 SystemTap allows users to write and reuse simple scripts to deeply
17 examine the activities of a running Linux system. These scripts can be
18 designed to extract data, filter it, and summarize it quickly (and
19 safely), enabling the diagnosis of complex performance (or even
20 functional) problems.
21 </para>
22 <indexterm>
23 <primary>Understanding How SystemTap Works</primary>
24 <secondary>events and handlers</secondary>
25 </indexterm>
26
27 <indexterm>
28 <primary>events and handlers</primary>
29 </indexterm>
30 <indexterm>
31 <primary>handlers and events</primary>
32 </indexterm>
33
34
35 <para>The essential idea behind a SystemTap script is to name
36 <emphasis>events</emphasis>, and to give them
37 <emphasis>handlers</emphasis>. When SystemTap runs the script, SystemTap
38 monitors for the event; once the event occurs, the Linux kernel then runs
39 the handler as a quick sub-routine, then resumes.
40 </para>
41 <indexterm>
42 <primary>Understanding How SystemTap Works</primary>
43 <secondary>event types</secondary>
44 </indexterm>
45
46 <indexterm>
47 <primary>event types</primary>
48 <secondary>Understanding How SystemTap Works</secondary>
49 </indexterm>
50
51 <para>
52 There are several kind of events; entering/exiting a function, timer
53 expiration, session termination, etc. A handler is a series of script
54 language statements that specify the work to be done whenever the event
55 occurs. This work normally includes extracting data from the event context,
56 storing them into internal variables, and printing results.
57 </para>
58
59 <section id="understanding-architecture-tools">
60 <title>Architecture</title>
61 <remark>
62 ** add diagram, describe architecture, enumerate common tools
63 </remark>
64
65 <remark>
66 ** architecture diagram must be simpler, if at all included
67 </remark>
68
69 <remark>
70 ** add design advantages? e.g. "building kmods on-the-fly allows safer
71 execution of script etc etc"
72 </remark>
73 <indexterm>
74 <primary>Understanding How SystemTap Works</primary>
75 <secondary>architecture</secondary>
76 </indexterm>
77
78 <indexterm>
79 <primary>architecture of SystemTap</primary>
80 </indexterm>
81
82 <indexterm>
83 <primary>SystemTap architecture</primary>
84 </indexterm>
85 <para>
86 A SystemTap session begins when you run a SystemTap script. This
87 session occurs in the following fashion:
88 </para>
89
90 <procedure id="systemtapsession">
91 <title>SystemTap Session</title>
92 <indexterm>
93 <primary>Understanding How SystemTap Works</primary>
94 <secondary>SystemTap sessions</secondary>
95 </indexterm>
96
97 <indexterm>
98 <primary>SystemTap sessions</primary>
99 </indexterm>
100 <indexterm>
101 <primary>sessions, SystemTap</primary>
102 </indexterm>
103 <step>
104 <para>
105 First, SystemTap checks the script against the existing tapset library
106 (normally in <filename>/usr/share/systemtap/tapset/</filename> for any
107 tapsets used. SystemTap will then substitute any located tapsets with their
108 corresponding definitions in the tapset library.
109 </para>
110 </step>
111
112 <step>
113 <para>SystemTap then translates the script to C, running the system C
114 compiler to create a kernel module from it. The tools that perform
115 this step are contained in the <filename>systemtap</filename> package
116 (refer to <xref linkend="installproper"/> for more information).
117 </para>
118 </step>
119
120 <step>
121 <para>
122 SystemTap loads the module, then enables all the probes (events and
123 handlers) in the script. The <command>staprun</command> in the
124 <filename>systemtap-runtime</filename> package (refer to <xref
125 linkend="installproper"/> for more information) provides this
126 functionality.
127 </para>
128 </step>
129
130 <!-- <step><para>SystemTap loads the module, then enables all the probed events by "hooking" those events into the kernel.</para></step>
131 -->
132 <step>
133 <para>
134 As the events occur, their corresponding handlers are executed.
135 </para>
136 </step>
137
138 <step>
139 <para>
140 Once the SystemTap session is terminated, the probes are disabled, and
141 the kernel module is unloaded.
142 </para>
143 </step>
144 <!--
145 <step><para>Once the SystemTap session is terminated, the hooked events are disconnected from the kernel; afterwards, the kernel module is unloaded.</para></step>-->
146 </procedure>
147
148 <para>This sequence is driven from a single command-line program:
149 <command>stap</command>. This program is SystemTap's main front-end
150 tool. For more information about <command>stap</command>, refer to
151 <command>man stap</command> (once SystemTap is properly installed on your
152 machine).
153 </para>
154
155 </section>
156 <xi:include href="Scripts.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
157 <xi:include href="ScriptConstructs.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
158 <xi:include href="Arrays.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
159 <xi:include href="Array-Operations.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
160
161 <!--
162 <section id="understanding-scripts">
163 <title>SystemTap Scripts</title>
164
165 <remark>
166 ** definition, significance, structure, very basic examples, reference to later chapter (how to read library of preset SystemTap scripts in this book, using them)
167 </remark>
168 </section>
169 -->
170 <section id="understanding-tapsets">
171 <title>Tapsets</title>
172 <indexterm>
173 <primary>Tapsets</primary>
174 <secondary>definition of</secondary>
175 </indexterm>
176 <remark>
177 definition, significance, difference with stap scripts (previous section),
178 library of tapsets in system: location
179 </remark>
180
181 <para>
182 <firstterm>Tapsets</firstterm> are scripts that form a library of
183 pre-written probes and functions to be used in SystemTap scripts. When a
184 user runs a SystemTap script, SystemTap checks the script's probe events
185 and handlers against the tapset library; SystemTap then loads the
186 corresponding probes and functions before translating the script to C
187 (refer to <xref linkend="understanding-architecture-tools"/> for
188 information on what transpires in a SystemTap session).
189 </para>
190 <!--
191 <para>
192 Simply put, the tapset library is an abstraction layer designed to make it easier for users to define events and functions. In a way, tapsets provide useful "aliases" for functions that users may want to specify as an event; knowing the proper alias to use is, for the most part, easier than understanding how to specify a specific kernel function.
193 </para>
194 -->
195 <para>
196 Like SystemTap scripts, tapsets use the file name extension
197 <filename>.stp</filename>. The standard library of tapsets is located in
198 <filename>/usr/share/systemtap/tapset/</filename> by default. However,
199 unlike SystemTap scripts, tapsets are not meant for direct execution;
200 rather, they constitute the library from which other scripts can pull
201 definitions.
202 </para>
203
204 <para>
205 The tapset library is an abstraction layer designed to make it
206 easier for users to define events and functions.
207 Tapsets provide useful aliases for functions that users may want to
208 specify as an event; knowing the proper alias to use is, for the most
209 part, easier than remembering specific kernel functions that might vary
210 between kernel versions.
211 </para>
212
213 <!-- understanding how to specify a specific kernel function. -->
214
215 <para>
216 Several handlers and functions in <xref linkend="systemtapscript-events"/>
217 and <xref linkend="systemtapscript-functions"/> are defined in tapsets.
218 For example, <command>thread_indent()</command> is defined in
219 <filename>indent.stp</filename>.
220 </para>
221
222 <remark>
223 any other details to be included? i dont want to dwell too long here,
224 though, since IMHO tapset development is beyond the scope of this
225 "beginner's guide"
226 </remark>
227
228 </section>
229
230 </chapter>