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