Debian Codegraph @

doc/SystemTap_Beginners_Guide/en-US/CrossInstrumenting.xml

raw
1 <?xml version='1.0'?>
2 <!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
3 ]>
4
5 <section id="cross-compiling">
6 <title>Generating Instrumentation for Other Computers</title>
7 <indexterm>
8 <primary>cross-instrumentation</primary>
9 <secondary>building kernel modules from SystemTap scripts</secondary>
10 </indexterm>
11 <indexterm>
12 <primary>cross-instrumentation</primary>
13 <secondary>generating instrumentation from SystemTap scripts</secondary>
14 </indexterm>
15 <remark>
16 cross-compiling script from here:
17 http://sourceware.org/ml/systemtap/2008-q3/msg00310.html
18 </remark>
19
20 <indexterm>
21 <primary>kernel modules from SystemTap scripts, building</primary>
22 </indexterm>
23 <indexterm>
24 <primary>building kernel modules from SystemTap scripts</primary>
25 </indexterm>
26 <indexterm>
27 <primary>instrumentation modules from SystemTap scripts, building</primary>
28 </indexterm>
29 <indexterm>
30 <primary>building instrumentation modules from SystemTap scripts</primary>
31 </indexterm>
32 <indexterm>
33 <primary>compiling instrumentation/kernel modules from SystemTap scripts</primary>
34 </indexterm>
35
36 <indexterm>
37 <primary>cross-compiling</primary>
38 </indexterm>
39 <remark>
40 above; add short description, significance, howto, script (test first)
41 </remark>
42
43 <para>
44 When users run a SystemTap script, SystemTap builds a kernel module out of
45 that script. SystemTap then loads the module into the kernel, allowing it to
46 extract the specified data directly from the kernel (refer to
47 <xref linkend="systemtapsession"/> in
48 <xref linkend="understanding-architecture-tools"/> for more information).
49 </para>
50
51 <para>
52 Normally, however, SystemTap scripts can only be run on systems where SystemTap is deployed (as in <xref linkend="using-setup"/>). This could mean that if you want to run SystemTap on ten systems, you would need to deploy SystemTap on <emphasis>all</emphasis> those systems. In some cases, this may be neither feasible nor desired. For instance, corporate policy may prohibit an administrator from installing RPM packages that provide compilers or debug information on specific machines, and thus prevent the deployment of SystemTap. To work around this problem, SystemTap allows you to use <firstterm>cross-instrumentation</firstterm>.
53 </para>
54
55 <para>
56 Cross-instrumentation is the process of generating SystemTap instrumentation module from a SystemTap script on one computer to be used on another computer. This process offers the following benefits:
57 </para>
58 <indexterm>
59 <primary>cross-instrumentation</primary>
60 <secondary>advantages of</secondary>
61 </indexterm>
62
63 <indexterm>
64 <primary>advantages of cross-instrumentation</primary>
65 </indexterm>
66
67 <itemizedlist>
68 <listitem>
69 <para>
70 The kernel information packages for various machines can be installed on a single <emphasis>host machine</emphasis>.
71 </para>
72 </listitem>
73
74 <listitem>
75 <para>
76 Each <emphasis>target machine</emphasis> only needs one RPM package to be installed in order to use the generated SystemTap instrumentation module: the <package>systemtap-runtime</package> package.
77 </para>
78 </listitem>
79 </itemizedlist>
80
81 <!--
82
83 <para>
84 Such a task does not scale well as the number of systems you are monitoring increases. As such, if you need to run a SystemTap script against a wide number of machines, you can simplify your deployment and monitoring through <firstterm>cross-instrumentation</firstterm>.
85 </para>
86
87 <para>
88 <firstterm>Cross-instrumentation</firstterm> is the process of building the resulting kernel module from a SystemTap script on a <emphasis>host</emphasis> machine to be loaded on another <emphasis>target machine</emphasis>. In a manner of speaking, this process allows you to "run" SystemTap scripts on a machine without having to install the necessary debug RPMs for its kernel.
89 </para>
90
91
92 <para>
93 To illustrate; Tom has 25 systems, all of which have the same kernel. If Tom wants to run the SystemTap <filename>script.stp</filename> on all of them, he could install SystemTap and the necessary debug RPMs <emphasis>on each of the 25 machines</emphasis>. This is a tedious enough task to perform on 25 systems; what more if each system had a different kernel?
94 </para>
95 Alternatively, however, Tom can simply perform cross-instrumentation; this allows him to simply deploy SystemTap fully on one machine, build the necessary kernel module from <filename>script.stp</filename> on that machine, and load that module on each of the other systems.
96 </para>
97
98 -->
99
100 <para>
101 For the sake of simplicity, the following terms are used
102 throughout this section:
103 </para>
104
105 <itemizedlist>
106 <listitem>
107 <para>
108 <indexterm>
109 <primary>cross-instrumentation</primary>
110 <secondary>instrumentation module</secondary>
111 </indexterm>
112
113 <indexterm>
114 <primary>instrumentation module</primary>
115 <secondary>cross-instrumentation</secondary>
116 </indexterm>
117 <emphasis>Instrumentation module</emphasis> &mdash; the
118 kernel module built from a SystemTap script. The
119 <emphasis>SystemTap module</emphasis> is built on the <emphasis>host
120 system</emphasis>, and will be loaded on the <emphasis>target
121 kernel</emphasis> of <emphasis>target
122 system</emphasis>.
123 </para>
124 </listitem>
125
126 <listitem>
127 <para>
128 <indexterm>
129 <primary>cross-instrumentation</primary>
130 <secondary>host system</secondary>
131 </indexterm>
132
133 <indexterm>
134 <primary>host system</primary>
135 <secondary>cross-instrumentation</secondary>
136 </indexterm>
137 <emphasis>Host system</emphasis> &mdash; the system on
138 which you compile the <emphasis>instrumentation modules</emphasis> from SystemTap
139 scripts in order to load them on <emphasis>target
140 systems</emphasis>.
141 </para>
142 </listitem>
143
144 <listitem>
145 <para>
146 <indexterm>
147 <primary>cross-instrumentation</primary>
148 <secondary>target system</secondary>
149 </indexterm>
150
151 <indexterm>
152 <primary>target system</primary>
153 <secondary>cross-instrumentation</secondary>
154 </indexterm>
155
156 <emphasis>Target system</emphasis> &mdash; the system for which you
157 are building the <emphasis>instrumentation modules</emphasis> from
158 SystemTap scripts.
159 </para>
160 </listitem>
161
162 <listitem>
163 <para>
164 <indexterm>
165 <primary>cross-instrumentation</primary>
166 <secondary>target kernel</secondary>
167 </indexterm>
168
169 <indexterm>
170 <primary>target kernel</primary>
171 <secondary>cross-instrumentation</secondary>
172 </indexterm>
173 <emphasis>Target kernel</emphasis> &mdash; the kernel of
174 the <emphasis>target system</emphasis>. This is the kernel on which
175 you intend to load or run the <emphasis>instrumentation
176 module</emphasis>.
177 </para>
178 </listitem>
179 </itemizedlist>
180
181 <!--
182 running a SystemTap script on a target system where SystemTap is not installed. Normally, to run a SystemTap script on a system, you need to deploy SystemTap on it first (as in <xref linkend="installproper"/>).
183 </para> -->
184
185 <!-- <para>
186 This section teaches you how to deploy SystemTap on a host machine, from which you can create the necessary kernel module/s to be loaded on client machines. These kernel modules are built from SystemTap scripts you wish to run on the client machine.
187 </para>-->
188
189 <para>
190 To configure a host system and target systems, complete the following steps:
191 </para>
192
193 <procedure id="preppingxcompile">
194 <indexterm>
195 <primary>cross-instrumentation</primary>
196 <secondary>configuration</secondary>
197 <tertiary>host system and target system</tertiary>
198 </indexterm>
199
200 <indexterm>
201 <primary>host system and target system</primary>
202 <secondary>cross-instrumentation</secondary>
203 <tertiary>configuration</tertiary>
204 </indexterm>
205
206 <indexterm>
207 <primary>target system and host system</primary>
208 <secondary>configuration</secondary>
209 </indexterm>
210 <step>
211 <para>
212 Install the <package>systemtap-runtime</package> package on each
213 <emphasis>target system</emphasis>.
214 </para>
215 </step>
216
217 <step>
218 <para>
219 Determine the kernel running on each <emphasis>target system</emphasis>
220 by running the <command>uname -r</command> command on each of these systems.
221 </para>
222 </step>
223
224 <step>
225 <para>
226 Install SystemTap on the <emphasis>host system</emphasis>.
227 You will be building the <emphasis>instrumentation
228 module</emphasis> for the <emphasis>target
229 systems</emphasis> on the <emphasis>host system</emphasis>.
230 For instructions on how to install SystemTap, refer
231 to <xref linkend="installproper"/>.
232 </para>
233 </step>
234
235 <step>
236 <para>
237 Using the <emphasis>target kernel</emphasis> version determined earlier,
238 install the <emphasis>target kernel</emphasis> and related RPM packages on the
239 <emphasis>host system</emphasis> as described in <xref
240 linkend="install-kinfo"/>. If multiple <emphasis>target
241 systems</emphasis> use different <emphasis>target kernels</emphasis>,
242 repeat this step for each different kernel used on the
243 <emphasis>target systems</emphasis>.
244 </para>
245 </step>
246
247 </procedure>
248
249 <para>
250 After completing these steps, you can now build the
251 <emphasis>instrumentation module</emphasis> (for any <emphasis>target
252 system</emphasis>) on the <emphasis>host system</emphasis>.
253 </para>
254
255 <para>
256 To build the <emphasis>instrumentation module</emphasis>, run the following
257 command on the <emphasis>host system</emphasis> (be sure to specify the
258 appropriate values):
259 </para>
260
261 <screen><command>stap -p4 -r <replaceable>kernel_version</replaceable> <replaceable>script</replaceable> -m <replaceable>module_name</replaceable></command></screen>
262
263 <para>
264 Here, <replaceable>kernel_version</replaceable> refers to
265 the version of the <emphasis>target kernel</emphasis> (the output of
266 the <command>uname -r</command> command on the target machine),
267 <replaceable>script</replaceable> refers to the script to
268 be converted into the <emphasis>instrumentation module</emphasis>, and
269 <replaceable>module_name</replaceable> is the desired
270 name of the <emphasis>instrumentation module</emphasis>.
271 </para>
272
273 <note>
274 <title>Note</title>
275 <indexterm>
276 <primary>uname -m</primary>
277 </indexterm>
278
279 <indexterm>
280 <primary>determining architecture notation</primary>
281 </indexterm>
282
283 <indexterm>
284 <primary>architecture notation, determining</primary>
285 </indexterm>
286 <para>
287 To determine the architecture notation of a running kernel, you can run the following command:
288 </para>
289
290 <screen><command>uname -m</command></screen>
291 </note>
292
293 <para>
294 Once the <emphasis>instrumentation module</emphasis> is compiled, copy
295 it to the <emphasis>target system</emphasis> and then load it using:
296 </para>
297
298 <screen><command>staprun <replaceable>module_name</replaceable>.ko</command></screen>
299
300 <para>
301 For example, to create the
302 <emphasis>instrumentation module</emphasis> <filename>simple.ko</filename>
303 from a SystemTap script named
304 <filename>simple.stp</filename> for the <emphasis>target kernel</emphasis>
305 2.6.18-92.1.10.el5 (on x86_64 architecture), use the following command:
306 </para>
307
308 <screen><command>stap -r 2.6.18-92.1.10.el5 -e 'probe vfs.read {exit()}' -m simple</command></screen>
309
310 <para>
311 This creates a module named <filename>simple.ko</filename>. To use this
312 <emphasis>instrumentation module</emphasis>,
313 copy it to the <emphasis>target system</emphasis> and run the following
314 command (on the <emphasis>target system</emphasis>):
315 </para>
316
317 <screen><command>staprun simple.ko</command></screen>
318
319 <!--<procedure id="preppingxcompile">
320 <title>Preparing for a Cross-Compile</title>
321
322 <step>
323 <para>Note the version of the target system's kernel on which you wish to use SystemTap. You can do this by logging onto the target system and running <command>uname -r</command> (assuming the system is running the kernel on which you wish to use SystemTap), or by inspecting <filename>/boot</filename>.</para>
324 </step> -->
325 <important>
326 <title>Important</title>
327 <para>
328 The <emphasis>host system</emphasis> must be the same architecture and
329 running the same distribution of Linux as the <emphasis>target
330 system</emphasis> in order for the built <emphasis>instrumentation
331 module</emphasis> to work.
332 </para>
333 </important>
334
335 </section>