| 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: |