Debian Codegraph @

man/cs/stapprobes.3stap

raw
1 .\" t
2 .TH STAPPROBES 3stap
3 .SH JMÉNO
4 stapprobes \- přehled sondážních bodů systemtapu
5
6 .\" macros
7 .de SAMPLE
8
9 .nr oldin \\n(.i
10 .br
11 .RS
12 .nf
13 .nh
14 ..
15 .de ESAMPLE
16 .hy
17 .fi
18 .RE
19 .in \\n[oldin]u
20
21 ..
22
23 .SH POPIS
24
25 Následující text přináší přehled základních druhů sondážních bodů (probe
26 points) podporovaných překladačem systemtapu. Zmíněny jsou také některé
27 přezdívky (aliases) definované v tapset skriptech. Podrobnější individuální
28 informace k mnohým z nich přinášejí man stránky s prefixem
29
30 .IR probe::
31 sdružené v man sekci
32 .IR 3stap .
33
34 .SH SYNTAXE
35
36 .PP
37 .SAMPLE
38 .BR probe " PROBEPOINT [" , " PROBEPOINT] " { " [STMT ...] " }
39 .ESAMPLE
40 .PP
41
42
43 Deklarace sondy (probe) může obsahovat seznam čárkou oddělených sondážních
44 bodů. Sonda pak bude svázána se všemi takto zmíněnými sondážními body, potažmo
45 událostmi v systému.
46
47 .PP
48
49 Jednotlivý sondážní bod se zapíše jako posloupnost tečkou oddělených komponent,
50 například 'syscall.read', kde 'syscall' a 'read' jsou komponenty. Komponenty
51 odpovídají určitým třídám dělení jmenného prostoru událostí. Připomíná to
52 zápis doménového jména počítače na internetu. Každá komponenta může být
53 přesněji specifikována číselným, nebo řetězcovým parametrem uvedeným v
54 závorkách, podobně jako při volání funkce. V rámci deklarace sondy lze použít
55 zástupný symbol hvězda "*", který bude expandován v rámci jedné z tečkou oddělených
56 komponent, nebo symbol "**", který bude expandován přes více než jednu komponentu
57 (v extrémním případě přes všechny).
58
59 .PP
60 Přezdívka sondy se syntakticky chová podobně jako sonda samotná. Lze též
61 pracovat s přezdívkami přezdívek. Přezdívku sondy lze volat samostatně, nebo s
62 příponou. Přípona se při překladu připojí k sondě nad kterou je přezdívka
63 definovaná. Příklad:
64
65 .SAMPLE
66 syscall.read.return.maxactive(10)
67 .ESAMPLE
68 se expanduje na
69 .SAMPLE
70 kernel.function("sys_read").return.maxactive(10)
71 .ESAMPLE
72 kde
73 .IR maxactive(10)
74 se chápe jako přípona.
75 .PP
76
77 Každý sondážní bod se po expanzi zástupných symbolů a přezdívek mapuje na nějaký
78 nízkoúrovňový prvek systému, jako například na 'kprobe' adresu, na značku
79 (marker), na událost časovače a podobně. Pokud takové mapování selže (například
80 snažíme-li se odkázat na jaderný modul který není zaveden), překlad skriptu
81 selže.
82 .PP
83 Sondážní bod může být následován znakem "?", a pak je považován za
84 .IR volitelný.
85 V tom případě nedojde k chybě překladu, pokud se mapování nezdaří.
86 Tento příznak volitelnosti se při překladu předává níže přes přezdívky a expanze
87 až k elementárním sondážním bodům překladače.
88 Sondážní bod může být též následován znakem "!". V tom případě je považován za
89 .IR volitelný
90 a
91 .IR dostatečný.
92 Volně to připomíná 'cut' operátor známý z prologu. Pokud se takový
93 "dostatečný" sondážní bod podaří úspěšně namapovat, pak se už překladač
94 nepokouší o mapování dalších (čárkou oddělených) sondážních bodů definujících
95 danou sondu. Označit sondážní bod za dostatečný tedy dává smysl jen je-li v
96 definici sondy následován dalším sondážním bodem.
97
98 .PP
99 Dále může být sondážní bod následován výrazem podmínky "if (expr)". Tím lze
100 sondážní bod za běhu aktivovat, či deaktivovat. Pokud 'expr' je nepravda,
101 sondážní bod je neaktivní. Podmínka se při překladu předává níže přes
102 přezdívky a expanze až k elementárním sondážním bodům překladače, takže na
103 nejnižší úrovni představuje podmínka logický součin příslušných podmínek na
104 elementárních sondážních bodech. Podmínka 'expr' může zákonitě být založena
105 jen na globálních proměnných a při tom nesmí měnit jejich hodnotu (např. i++
106 není povoleno).
107
108 .PP
109 Následující sondážní body jsou
110 .B syntakticky
111 korektní. (Jejich
112 .B sémantika
113 závisí na obsahu tapsetu, verzi jádra analyzovaného systému atd. Pro Váš
114 systém jsou pravděpodobně sémanticky nevalidní.)
115
116 .SAMPLE
117 kernel.function("foo").return
118 process("/bin/vi").statement(0x2222)
119 end
120 syscall.*
121 syscall.*.return.maxactive(10)
122 syscall.{open,close}
123 sys**open
124 kernel.function("no_such_function") ?
125 module("awol").function("no_such_function") !
126 signal.*? if (switch)
127 kprobe.function("foo")
128 .ESAMPLE
129
130 Sondy lze obecně klasifikovat na "synchronní" a "asynchronní". Za synchronní
131 považujeme sondu (resp. událost), kdy např. některý z procesorů vykonal danou
132 instrukci. Tím je dán referenční bod na základě kterého může sonda získat
133 další kontextové informace. Za asynchronní považujeme např. událost časovače.
134 Asynchronní sonda nemá k dispozici kontextové informace. Každá sonda může být
135 definovaná na základě množství sondážních bodů například prostřednictvím
136 zástupných symbolů, přezdívek, nebo dalších čárkou oddělených sondážních bodů.
137 Jakmile kterýkoliv z nich detekuje událost, sonda se aktivuje (probe point is
138 hit) a spustí obslužnou rutinu, což je blok kódu (probe handler).
139
140 Závorková expanze je úsporný způsob zápisu většího množství sondážních bodů, které
141 dohromady tvoří sondu. Do složených závorek se uvede seznam čárkou oddělených
142 subkomponent a/nebo případně dalších (vnořených) závorkových expanzí. Expanze
143 sonděhne v daném pořadí.
144
145 Otazník (?), vykřičník (!) a podmínky (if (expr)) musí být uvedeny za poslední
146 komponentou sondážního bodu.
147
148 Příklad závorkové expanze:
149
150 .SAMPLE
151 syscall.{write,read}
152 # Se expanduje na
153 syscall.write, syscall.read
154
155 {kernel,module("nfs")}.function("nfs*")!
156 # Se expanduje na
157 kernel.function("nfs*")!, module("nfs").function("nfs*")!
158 .ESAMPLE
159
160 .SH LADICÍ INFORMACE FORMÁTU DWARF
161
162 Vyhodnocení některých sondážních bodů vyžaduje relevantní ladicí informace
163 formátu (DWARF). Pro některé sondážní body si umí systemtap zrekonstruovat
164 potřebné ladicí informace na základě hlavičkových souborů sám. Pro jiné
165 sondážní body nejsou ladicí informace potřeba. Vzhledem k tomu, že systemtap
166 skript může obsahovat libovolný mix různých typů sond, výsledné požadavky
167 celého skriptu na dostupnost ladicích informací jsou sjednocením odpovídajících
168 požadavků pro jednotlivé sondážní body. Ladicí informace jsou potřebné v
169 okamžiku kdy dochází k překladu skriptu. K té nemusí nutně dojít na systému,
170 kde bude systemtap modul nakonec použit. Viz volba \fI\-\-use\-server\fR a
171 termín \fBstap-server\(8)\fR v manuálové stránce stap(1)).
172 .PP
173 Následuje seznam dostupných rodin sondážních bodů rozdělený podle jejich nároků
174 na dostupnost ladicích informací:
175
176 .TS
177 l l l.
178 \fBDWARF NON-DWARF SYMBOL-TABLE\fP
179
180 kernel.function, .statement kernel.mark kernel.function\fI*\fP
181 module.function, .statement process.mark, process.plt module.function\fI*\fP
182 process.function, .statement begin, end, error, never process.function\fI*\fP
183 process.mark\fI*\fP timer
184 \.function.callee perf
185 python2, python3 procfs
186 kernel.statement.absolute
187 \fBAUTO-GENERATED-DWARF\fP kernel.data
188 kprobe.function
189 kernel.trace process.statement.absolute
190 process.begin, .end
191 netfilter
192 java
193 .TE
194
195 .PP
196
197 Pro rodiny sond označené hvězdou \fI*\fP, si dokáže systemtap za určitých
198 okolností vygenerovat část ladicích informací z hlavičkových souborů sám.
199 Obecně platí, že čím více relevantních ladicích informací je k dispozici,
200 tím vyšší bude kvalita analýzy.
201
202 .SH ODEMYKÁNÍ A ZAMYKÁNÍ SOND ZA BĚHU
203
204 Následující typy sondážních bodů lze podle potřeby zamknout / odemknout za
205 běhu. Tím lze snížit zatížení systému. Odemčená sonda je neaktivní, zamčená
206 je aktivní. Odemčená sonda nekonzumuje systémové prostředky.
207
208
209 .TS
210 l l.
211 \fBODEMYKATELNÉ výjimky\fP
212 kernel.function, kernel.statement
213 module.function, module.statement
214 process.*.function, process.*.statement
215 process.*.plt, process.*.mark
216 timer. timer.profile
217 java
218 .TE
219
220 Odemykání lze předepsat i jiným typům sond, ale v jejich případě nedojde k
221 úsporám systémových prostředků.
222
223 .SH TYPY SONDÁŽNÍCH BODŮ
224
225 .SS BEGIN/END/ERROR
226
227 Sondážní body
228 .IR begin " a " end
229 jsou definovány překladačem a odkazují k okamžikům startu, resp. ukončení
230 skriptu. Obslužné rutiny svázané se všemi 'begin' sondami se v určitém pořadí
231 provedou během startu systemtap sezení. Před tím se inicializují všechny
232 globální proměnné. Obslužné rutiny svázané s 'end' sondami se provedou v daném
233 pořadí během
234 .I normálního
235 ukončení sezení, jako například po vykonání funkce
236 .I exit ()
237 , nebo pokud sezení ukončí uživatel (Ctrl-C). V případě, kdy sezení skončí v důsledku
238 chyby, nebudou 'end' sondy aktivní. V kontextu 'end' sond neexistují žádné
239 cílové proměnné.
240 .PP
241 Pořadí vykonání jednotlivých "begin" a "end" sond, lze určit pořadovým číslem:
242
243 .SAMPLE
244 begin(N)
245 end(N)
246 .ESAMPLE
247
248 Číslo M může být kladné i záporné. Sondy budou aktivní ve vzestupném pořadí
249 svých pořadových čísel. Pořadí vykonání sond se stejným pořadovým číslem je
250 nedefinované. Kde není pořadové číslo explicitně uvedeno, pracuje se efektivně
251 s nulou.
252
253 Sondážní bod
254 .IR error
255 je podobný sondážnímu bodu
256 .IR end
257 až na to, že je aktivován při ukončení sezení v důsledku chyby. V takových
258 případech se 'end' sondy přeskočí, ale dojde k pokusu vykonat všechny 'error'
259 sondy. Tento typ sond lze využít k závěrečnému úklidu. Také 'error' sondám lze
260 nastavit pořadí vykonání.
261
262 .SS NEVER
263 Sondážní bod
264 .IR never
265 je speciálně definovaný překladačem a znamená "nikdy". Obslužná rutina spojená
266 s touto sondou se nikdy nevykoná, nicméně její příkazy projdou analýzou
267 překladače. Tato sonda může být užitečná v kombinaci s volitelnými (optional)
268 sondami.
269
270 .SS SYSCALL a ND_SYSCALL
271
272 Přezdívky
273 .IR syscall.* " a " nd_syscall.*
274 definují několik set sond. Příliš mnoho pro detailní popis na tomto místě.
275 Zde je obecná forma:
276
277 .SAMPLE
278 syscall.NAME
279 .br
280 nd_syscall.NAME
281 .br
282 syscall.NAME.return
283 .br
284 nd_syscall.NAME.return
285 .ESAMPLE
286
287 Pro každé běžné systémové volání (viz
288 .IR syscalls(2)
289 ) je definována dvojice sond: Jedna pro vstup a druhá pro opuštění systémového
290 volání. Systémová volání, která nikdy neskončí, nemají odpovídající
291 .IR .return
292 sondu. Rodina 'nd_*' sond je velmi podobná s tím rozdílem, že používá
293 .B non-DWARF
294 přístup, tedy nevyžaduje ke své činnosti ladicí informace. Mohou být
295 užitečné zejména není-li k dispozici RPM balíček kernel-debuginfo s ladicími
296 informacemi jádra.
297 .PP
298 Přezdívky obvykle poskytují řadu proměnných, se kterými lze v rámci obslužné
299 rutiny sondy pracovat. Jejich kompletní seznam je obsažen v tapset skriptech.
300 Tam je vhodné nahlédnout. Například
301 .IR syscall.open
302 poskytuje následující proměnné:
303 .IR filename ", " flags ", a " mode .
304 Kromě nich jsou v každém 'syscall.*' sondážním bodu dostupné standardní proměnné
305 jako:
306 .TP
307 .IR argstr
308 Řetězec obsahující hodnoty všech argumentů.
309 .TP
310 .IR name
311 Jméno systémového volání.
312 .TP
313 .IR retstr
314 Řetězec obsahující návratovou hodnotu systémového volání (dostupný v sondách
315 pro výstup ze systémového volání).
316 .PP
317 Tyto proměnné jsou inicializovány v určitém okamžiku při vstupu / výstupu do /
318 ze systémového volání na základě kontextových proměnných a tudíž nereflektují
319 eventuální pozdější změny těchto kontextových proměnných.
320
321 .SS ČASOVAČE
322 Existují dva hlavní typy 'timer' sond: Jsou to sondy 'jiffies', a sondy pro
323 časové intervaly.
324
325 Časové intervaly jsou v terminologii linuxového jádra definovány v jednotkách
326 "jiffies" (odpovídající přibližně 1 až 60 ms). Časovač aktivuje asynchronní
327 sondy 'timer'. Překladač podporuje dvě varianty těchto sond:
328
329 .SAMPLE
330 timer.jiffies(N)
331 timer.jiffies(N).randomize(M)
332 .ESAMPLE
333
334 Sonda je aktivována každých N jiffies. Pokud je dána komponenta 'randomize',
335 je k hodnotě N přičteno náhodné číslo v rozmezí -M .. +M. Při tom N musí
336 nabývat rozumných hodnot, tj. přibližně z intervalu 1 .. 1e+6, a současně M < N.
337 Časovače neposkytují žádné kontextové proměnné. Na multiprocesorových
338 systémech mohou tyto sondy běžet současně.
339
340 .PP
341 Časové intervaly mohou být případně vyjádřeny i v jiných jednotkách. Příklad:
342
343 .SAMPLE
344 timer.ms(N)
345 timer.ms(N).randomize(M)
346 .ESAMPLE
347
348 V tomto případě jsou M a N vyjádřeny v milisekundách. Analogicky je možno čas
349 vyjadřovat v sekundách (s/sec), milisekundách (ms/msec), mikrosekundách
350 (us/usec), nanosekundách (ns/nsec), a v hertzích (Hz). Randomizace není
351 podporována je-li čas vyjádřen v jednotkách Hz.
352
353 Skutečná přesnost časovačů závisí na konkrétním jádru. U jader starších než
354 2.6.17 byla nejmenší jednotka času jiffie, takže zadané časové intervaly se
355 zaokrouhlily na celý počet jiffies. U novějších jader jsou časovače založeny na
356 tzv. 'hrtimers' pro vyšší přesnost. Ovšem skutečná přesnost závisí na
357 architektuře. V každém případě, pokud je dána komponenta 'randomize', pak náhodná
358 složka bude přidána před případným zaokrouhlováním.
359 .PP
360 Existují také profilovací časovače, které tikají na všech CPU frekvencí
361 CONFIG_HZ. Na některých systémech může tento časovač používat jen jediný
362 uživatel, na jiných systémech může být tento časovač nedostupný (EBUSY během
363 registrace sondy).
364
365 .SAMPLE
366 timer.profile.tick
367 timer.profile.freq.hz(N)
368 .ESAMPLE
369
370 Při použití tohoto časovače je k dispozici plný kontext přerušeného procesu,
371 takže tento časovač je vhodný pro sbírání profilovacích vzorků.
372 .PP
373 Doporučujeme používat
374 .IR timer.profile
375 namísto timer.profile.tick. Obě sondy se chovají podobně, pokud je dostupná
376 potřebná funkcionalita jádra. Ale timer.profile umí na novějších jádrech
377 transparentně využít perf.sw.cpu_clock. Je tedy obecnější.
378 .PP
379 Profilovací časovače s určenou frekvencí jsou přesné jen přibližně do 100 Hz.
380
381 .PP
382 Poznamenejme, že pokud je frekvence 'timer' sondy příliš vysoké, a tělo sondy
383 příliš složité, mohou být některé aktivace dané sondy přeskočeny, neboť
384 jejich čas již uplynul. Normálně systemtap hlásí přeskočené sondy, ovšem takto
385 přeskočené 'timer' sondy hlášeny nebudou.
386
387 .SS LADICÍ INFORMACE (DWARF)
388
389 Tato rodina sondážních bodů používá symbolické ladicí informace k analýze
390 jádra / modulu / programu. Ladicí informace mohou být buďto přímou součástí
391 zkoumaného ELF objektu (unstripped), nebo samostatně stojící (stripped) např. v
392 rámci
393 .I debuginfo
394 RPM balíčků. Umožňují umístit sondy do exekuční cesty programu prostřednictvím
395 symbolické specifikace umístění ve zdrojovém, nebo objektovém kódu. Jakmile se
396 odpovídající příkaz na některé CPU vykoná, spustí se obslužný kód sondy v daném
397 kontextu.
398 .PP
399 Existuje několik druhů DWARF sond založených na ladicích informacích. Mohou být
400 specifické pro jádro, jaderný modul, či uživatelský proces. Mohou se odkazovat na
401 zdrojový soubor, na konkrétní řádku nebo funkci v něm, anebo na nějakou kombinaci
402 uvedeného.
403
404 .PP
405 Zde je seznam konkrétně podporovaných DWARF sond:
406 .SAMPLE
407 kernel.function(PATTERN)
408 kernel.function(PATTERN).call
409 kernel.function(PATTERN).callee(PATTERN)
410 kernel.function(PATTERN).callee(PATTERN).return
411 kernel.function(PATTERN).callee(PATTERN).call
412 kernel.function(PATTERN).callees(DEPTH)
413 kernel.function(PATTERN).return
414 kernel.function(PATTERN).inline
415 kernel.function(PATTERN).label(LPATTERN)
416 module(MPATTERN).function(PATTERN)
417 module(MPATTERN).function(PATTERN).call
418 module(MPATTERN).function(PATTERN).callee(PATTERN)
419 module(MPATTERN).function(PATTERN).callee(PATTERN).return
420 module(MPATTERN).function(PATTERN).callee(PATTERN).call
421 module(MPATTERN).function(PATTERN).callees(DEPTH)
422 module(MPATTERN).function(PATTERN).return
423 module(MPATTERN).function(PATTERN).inline
424 module(MPATTERN).function(PATTERN).label(LPATTERN)
425 kernel.statement(PATTERN)
426 kernel.statement(PATTERN).nearest
427 kernel.statement(ADDRESS).absolute
428 module(MPATTERN).statement(PATTERN)
429 process("PATH").function("NAME")
430 process("PATH").statement("*@FILE.c:123")
431 process("PATH").library("PATH").function("NAME")
432 process("PATH").library("PATH").statement("*@FILE.c:123")
433 process("PATH").library("PATH").statement("*@FILE.c:123").nearest
434 process("PATH").function("*").return
435 process("PATH").function("myfun").label("foo")
436 process("PATH").function("foo").callee("bar")
437 process("PATH").function("foo").callee("bar").return
438 process("PATH").function("foo").callee("bar").call
439 process("PATH").function("foo").callees(DEPTH)
440 process(PID).function("NAME")
441 process(PID).function("myfun").label("foo")
442 process(PID).plt("NAME")
443 process(PID).plt("NAME").return
444 process(PID).statement("*@FILE.c:123")
445 process(PID).statement("*@FILE.c:123").nearest
446 process(PID).statement(ADDRESS).absolute
447 .ESAMPLE
448 (Viz sekce ANALÝZA UŽIVATELSKÝCH PROCESŮ níže)
449 .PP
450 Ve výše uvedených sondách lze používat následující modifikátory / filtry, které
451 přinášejí dodatečnou funkcionalitu:
452 .RS
453 .TP
454 \fB.function\fR
455 Umístí sondu poblíž začátku uvedené funkce, takže funkční parametry jsou
456 dostupné jako kontextové proměnné.
457 .TP
458 \fB.return\fR
459 Umístí sondu hned \fBza\fR bod návratu z dané funkce, takže návratová hodnota
460 funkce je dostupná jako kontextová proměnná "$return".
461 .TP
462 \fB.inline\fR
463 Filtr propouštějící jen 'inline' funkce. Poznamenejme, že 'inline' funkce nemají
464 identifikovatelný bod návratu, takže \fB.return\fR na \fB.inline\fR funkcích
465 nelze použít.
466 .TP
467 \fB.call\fR
468 Filtr propouštějící jen funkce, které nejsou 'inline' (opak \fB.inline\fR).
469 .TP
470 \fB.exported\fR
471 Filtr propouštějící jen exportované funkce.
472 .TP
473 \fB.statement\fR
474 Vloží sondu na konkrétní místo a zpřístupní lokální proměnné které jsou v daném
475 kontextu viditelné.
476 .TP
477 \fB.statement.nearest\fR
478 Vloží sondu na místo nejbližší danému číslu řádku (pro každé číslo řádku předané
479 jako parametr 'statement')
480 .TP
481 \fB.callee\fR Vloží sondu do volané funkce \fB.callee\fR, která je volána funkcí
482 \fB.function\fR. Oproti přímému umístění sondy do funkce \fB.callee\fR má tento
483 způsob výhodu v tom, že sonda bude aktivní jen když volaná funkce \fB.callee\fR
484 bude volána z dané funkce \fB.function\fR. Toto chování lze potlačit direktivou
485 -DSTAP_CALLEE_MATCHALL, viz \fBstap\fR(1)).
486
487 Poznamenejme, že mechanizmus 'callee' lze použít jen na staticky dohledatelné
488 funkce. Mechanizmus 'callee' nelze použít například na funkce volané
489 prostřednictvím ukazatele, nebo na funkce z DSO knihoven. Další podmínkou je,
490 aby kód byl překládán GCC 4.7+.
491
492 .TP
493 \fB.callees\fR
494 Zkratka pro \fB.callee("*")\fR. Vloží sondu do všech funkcí volaných zadanou
495 funkcí.
496 .TP
497 \fB.callees\fR(DEPTH)
498 Rekurzivně umístí sondy do volaných funkcí až do hloubky DEPTH. Například
499 \fB.callees(2)\fR vloží sondu nejen do volaných funkcí, ale i do jimi volaných
500 funkcí. Sonda v hloubce N bude aktivní jen když všechny volající funkce budou
501 staticky dohledatelné. Toto chování lze potlačit direktivou
502 -DSTAP_CALLEE_MATCHALL, viz \fBstap\fR(1)).
503 .RE
504 .PP
505 Ve výše uvedeném seznamu sondážních bodů zastupuje MPATTERN řetězcový literál,
506 který určuje zkoumaný jaderný modul. Pokud se modul nachází v obvyklém umístění
507 (in-tree), stačí jej určit jménem (např. "btrfs"). Jméno může obsahovat zástupné
508 symboly, jako např. "*", "[]", a "?". Pokud se modul nachází v neobvyklém
509 umístění (out-of-tree), je potřeba použít absolutní cestu. V tomto případě
510 nejsou zástupné symboly přípustné. Jméno souboru musí vyhovovat konvenčnímu
511 schématu <module_name>.ko (znaky ',' a '-' se nahradí '_').
512 .PP
513 LPATTERN je řetězcový literál, který odkazuje k umístění ve zdrojovém kódu.
514 Může obsahovat zástupné symboly "*", "[]" a "?". Skládá se ze tří částí:
515 .IP \(bu 4
516 První část je jméno funkce, tak, jak je zobrazí program
517 .I nm .
518 V této části lze použít zástupné symboly "*" a "?" k zadání více jmen.
519 .IP \(bu 4
520 Druhá část je volitelná a začíná znakem "@". Následuje cesta ke zdrojovému
521 souboru, který danou funkci obsahuje. Cesta může obsahovat zástupné znaky jako
522 např 'mm/slab*'. Pokud zadanému zástupnému symbolu nic nevyhovuje, přidá
523 překladač implicitně "*/"
524 .I před
525 daný zástupný symbol, takže v praxi stačí vyjmenovat několik posledních
526 komponent cesty ke zdrojovému souboru.
527 .IP \(bu 4
528 Nakonec třetí část je volitelná a určuje číslo řádku ve zdrojovém kódu. Číslu řádku
529 předchází jeden ze znaků ":", nebo "+". Předpokládá se, že číslo řádku je
530 absolutní pokud mu předchází ":", nebo relativní vzhledem k deklaraci funkce,
531 pokud mu předchází "+". Všechny řádky funkce lze vyjádřit jako ":*", rozsah
532 řádků od x do y použitím ":x\-y". Rozsahy a konkrétní řádky lze kombinovat,
533 např. ":x,y\-z".
534 .PP
535 Jako PATTERN lze zadat paměťovou adresu. Je to číselná konstanta odpovídající
536 adrese v tabulce symbolů objektového souboru jádra, nebo jaderného
537 modulu. Taková adresa bude ověřena proti známým limitům a za běhu relokována.
538 .PP
539 V guru režimu lze zadat absolutní adresu jádra pomocí ".absolute". Taková
540 adresa se považuje za již relokovanou jako jsou adresy v
541 .BR /proc/kallsyms ,
542 a nelze ji validovat.
543 .SS KONTEXTOVÉ PROMĚNNÉ
544
545 .PP
546 Mnohé z kontextových proměnných, jako jsou parametry funkcí, lokální proměnné,
547 globální proměnné viditelné v kompilační jednotce, můžou být viditelné v
548 obslužných rutinách sond. Jejich jména mají prefix "$". Pomocí speciální
549 syntaxe je možné do jisté míry dereferencovat ukazatele a procházet tak
550 strukturami struktur a polí. Pěkný formátovaný výpis (pretty-printing)
551 proměnných a jejich skupin je také možný. Viz
552 .BR @cast .
553 Poznamenejme, že proměnné mohou být nedostupné kvůli stránkování paměti, nebo i
554 z jiných důvodů. Viz též manuálovou stránku
555 .IR error::fault (7stap).
556 .TP
557 $var
558 se odkazuje k proměnné "var". Pokud jde o nějaký celočíselný typ, bude
559 přetypován na typ 64-bit int pro použití v systemtap skriptech. Ukazatele na
560 řetězce (char *), mohou být zkopírovány do řetězcových proměnných pomocí funkcí
561 .IR kernel_string " nebo " user_string.
562 .TP
563 @var("varname")
564 je alternativní syntaxe pro
565 .IR $varname .
566 .TP
567 @var("varname@src/file.c")
568 se odkazuje ke globální (jak 'file local', tak 'external') proměnné
569 .IR varname
570 definované v souboru
571 .IR src/file.c .
572 Za relevantní kompilační jednotku se považuje ta, která má odpovídající jméno
573 souboru a při tom nejkratší cestu. Např. máme-li
574 .IR @var("foo@bar/baz.c")
575 a kompilační jednotky
576 .IR src/sub/module/bar/baz.c
577 a
578 .IR src/bar/baz.c,
579 pak druhá z kompilačních jednotek bude považovaná za relevantní pro proměnnou
580 .IR foo .
581 .TP
582 Syntaxe $var\->field slouží k procházení strukturou ukazatelů. Tento obecný
583 dereferenční operátor lze opakovat a procházet tak více úrovněmi zanoření.
584 Poznamenejme, že operátor
585 .IR .
586 se nepoužívá pro odkaz na člena struktury. Jak pro odkaz na člena struktury, tak pro
587 dereferenci ukazatele se používá symbol
588 .IR \->
589 neboť operátor "." je vyhrazen pro spojení řetězců. Poznamenejme, že pro přímé
590 dereferencování ukazatele se doporučuje použít funkcí {kernel,user}_{char,int,...}($p).
591 Více v sekci stapfuncs(5).
592 .TP
593 $return
594 je přístupný jen v .return sondách funkcí, které mají deklarovanou návratovou
595 hodnotu. To lze detekovat pomocí @defined($return).
596 .TP
597 $var[N]
598 slouží k odkazu do pole podle daného indexu (číselný literál, nebo číselný
599 výraz).
600 .PP
601 Pro kontextové proměnné existuje řada operátorů:
602 .TP
603 $$vars
604 se expanduje na znakový řetězec následujícího formátu:
605 .SAMPLE
606 sprintf("parm1=%x ... parmN=%x var1=%x ... varN=%x",
607 parm1, ..., parmN, var1, ..., varN)
608 .ESAMPLE
609 pro každou proměnnou v rozsahu (scope) sondážního bodu. Některé proměnné mohou
610 mít hodnotu označenou jako
611 .IR =?
612 v případě, že nebyly úspěšně lokalizovány v paměťovém prostoru.
613 .TP
614 $$locals
615 se expanduje na podmnožinu $$vars pouze pro lokální proměnné.
616 .TP
617 $$parms
618 se expanduje na podmnožinu $$vars pouze pro funkční parametry.
619 .TP
620 $$return
621 je dostupný jen v .return sondách. Expanduje se na řetězec, který je
622 ekvivalentní sprintf("return=%x", $return) pokud zkoumaná funkce má návratovou
623 hodnotu (jinak bude roven prázdnému řetězci)
624 .TP
625 & $EXPR
626 expanduje se na adresu dané kontextové proměnné (pokud je adresovatelná).
627 .TP
628 @defined($EXPR)
629 Expanduje se na 1 nebo 0, pokud je daná kontextová proměnná nalezitelná. Použít
630 lze v podmínkách jako např.:
631 .SAMPLE
632 @defined($foo\->bar) ? $foo\->bar : 0
633 .ESAMPLE
634 .TP
635 $EXPR$
636 Se expanduje na řetězec se všemi členy $EXPR. Formát:
637 .SAMPLE
638 sprintf("{.a=%i, .b=%u, .c={...}, .d=[...]}",
639 $EXPR\->a, $EXPR\->b)
640 .ESAMPLE
641 .TP
642 $EXPR$$
643 Se expanduje na řetězec se všemi členy $EXPR včetně vnořených členů. Formát:
644 .SAMPLE
645 sprintf("{.a=%i, .b=%u, .c={.x=%p, .y=%c}, .d=[%i, ...]}",
646 $EXPR\->a, $EXPR\->b, $EXPR\->c\->x, $EXPR\->c\->y, $EXPR\->d[0])
647 .ESAMPLE
648
649 .SS NÁVRATOVÉ SONDY (RETURN PROBES)
650
651 .PP
652 V jaderných 'return' sondách může být zpracován jen relativně malý počet návratů
653 ".return" z funkce. Výchozí počet je malé číslo, přibližně jen několikanásobek
654 počtu fyzických CPU. Pokud danou funkci volá současně více vláken (jako např.
655 futex(), nebo read()), může být tento limit snadno překročen. V tom případě bude
656 "stap \-t" hlásit přeskočené sondy 'kretprobe'. Obejít tento problém je možno
657 použitím přípony
658 .SAMPLE
659 probe FOO.return.maxactive(NNN)
660 .ESAMPLE
661 s dostatečně velkým NNN. Případně lze na příkazové řádce zadat
662 .SAMPLE
663 stap \-DKRETACTIVE=NNNN
664 .ESAMPLE
665 čímž se tento problém obejde pro všechny ".return" sondy ve skriptu.
666 .PP
667 Pro pohodlí uživatele jsou v ".return" sondách přístupné i jiné kontextové
668 proměnné, než jen $return. Jde zejména o parametry volání funkce. V tomto
669 případě ale jde o \fBkopie\fP (snapshot) vytvořené v momentě vstupu do funkce.
670 (Lokální proměnné funkce obecně \fBnejsou\fP dostupné, neboť ty v době vytváření
671 "snapshotu" neexistovaly.) Vhodným způsobem přístupu k těmto proměnným je
672 .IR @entry($var) .
673 .PP
674 Při vstupu do funkce je možno uložit pomocné hodnoty pro pozdější využití v
675 .return sondách pomocí operátoru
676 .IR @entry(expr) .
677 Například tak lze změřit dobu běhu funkce:
678 .SAMPLE
679 probe kernel.function("do_filp_open").return {
680 println( get_timeofday_us() \- @entry(get_timeofday_us()) )
681 }
682 .ESAMPLE
683
684 .PP
685 Následující tabulka ukazuje, jak lze přistoupit ke kontextovým proměnným
686 funkčních hodnot. Ukazatel s názvem \fBaddr\fP je použitelný v
687 .IR .return
688 sondě.
689 .\" viz http://sourceware.org/ml/systemtap/2012-q1/msg00025.html
690 .TS
691 l l l.
692 \fBvstupní hodnota hodnota po výstupu z funkce\fP
693
694 $addr \fInot available\fP
695 $addr->x->y @cast(@entry($addr),"struct zz")->x->y
696 $addr[0] {kernel,user}_{char,int,...}(& $addr[0])
697 .TE
698
699
700 .SS SONDY NEZÁVISLÉ NA LADICÍCH INFORMACÍCH (DWARFLESS PROBES)
701 V případech, kdy ladicí informace nejsou k dispozici, lze do míst volání a
702 výstupu do/z funkcí vkládat sondy z rodiny 'kprobe'. Ty ovšem neumožňují
703 vyhledávání lokálních proměnných a/nebo parametrů funkcí. Podporovány jsou
704 následující konstrukce:
705 .SAMPLE
706 kprobe.function(FUNCTION)
707 kprobe.function(FUNCTION).call
708 kprobe.function(FUNCTION).return
709 kprobe.module(NAME).function(FUNCTION)
710 kprobe.module(NAME).function(FUNCTION).call
711 kprobe.module(NAME).function(FUNCTION).return
712 kprobe.statement(ADDRESS).absolute
713 .ESAMPLE
714 .PP
715 Pro jaderné funkce doporučujeme použít sondy typu
716 .B function
717 zatímco pro analýzu modulů jsou vhodné sondy
718 .B module
719 V případech, kdy je známa absolutní adresa v jádře, nebo v modulu, lze použít
720 sondy typu
721 .B statement.
722 .PP
723 Poznamenejme, že
724 .I FUNCTION
725 a
726 .I MODULE
727 .B nesmí
728 obsahovat zástupné symboly, jinak sonda nebude zaregistrována.
729 Dále pozn., že ".statement" funguje jen v guru režimu.
730
731
732 .SS UŽIVATELSKÉ PROCESY (USER-SPACE)
733 Analýza uživatelských procesů je dostupná nad jádry, která jsou konfigurována s 'utrace',
734 nebo 'uprobes' (3.5+) rozšířeními (jde o širokou sadu konfiguračních
735 voleb, které musí být zapnuty, systemtap bude jejich nedostupnost ohlašovat).
736 .PP
737 Existuje několik syntaktických podob sond pro uživatelské procesy. První forma:
738 .SAMPLE
739 process(PID).statement(ADDRESS).absolute
740 .ESAMPLE
741 je analogická
742 .IR
743 kernel.statement(ADDRESS).absolute
744 v tom, že obě používají syrové (raw), tj. neverifikované adresy a
745 nezpřístupňují kontextové proměnné. Musí být zadán PID běžícího procesu a daná
746 adresa ADDRESS by měla identifikovat validní adresu instrukce. Analyzována budou
747 všechna vlákna.
748 .PP
749 Druhá forma slouží k analyzování nesymbolických událostí obsluhovaných
750 mechanizmem 'utrace':
751 .SAMPLE
752 process(PID).begin
753 process("FULLPATH").begin
754 process.begin
755 process(PID).thread.begin
756 process("FULLPATH").thread.begin
757 process.thread.begin
758 process(PID).end
759 process("FULLPATH").end
760 process.end
761 process(PID).thread.end
762 process("FULLPATH").thread.end
763 process.thread.end
764 process(PID).syscall
765 process("FULLPATH").syscall
766 process.syscall
767 process(PID).syscall.return
768 process("FULLPATH").syscall.return
769 process.syscall.return
770 .ESAMPLE
771 .PP
772
773 .B process.begin
774 sonda je aktivována při vytvoření nového procesu daného PID, nebo FULLPATH.
775 Navíc je tato sonda volána jedenkrát z kontextu každého procesu, který
776 za běhu systemtap skriptu vznikne. To je užitečné pro udržování seznamu
777 běžících procesů.
778
779 .B process.thread.begin
780 sonda je aktivována při vytvoření nového vlákna daného PID, nebo FULLPATH.
781
782 .B process.end
783 sonda je aktivována při ukončení procesu daného PID, nebo FULLPATH.
784
785 .B process.thread.end
786 sonda je aktivována při ukončení vlákna daného PID, nebo FULLPATH.
787
788 .B process.syscall
789 sonda je aktivována když vlákno daného PID nebo FULLPATH zavolá systémové
790 volání. Číslo systémového volání je přístupné v kontextové proměnné
791 .BR $syscall
792 a prvních 6 funkčních argumentů v kontextových proměnných
793 .BR $argN
794 (ex. $arg1, $arg2, ...).
795 Sonda
796 .B process.syscall.return
797 sonda je aktivována když se vlákno daného PID nebo FULLPATH vrací ze systémového
798 volání. Číslo systémového volání je přístupné v kontextové proměnné
799 .BR $syscall
800 a návratová hodnota systémového volání pak v rámci kontextové proměnné
801 .BR $return .
802 Sonda
803 .PP
804 Pokud je sonda specifikována bez PID, nebo FULLPATH, budou analyzována vlákna
805 všech uživatelských procesů. Ovšem pokud byl stap volán s přepínačem
806 .IR \-c " nebo " \-x ,
807 pak bude brán v potaz pouze daný proces a jeho potomci. Pokud chybí jak
808 specifikace PID, tak specifikace FULLPATH, ale je dán přepínač
809 .IR \-c "
810 , bude cesta k programu doplněna na základě heuristiky. V tom případě jsou v
811 rámci argumentu
812 .IR \-c
813 přípustné jen příkazy (tj. přípustné nejsou zejména např. substituce a nesmí se
814 ani vyskytnout znaky '|&;<>(){}').).
815
816 .PP
817 Třetí typ: Je založen na statické instrumentaci, která je již zakompilovaná do
818 programů a DSO knihoven.
819 .SAMPLE
820 process("PATH").mark("LABEL")
821 process("PATH").provider("PROVIDER").mark("LABEL")
822 process(PID).mark("LABEL")
823 process(PID).provider("PROVIDER").mark("LABEL")
824 .ESAMPLE
825 .PP
826 Sonda
827 .B .mark
828 bude aktivována, jakmile vykonávání programu dosáhne místa, kde je zapřekládána
829 speciální značka pomocí makra STAP_PROBE1(PROVIDER,LABEL,arg1). Toto makro je
830 definováno v
831 .BR sys/sdt.h .
832 PROVIDER je volitelný identifikátor aplikace, LABEL identifikátor značky, a
833 arg1 je celočíselný argument. Pro sondy s jedním argumentem se použije makro
834 STAP_PROBE1, pro sondy se dvěma argumenty makro STAP_PROBE2 a tak dále. Proměnné
835 arg1, arg2, ... argN jsou pak dostupné v kontextu sondy.
836
837 Alternativou k použití makra STAP_PROBE je použít dtrace skript k vytvoření
838 uživatelských maker. V kontextu sondy jsou též dostupné proměnné $$name a
839 $$provider. V
840 .B sys/sdt.h
841 se definuje makro DTRACE_PROBE* jako přezdívka pro STAP_PROBE*.
842
843 .PP
844 Poslední typ: V uživatelských programech jsou dostupné všechny varianty
845 DWARF sond. Jsou analogické k jaderným DWARF sondám, nebo DWARF sondám pro
846 jaderné moduly popsaným výše. Poskytují přístup ke kontextovým proměnným pro
847 parametry funkcí, lokální proměnné atd:
848 .SAMPLE
849 process("PATH").function("NAME")
850 process("PATH").statement("*@FILE.c:123")
851 process("PATH").plt("NAME")
852 process("PATH").library("PATH").plt("NAME")
853 process("PATH").library("PATH").function("NAME")
854 process("PATH").library("PATH").statement("*@FILE.c:123")
855 process("PATH").function("*").return
856 process("PATH").function("myfun").label("foo")
857 process("PATH").function("foo").callee("bar")
858 process("PATH").plt("NAME").return
859 process(PID).function("NAME")
860 process(PID).statement("*@FILE.c:123")
861 process(PID).plt("NAME")
862 .ESAMPLE
863
864 .PP
865 Poznamenejme, že pro všechny sondy pro uživatelské procesy platí, že
866 .I PATH
867 se odkazuje k spustitelnému souboru, jehož absolutní umístění se dohledává
868 podobně jako to dělají shelly, tj. relativně k aktuálnímu adresáři pokud
869 obsahují lomítko "/", jinak v
870 .BR $PATH .
871 Pokud se PATH odkazuje na skript, bude předmětem analýzy příslušný interpreter
872 tak, jak je definován v prvním řádku skriptu za sekvencí #! (shebang).
873
874 .PP
875 Pokud je PATH parametrem komponenty '.process' a odkazuje se na sdílenou
876 DSO knihovnu, pak analyzovány budou všechny procesy, které tuto knihovnu
877 využívají. Pokud je PATH parametrem komponenty '.library', pak analyzován bude
878 pouze daný proces. Poznamenejme, že PATH v rámci komponenty '.library' se vždy
879 vztahuje na knihovny, které lze z daného spustitelného souboru zjistit staticky.
880 Nicméně vždy je možné uvést absolutní cestu k libovolné knihovně explicitně.
881
882 .PP
883 Sonda .plt bude umístěns do 'program linkage' tabulky odpovídající zbytku
884 definice sondážního bodu. Při tom .plt je zkratkou pro .plt("*"). Jméno
885 symbolu je dostupné v kontextové proměnné $$name, parametry funkcí dostupné
886 nejsou, protože PLT sondy se zpracovávají bez ladicích informací. Sonda
887 .plt.return bude aktivní v okamžiku, který nastane brzy \fBpo\fR návratu z dané
888 funkce.
889
890 .PP
891 Řetězec PATH může obsahovat zástupné symboly, jako tomu bylo v případě MPATTERN.
892 V tomto případě nebude brán zřetel na proměnnou
893 .BR $PATH .
894
895 .PP
896 Pokud je systemtap vyvolán s jedním z přepínačů
897 .IR \-c " nebo " \-x
898 pak bude analýza omezena na cílový proces a jeho potomky.
899
900 .SS JAVA
901 Podpora pro instrumentaci java metod je založena na nástroji Byteman, což je
902 software sloužící k instrumentaci javy vyvíjený v rámci JBoss projektu.
903 Systemtap tak může detekovat vykonání java metody, nebo vykonání daného řádku
904 java programu.
905 .PP
906 Instrumentace javy je založená na generování byteman skriptu a následném volání
907 .IR bminstall .
908 .PP
909 V současnosti je instrumentace javy prototypem s významnými omezeními:
910 Instrumentace javy nefunguje napříč uživateli. Systemtap skript musí být
911 spuštěn stejným uživatelem, jako instrumentovaný proces. Tedy zejména, a to je
912 ne neobvyklé, systemtap skript spuštěný rootem nemůže analyzovat java program
913 jiného uživatele.
914
915 .PP
916 První typ java sond se odkazuje k java procesům jménem:
917 .SAMPLE
918 java("PNAME").class("CLASSNAME").method("PATTERN")
919 java("PNAME").class("CLASSNAME").method("PATTERN").return
920 .ESAMPLE
921 Argument PNAME musí být již existující jvm PID a musí být viditelný ve výpisu
922 programu jps.
923
924 .PP
925 Parametr PATTERN určuje signaturu java metody, která se má instrumentovat.
926 Signatura musí sestávat z přesného jména java metody následovaného
927 uzávorkovaným seznamem typů argumentů. Příklad: "myMethod(int,double,Foo)".
928 Zástupné znaky se zde nepodporují.
929
930 .PP
931 Sondu lze vložit na konkrétní řádek připojením dvojtečky a čísla řádku jako
932 obvykle. Příklad: "myMethod(int,double,Foo):245".
933
934 .PP
935 Parametr CLASSNAME identifikuje Java třídu, ke které metoda náleží, a to jak s,
936 tak bez uvedení názvu balíčku (package). Za normálních okolností bude sonda
937 aktivní také na potomcích dané třídy, kteří ponechávají danou metodu
938 nepředefinovanou. Nicméně, CLASSNAME přijímá volitelný prefix "^" jako např:
939 .IR ^org.my.MyClass,
940 který značí, že sonda by měla být též aktivní na všech potomcích dané třídy,
941 včetně těch, kteří danou metodu předefinovali. Například všechny metody foo(int)
942 v programu org.my.MyApp mohou být instrumentovány takto:
943 .SAMPLE
944 java("org.my.MyApp").class("^java.lang.Object").method("foo(int)")
945 .ESAMPLE
946 .PP
947 Druhý typ sond funguje analogicky, ovšem odkazuje se k java procesu
948 prostřednictvím PID:
949 .SAMPLE
950 java(PID).class("CLASSNAME").method("PATTERN")
951 java(PID).class("CLASSNAME").method("PATTERN").return
952 .ESAMPLE
953 (PID již běžícího procesu lze získat pomocí
954 .IR jps (1) .
955 )
956 .PP
957 Kontextové proměnné definované v java sondách zahrnují
958 .IR $arg1
959 až
960 .IR $arg10
961 (pro až 10 prvních parametrů metody), jakožto ukazatele na řetězce,
962 které lze podle potřeby předhodit ke zpracování funkci toString().
963
964 Proměnné
965 .IR arg1
966 až
967 .IR arg10
968 zpřístupňují zmíněné argumenty metody přímo jakožto řetězce získané prostřednictvím
969 .IR user_string_warn() .
970
971 .PP
972 Ve starších verzích systemtapu (3.1 a níže) obsahovaly
973 .IR $arg1
974 až
975 .IR $arg10
976 buďto celá čísla, nebo ukazatele na řetězce, v závislosti na typu
977 odpovídajících objektů. Toto historické chování lze použít v režimu
978 .I stap --compatible=3.0 .
979
980
981 .SS PROCFS
982
983 Následující sondy umožňují vytvářet / číst "soubory" v /proc/systemtap/MODNAME.
984 Při tom je možné definovat umask. výchozí hodnoty jsou 0400 pro čtecí sondy a
985 0200 pro zapisovací sondy. Pokud jsou na jednom souboru používány sondy jak
986 pro čtení, tak pro zápis, pak výchozí oprávnění bude 0600.
987
988 Sonda procfs.umask(0040).read způsobí nastavení oprávnění 0404 na souboru.
989 .RI ( MODNAME
990 je jméno systemtap modulu). Souborový (pseudo-) systém
991 .I proc
992 se používá jako uživatelské rozhraní pro datové struktury jádra. Překladač
993 podporuje několik variant procfs sond:
994
995 .SAMPLE
996 procfs("PATH").read
997 procfs("PATH").umask(UMASK).read
998 procfs("PATH").read.maxsize(MAXSIZE)
999 procfs("PATH").umask(UMASK).maxsize(MAXSIZE)
1000 procfs("PATH").write
1001 procfs("PATH").umask(UMASK).write
1002 procfs.read
1003 procfs.umask(UMASK).read
1004 procfs.read.maxsize(MAXSIZE)
1005 procfs.umask(UMASK).read.maxsize(MAXSIZE)
1006 procfs.write
1007 procfs.umask(UMASK).write
1008 .ESAMPLE
1009
1010 .I PATH
1011 je cesta relativní vzhledem k /proc/systemtap/MODNAME
1012 Pokud není
1013 .I PATH
1014 určeno (tak jako u posledních dvou variant výše), pak
1015 .I PATH
1016 nabývá výchozí hodnoty "command". Název souboru "__stdin" se vnitřně používá v "input"
1017 sondách a neměl by se používat v roli
1018 .I PATH
1019 procfs sond; viz sekce INPUT níže.
1020 .PP
1021 Když uživatel čte /proc/systemtap/MODNAME/PATH, aktivuje se
1022 procfs
1023 .I read
1024 proba. Řetězcová data ke čtení se přiřadí proměnné
1025 .IR $value .
1026 Příklad:
1027
1028 .SAMPLE
1029 procfs("PATH").read { $value = "100\\n" }
1030 .ESAMPLE
1031 .PP
1032 Když uživatel zapisuje do /proc/systemtap/MODNAME/PATH, aktivuje se odpovídající
1033 .I write
1034 sonda. Data zapsaná uživatelem jsou pak dostupná v proměnné
1035 .IR $value .
1036 Příklad:
1037
1038 .SAMPLE
1039 procfs("PATH").write { printf("user wrote: %s", $value) }
1040 .ESAMPLE
1041 .PP
1042 .I MAXSIZE
1043 Maximální velikost procfs čtecího bufferu a procfs výstupu. Pokud
1044 .I MAXSIZE
1045 není nastavena, velikost čtecího bufferu se položí rovna
1046 .I STP_PROCFS_BUFSIZE
1047 (s výchozí hodnotou
1048 .IR MAXSTRINGLEN ,
1049 tj. maximální délka řetězce).
1050 V případě, kdy je třeba nastavit velikost čtecích bufferů pro více než jeden
1051 procfs soubor, může pomoci
1052 .I STP_PROCFS_BUFSIZE .
1053
1054 Zde je příklad použití
1055 .IR MAXSIZE :
1056
1057 .SAMPLE
1058 procfs.read.maxsize(1024) {
1059 $value = "dlouhý řetězec..."
1060 $value .= "jiný dlouhý řetězec..."
1061 $value .= "jiný dlouhý řetězec..."
1062 $value .= "jiný dlouhý řetězec..."
1063 }
1064 .ESAMPLE
1065
1066 .SS INPUT
1067
1068 Tyto sondy zpřístupňují standardní vstup skriptu v době jeho běhu.
1069 Překladač podporuje dvě varianty této rodiny sond:
1070
1071 .SAMPLE
1072 input.char
1073 input.line
1074 .ESAMPLE
1075
1076 .BR input.char
1077 se aktivuje po každém přečtení znaku ze standardního vstupu. Dotyčný znak je
1078 pak dostupný prostřednictvím proměnné
1079 .IR char .
1080 Nehraje zde roli žádná vyrovnávací paměť.
1081
1082 .BR input.line
1083 Znaky načtené ze standardního vstupu se ukládají do vyrovnávací paměti až do
1084 okamžiku načtení znaku nového řádku. Po načtení celého řádku se tento včetně
1085 ukončovacího znaku stane dostupným prostřednictvím proměnné
1086 .IR line .
1087 Při tom maximální délka řádku je MAXSTRINGLEN. Znaky přesahující MAXSTRINGLEN
1088 se do
1089 .IR line
1090 nedostanou.
1091
1092 .PP
1093 Tyto input sondy jsou ve skutečnosti přezdívkami pro
1094 .BR procfs("__stdin").write .
1095 Pokud uživatelský skript obsahuje procfs sondu, neměl by využívat "__stdin" jako
1096 argument "procfs" sond.
1097 Sondy "input" nefungují při použití -F a --remote voleb.
1098
1099 .SS SONDY 'NETFILTER HOOKS'
1100
1101 Sondy 'netfilter hooks', (dále jen netfilter sondy) umožní sledování
1102 síťových paketů pomocí jaderného mechanizmu 'netfilter'. Netfilter sonda
1103 odpovídá funkci 'netfilter hook' s využitím originálního API. Pravděpodobně
1104 pohodlnější, než používání "syrových" sondážních bodů překladače,
1105 je použít příslušné tapset funkce
1106 .IR tapset::netfilter (3stap),
1107 které poskytují praktickou obálku.
1108
1109 .PP
1110 Překladač podporuje několik variant netfilter sond:
1111
1112 .SAMPLE
1113 netfilter.hook("HOOKNAME").pf("PROTOCOL_F")
1114 netfilter.pf("PROTOCOL_F").hook("HOOKNAME")
1115 netfilter.hook("HOOKNAME").pf("PROTOCOL_F").priority("PRIORITY")
1116 netfilter.pf("PROTOCOL_F").hook("HOOKNAME").priority("PRIORITY")
1117 .ESAMPLE
1118
1119 .PP
1120 .I PROTOCOL_F
1121 je rodina protokolů které mají být využity k poslouchání. V současností jsou k
1122 dispozici následující možnosti:
1123
1124 .I NFPROTO_IPV4,
1125 .I NFPROTO_IPV6,
1126 .I NFPROTO_ARP,
1127 nebo
1128 .I NFPROTO_BRIDGE.
1129
1130 .PP
1131 .I HOOKNAME
1132 je bod ('hook') v rámci daného protokolu, ve kterém se zachytí paket. Seznam
1133 dostupných typů příslušných sondážních bodů nalezne čtenář v hlavičkových
1134 souborech <linux/netfilter_ipv4.h>, <linux/netfilter_ipv6.h>,
1135 <linux/netfilter_arp.h> a <linux/netfilter_bridge.h>. Například použitelné
1136 sondážní body pro
1137 .I NFPROTO_IPV4
1138 jsou
1139 .I NF_INET_PRE_ROUTING,
1140 .I NF_INET_LOCAL_IN,
1141 .I NF_INET_FORWARD,
1142 .I NF_INET_LOCAL_OUT,
1143 a
1144 .I NF_INET_POST_ROUTING.
1145
1146 .PP
1147 .I PRIORITY
1148 Je celočíselná priorita určující pořadí aktivace netfilter sond vzhledem k
1149 ostatním 'netfilter hook' funkcím pro daný paket. Na daném paketu se nejdříve
1150 vykonají 'hetfilter hook' funkce s nejnižší prioritou, poté funkce s vyšší
1151 prioritou. Pokud
1152 .I PRIORITY
1153 není specifikovaná (jako je tomu v prvních dvou příkladech výše), bude efektivně
1154 .I PRIORITY
1155 rovna nule.
1156
1157 Existuje řada pojmenovaných priorit tvaru
1158 .I NF_IP_PRI_*
1159 a
1160 .I NF_IP6_PRI_* ,
1161 které jsou definovány v hlavičkových souborech jádra <linux/netfilter_ipv4.h> a
1162 <linux/netfilter_ipv6.h>. Tato makra mohou být použita v systemtap skriptech.
1163 Výjimkou jsou sondážní body pro
1164 .I NFPROTO_ARP
1165 a
1166 .I NFPROTO_BRIDGE
1167 pro které momentálně neexistují pojmenované priority. Přijatelné způsoby
1168 nastavení priorit:
1169
1170 .SAMPLE
1171 priority("255")
1172 priority("NF_IP_PRI_SELINUX_LAST")
1173 .ESAMPLE
1174
1175 Skript v guru režimu může určit libovolný identifikátor nebo číslo jako
1176 parametr 'hook', 'pf' a 'priority', což je vhodné používat opatrně, neboť
1177 parametr se vkládá do vygenerovaného C kódu doslovně.
1178
1179 V rámci netfilter sond existují následující kontextové proměnné:
1180 .TP
1181 .IR $hooknum
1182 Číslo identifikující 'netfilter hook'.
1183 .TP
1184 .IR $skb
1185 adresa struktury sk_buff, která reprezentuje paket. Viz hlavičkový soubor
1186 <linux/skbuff.h> a manuálovou stránku
1187 .IR tapset::netfilter (3stap)
1188 pro podrobnější informace.
1189
1190 .TP
1191 .IR $in
1192 Adresa struktury net_device, která reprezentuje síťové zařízení ze kterého paket
1193 přišel. Může být 0 pokud zařízení není známo nebo definováno.
1194
1195 .TP
1196 .IR $out
1197 Adresa struktury net_device reprezentující síťové zařízení na které má být paket
1198 odeslán. Může být 0 pokud zařízení není známo nebo definováno.
1199
1200 .TP
1201 .IR $verdict
1202 Je dostupný jen v guru režimu. Nastavením této hodnoty (viz <linux/netfilter.h>)
1203 se rozhodne o dalším způsobu zpracování paketu v paketovém filtru. Například
1204 následující guru skript způsobí zahazování všech IPv6 paketů:
1205
1206 .SAMPLE
1207 probe netfilter.pf("NFPROTO_IPV6").hook("NF_IP6_PRE_ROUTING") {
1208 $verdict = 0 /* nf_drop */
1209 }
1210 .ESAMPLE
1211
1212 Pro pohodlí uživatele poskytují netfilter sondy definované v
1213 .IR tapset::netfilter (3stap)
1214 hodnoty pro proměnnou 'verdict' jako lokální proměnné. Například
1215 proměnná 'nf_drop' obsahuje hodnotu NF_DROP.
1216
1217
1218 .SS SONDÁŽNÍ BODY TYPU 'TRACEPOINT'
1219
1220 Tato rodina sondážních bodů je založena na staticky zakompilovaných značkách
1221 typu 'tracepoint' (dále jen tracepoint body) vložených do jádra, nebo jaderného
1222 modulu. Systemtap umí tyto značky detekovat pomocí sondážních bodů typu 'tracepoint',
1223 dále jen 'tracepoint sondy'. Tracepoint sondy jsou
1224 spolehlivější, než sondy založené na DWARF ladicích informacích. Pro funkčnost
1225 tracepoint sond není nutná přítomnost ladicích informací. Další výhodou
1226 tracepoint sond jsou silněji typované parametry ve srovnání se značkami
1227 (markers).
1228
1229 Příklady tracepoint sond:
1230 .BR kernel.trace("name") .
1231 Řetězcový literál "name" může obsahovat zástupné symboly. Pro omezení sondy na
1232 konkrétní subsystém (např. sched, ext3, atd...), lze využít následující syntaxe:
1233 .BR kernel.trace("subsystém:jméno") .
1234
1235 Obslužný kód pro tracepoint sondy může číst volitelné parametry, které autoři
1236 tracepoint bodů připravili. Například sondážní bod
1237 .BR kernel.trace("sched:sched_switch")
1238 poskytuje parametry
1239 .BR $prev " a " $next .
1240 Pokud je parametrem ukazatel, lze jej dereferencovat pomocí stejné syntaxe jako
1241 je tomu u DWARF sond. Hodnoty parametrů tracepoint sond nelze modifikovat. V
1242 guru režimu lze ovšem modifikovat proměnné dereferencované pomocí parametrů
1243 tracepoint sond.
1244
1245 Jméno subsystému a jméno tracepoint bodu je přístupné prostřednictvím proměnných
1246 .BR $$system " resp. " $$name
1247 a řetězcová reprezentace párů jméno=hodnota je pak dostupná prostřednictvím
1248 .BR $$vars " nebo " $$parms .
1249
1250 .SS JADERNÉ ZNAČKY (KERNEL MARKERS) (ZASTARALÉ)
1251
1252 Tato rodina sondážních bodů je postavena na poněkud zastaralém mechanizmu
1253 statických značek, které se vyskytují ve starších jádrech a jaderných modulech.
1254 Jde o makra STAP_MARK, které do jádra vložili vývojáři aby usnadnili
1255 instrumentaci jádra a učinili ji spolehlivou. Proto DWARF ladicí informace
1256 nejsou pro tento typ instrumentace potřeba.
1257
1258 Sondážní bod pro jadernou značku začíná
1259 .BR kernel .
1260 další částí je jméno značky samotné:
1261 .BR mark("name") .
1262 Řetězec vyjadřující jméno značky může obsahovat obvyklé zástupné symboly a
1263 porovnává se proti vývojářem zavedenému jménu značky. Volitelně lze uvést
1264 formát:
1265 .BR format("format") ,
1266 čímž se odliší značky se stejným jménem, ale odlišným označením pro formát.
1267
1268 Obslužný kód pro tento typ sond může číst parametry, které mohou být v místě
1269 značky dostupné jako:
1270 .BR $arg1 " až " $argNN ,
1271 Kde NN je počet parametrů podporovaných makrem. Parametry mohou být řetězcového
1272 a celočíselného typu.
1273
1274 Hodnota atributu 'format' značky je dostupná v proměnné
1275 .BR $format .
1276 Hodnota atributu 'name' v
1277 .BR $name .
1278
1279 .SS HARDWAROVÉ BODY ZASTAVENÍ (HARDWARE BREAKPOINTS)
1280 Tato skupina sond slouží k nastavení hardwarových bodů zastavení pro daný
1281 globální symbol jádra. Příslušné sondy sestávají ze tří komponent:
1282
1283 1.
1284 .BR virtuální
1285 adresa" / "jméno zkoumaného symbolu jádra se předává jako argument této třídě
1286 sond. Podporovány jsou pouze sondy pro proměnné v datovém segmentu. Analýzu
1287 lokálních proměnných nelze provést.
1288
1289 2. Způsob přístupu :
1290 a. sonda
1291 .I .write
1292 se aktivuje, jakmile dojde na zadané adrese / symbolu k zápisu.
1293 b. sonda
1294 .I rw
1295 se aktivuje, jakmile dojde na zadané adrese / symbolu ke čtení.
1296
1297 3.
1298 .BR .length
1299 (volitelné)
1300 uživatel má možnost vymezit rozsah adres pro analýzu pomocí
1301 "length". Uživatelem určená hodnota se zaokrouhlí na
1302 nejbližší hardwarem podporovanou hodnotu. Pokud se hodnota 'length' nezadá,
1303 položí ji překladač rovnu jedné. Pozn., že 'length' nelze použít v kombinaci se
1304 symbolickými jmény.
1305
1306 Podporovány jsou následující syntaktické konstrukce.
1307 .SAMPLE
1308 probe kernel.data(ADDRESS).write
1309 probe kernel.data(ADDRESS).rw
1310 probe kernel.data(ADDRESS).length(LEN).write
1311 probe kernel.data(ADDRESS).length(LEN).rw
1312 probe kernel.data("SYMBOL_NAME").write
1313 probe kernel.data("SYMBOL_NAME").rw
1314 .ESAMPLE
1315
1316 Tato skupina sond využívá ladicí registry procesoru, což je vzácný zdroj.
1317 Architektura x86_64 nabízí čtyři ladicí registry, powerpc jen jeden. Pokud se
1318 uživatel pokusí využít více ladicích registrů, než kolik jich má k dispozici,
1319 překlad skončí chybou ve fázi 2.
1320
1321 .SS PERF SONDY
1322
1323 Tato skupina sond je rozhraním pro infrastrukturu jádra "perf event", která
1324 pracuje s hardwarovými počitadly (hardware performance counters). Událost, se
1325 kterou se má proba svázat, se specifikuje pomocí atributů "type" a "config"
1326 struktury
1327 .IR perf_event_attr .
1328 Vzorkovací frekvence se určí pomocí atributů "sample_period" nebo "sample_freq".
1329
1330 Tento typ sond používá následující syntaxi:
1331 .SAMPLE
1332 probe perf.type(NN).config(MM).sample(XX)
1333 probe perf.type(NN).config(MM).hz(XX)
1334 probe perf.type(NN).config(MM)
1335 probe perf.type(NN).config(MM).process("PROC")
1336 probe perf.type(NN).config(MM).counter("COUNTER")
1337 probe perf.type(NN).config(MM).process("PROC").counter("COUNTER")
1338 .ESAMPLE
1339
1340 Obslužná rutina sondy se při použití '.sample' zavolá jednou za XX inkrementů
1341 daného počitadla, nebo, pokud se použije .hz, po uplynutí periody dané
1342 frekvence. Bez specifikace položí překladač XX rovno 1000000. Platný rozsah je
1343 specifikován v popisu systémového volání
1344 .IR perf_event_open (2)
1345 a / nebo v hlavičkovém souboru
1346 .IR linux/perf_event.h .
1347
1348 Neplatné nastavení skončí chybou překladu. Kontrola platnosti zadaných hodnot se
1349 provádí v rámci jádra. Za normálních okolností je .perf sonda platná pro celý
1350 systém. Pokud se určí .process, pak jen pro daný uživatelský proces. Pokud se
1351 vynechá jméno procesu, pokusí se ho překladač odvodit z \-c. Událost lze číst
1352 použitím '.counter'. Obslužná rutina perf sondy se pro .counter nezavolá,
1353 ale počitadlo lze číst pomocí následující syntaxe:
1354 .TP
1355 process("PROC").statement("func@file") {stat <<< @perf("NAME")}
1356
1357 .SS PYTHON
1358 S použitím speciálního python modulu je možné analyzovat python 2 a python 3 funkce.
1359 K tomu je potřeba mít nainstalované ladicí informace pro příslušný python.
1360 Zmíněný modul lze použít takto:
1361 .SAMPLE
1362 stap foo.stp -c "python -m HelperSDT foo.py"
1363 .ESAMPLE
1364 Příslušné sondy potom vypadají takto:
1365 .SAMPLE
1366 python2.module("MPATTERN").function("PATTERN")
1367 python2.module("MPATTERN").function("PATTERN").call
1368 python2.module("MPATTERN").function("PATTERN").return
1369 python3.module("MPATTERN").function("PATTERN")
1370 python3.module("MPATTERN").function("PATTERN").call
1371 python3.module("MPATTERN").function("PATTERN").return
1372 .ESAMPLE
1373 Výše zmíněná ukázka obsahuje následující modifikátory:
1374 .RS
1375 .TP
1376 \fB.function\fR
1377 Umístí sondu na začátek funkce určené jménem, pokud není prostřednictvím
1378 PATTERN určeno jinak. Funkční parametry jsou dostupné jako kontextové
1379 proměnné.
1380 .TP
1381 \fB.call\fR
1382 Umístí sondu na začátek funkce určené jménem. Funkční parametry jsou
1383 dostupné jako kontextové proměnné.
1384 .TP
1385 \fB.return\fR
1386 Umístí sondu těsně \fBpřed\fR návrat z funkce určené jménem. Parametry
1387 funkce, jakož i lokální, či globální proměnné jsou dostupné
1388 prostřednictvím kontextových proměnných.
1389 .RE
1390 .PP
1391 PATTERN představuje řetězcový literál, který určuje pozici v python
1392 programu. Skládá se ze tří částí:
1393 .IP \(bu 4
1394 První částí je jméno funkce (například "foo"), nebo metody (například
1395 "bar.baz"). V této části lze používat také zástupné symboly "*" a "?".
1396 .IP \(bu 4
1397 Druhá část je volitelná a začíná znakem "@". Za ní následuje cesta
1398 k souboru, který obsahuje danou funkci/metodu. Zde lze taktéž použít
1399 zástupné symboly "*" a "?". Pro vyhledávání ze vezme v potaz "python
1400 path".
1401 .IP \(bu 4
1402 Poslední, třetí volitelnou částí, je speecifikace čísla řádku ve
1403 zdrojovém souboru. Číslo řádku se zapisuje za dvojtečku ":", nebo
1404 plus "+". V případě dvojtečky se číslo řádku interpretuje jako
1405 absolutní číslo řádku, v případě plusu jako relativní vzhledem k
1406 deklaraci funkce. Všechny řádky dané funkce lze označit zápisem ":*".
1407 Rozsah řádků se zapíše jako ":x\-y", či ":x,y\-z".
1408 .PP
1409 MPATTERN zastupuje název python modulu, nebo skriptu, který se na
1410 python modul odkazuje. I zde lze použít zástupné znaky "*" a "?".
1411 Daný název souboru se hledá v rámci "python path".
1412
1413
1414 .SH PŘÍKLADY
1415 .PP
1416 Zde uvádíme několik konkrétních příkladů sond.
1417 .TP
1418 begin, end, end
1419 odkazuje se k začátku a k normálnímu ukončení sezení. V tomto případě se
1420 obslužná rutina provede jednou při začátku sezení, a dvakrát při jeho normálním
1421 ukončení.
1422 .TP
1423 timer.jiffies(1000).randomize(200)
1424 sonda se aktivuje periodicky každých 1000 +/\- 200 jiffies.
1425 .TP
1426 kernel.function("*init*"), kernel.function("*exit*")
1427 odkazuje se ke všem jaderným funkcím, jejichž jméno obsahuje podřetězec "init",
1428 nebo "exit".
1429 .TP
1430 kernel.function("*@kernel/time.c:240")
1431 odkazuje se k libovolné funkci z "kernel/time.c", kde část jejího těla leží na
1432 řádku 240.
1433 .BR
1434 Poznamenejme, že v tomto případě
1435 .BR nejde
1436 o sondu vloženou na daný řádek. Pro vložení sondy na daný řádek použijte
1437 .IR
1438 kernel.statement .
1439 .TP
1440 kernel.trace("sched_*")
1441 odkazuje se ke všem 'tracepoint' bodům s prefixem "sched_", tj. souvisejícím s
1442 časovačem.
1443 .TP
1444 kernel.mark("getuid")
1445 odkazuje se k zastaralému jadernému makru STAP_MARK(getuid, ...).
1446 .TP
1447 module("usb*").function("*sync*").return
1448 odkazuje se k bodu návratu ze všech funkcí, které obsahují "sync" ve svém jméně
1449 a nachází se v některém z USB modulů.
1450 .TP
1451 kernel.statement(0xc0044852)
1452 odkazuje se k prvnímu bajtu příkazu, jehož přeložené instrukce leží na dané
1453 adrese v jádře.
1454 .TP
1455 kernel.statement("*@kernel/time.c:296")
1456 odkazuje se k příkazu na řádku 290 v souboru "kernel/time.c".
1457 .TP
1458 kernel.statement("bio_init@fs/bio.c+3")
1459 odkazuje se k příkazu na řádku bio_init+3 v souboru "fs/bio.c".
1460 .TP
1461 kernel.data("pid_max").write
1462 odkazuje se k hardwarovému breakpointu typu "write" nastavenému na pid_max.
1463 .TP
1464 syscall.*.return
1465 odkazuje se ke skupině přezdívek sond s libovolným jménem druhé komponenty.
1466
1467 .SH VIZ TÉŽ
1468 .nh
1469 .nf
1470 .IR stap (1),
1471 .IR probe::* (3stap),
1472 .IR tapset::* (3stap)
1473
1474 .\" Local Variables:
1475 .\" mode: nroff
1476 .\" End: