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
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
|
<?xml version='1.0'?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
<section id="cross-compiling">
<title>Generating Instrumentation for Other Computers</title>
<remark>
cross-compiling script from here:
http://sources.redhat.com/ml/systemtap/2008-q3/msg00310.html
</remark>
<remark>
above; add short description, significance, howto, script (test first)
</remark>
<para>
When users run a SystemTap script, SystemTap builds a kernel module out of
that script. SystemTap then loads the module onto the kernel, allowing it to
extract the specified data directly from the kernel (refer to
<xref linkend="systemtapsession"/> in
<xref linkend="understanding-architecture-tools"/> for more information).
</para>
<para>
Normally, however, SystemTap scripts can only be run on systems where
SystemTap is deployed (as in <xref linkend="installproper"/>). 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 to fully deploy SystemTap on those
systems. For instance corporate policy may prohibit an administrator from
installing RPMs that proved debug information or compilers on specific
machines, which will prevent the deployment of SystemTap.
</para>
<para>
To work around this, you can resort to
<firstterm>cross-instrumentation</firstterm>. Cross-instrumentation is the
process of generating SystemTap instrumentation module from a SystemTap
script on one computer to be used on another machine. This process offers
the following benefits:
</para>
<itemizedlist>
<listitem>
<para>
The debug RPMs for various machines can be installed on a single system:
the host machine.
</para>
</listitem>
<listitem>
<para>
Each target machine only needs one RPM to installed to use
the generated SystemTap instrumentation module:
<filename>systemtap-runtime</filename>.
</para>
</listitem>
</itemizedlist>
<!--
<para>
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>.
</para>
<para>
<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.
</para>
<para>
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?
</para>
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.
</para>
-->
<note>
<title>Note</title>
<para>
For the sake of simplicity, we will be using the following terms
throughout this section:
</para>
<itemizedlist>
<listitem>
<para>
<emphasis>instrumentation module</emphasis> — the
kernel module built from a SystemTap script; i.e. the
<emphasis>SystemTap module</emphasis> is built on the <emphasis>host
system</emphasis>, and will be loaded on the <emphasis>target
kernel</emphasis> of <emphasis>target
system</emphasis>.
</para>
</listitem>
<listitem>
<para>
<emphasis>host system</emphasis> — the system on
which you compile the instrumentation modules (from SystemTap
scripts), to be loaded on <emphasis>target
systems</emphasis>.
</para>
</listitem>
<listitem>
<para>
<emphasis>target system</emphasis> — the system for which you
are building the <emphasis>instrumentation module</emphasis> (from
SystemTap scripts).
</para>
</listitem>
<listitem>
<para>
<emphasis>target kernel</emphasis> — the kernel of
the <emphasis>target system</emphasis>. This is the kernel on which
you wish to load/run the <emphasis>instrumentation
module</emphasis>.
</para>
</listitem>
</itemizedlist>
</note>
<!--
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"/>).
</para> -->
<!-- <para>
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.
</para>-->
<procedure id="preppingxcompile">
<title>Configuring a Host System and Target Systems</title>
<step>
<para>
Install the <filename>systemtap-runtime</filename> RPM on each
<emphasis>target system</emphasis>.
</para>
</step>
<step>
<para>
Determine the kernel running on each <emphasis>target system</emphasis>
by running the by running <command>uname -r</command> on each
<emphasis>target system</emphasis>:
</para>
</step>
<step>
<para>
Install SystemTap on the <emphasis>host system</emphasis>. It is from
this machine that you will be building the <emphasis>instrumentation
module</emphasis> (to be used on <emphasis>target
systems</emphasis>). For instructions on how to install SystemTap, refer
to <xref linkend="installproper"/>.
</para>
</step>
<step>
<para>
Using the <emphasis>target kernel</emphasis> version determined earlier,
install the <emphasis>target kernel</emphasis> and related RPMs on the
<emphasis>host system</emphasis> by the method described in <xref
linkend="install-kinfo"/>. If multiple <emphasis>target
systems</emphasis> use different <emphasis>target kernels</emphasis>,
you will need to repeat this step for each different kernel used on the
<emphasis>target systems</emphasis>.
</para>
</step>
</procedure>
<para>
After performing <xref linkend="preppingxcompile"/>, you can now build the
<emphasis>instrumentation module</emphasis> (for any <emphasis>target
system</emphasis>) on the <emphasis>host system</emphasis>.
</para>
<para>
To build the <emphasis>instrumentation module</emphasis>, run the following
command on the <emphasis>host system</emphasis> (be sure to specify the
appropriate values):
</para>
<para>
<command>stap -r <replaceable>kernel_version</replaceable>
<replaceable>script</replaceable> -m
<replaceable>module_name</replaceable></command>
</para>
<para>
Here, <command><replaceable>kernel_version</replaceable></command> refers to
the version of the <emphasis>target kernel</emphasis> (the output of
<command>uname -r</command> on the target machine),
<command><replaceable>script</replaceable></command> refers to the script to
be converted into an <emphasis>instrumentation module</emphasis>, and
<command><replaceable>module_name</replaceable></command> is the desired
name of the <emphasis>instrumentation module</emphasis>.
</para>
<note>
<title>Note</title>
<para>
To determine the architecture notation of a running kernel, run
<command>uname -m</command>.
</para>
</note>
<para>
Once the the <emphasis>instrumentation module</emphasis> is compiled, copy
it to the <emphasis>target system</emphasis> and load it using:
</para>
<para>
<command>staprun <replaceable>module_name</replaceable>.ko</command>
</para>
<para>
For example, to create the <emphasis>instrumentation module</emphasis>
<filename>simple.ko</filename> from a SystemTap script named
<filename>simple.stp</filename> for the <emphasis>target kernel</emphasis>
2.6.18-92.1.10.el5 (on x86_64 architecture), use the following command:
</para>
<para>
<command>stap -r 2.6.18-92.1.10.el5 -e 'probe vfs.read {exit()}' -m simple</command>
</para>
<para>
This will create a module named <filename>simple.ko</filename>. To use the
<emphasis>instrumentation module</emphasis> <filename>simple.ko</filename>,
copy it to the <emphasis>target system</emphasis> and run the following
command (on the <emphasis>target system</emphasis>):
</para>
<para><command>staprun simple.ko</command></para>
<!--<procedure id="preppingxcompile">
<title>Preparing for a Cross-Compile</title>
<step>
<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>
</step> -->
<important>
<title>Important</title>
<para>
The <emphasis>host system</emphasis> must be the same architecture and
running the same distribution of Linux as the <emphasis>target
system</emphasis> in order for the <emphasis>instrumentation
module</emphasis> to work.
</para>
</important>
</section>
|
