Provided by: systemtap-doc_5.1-5_amd64 
JMÉNO
stap - překladač a řadič systemtap skriptů
POUŽITÍ
stap [ VOLBY ] JMÉNO_SOUBORU [ ARGUMENTY ]
stap [ VOLBY ] - [ ARGUMENTY ]
stap [ VOLBY ] -e SKRIPT [ ARGUMENTY ]
stap [ VOLBY ] -l PROBE [ ARGUMENTY ]
stap [ VOLBY ] -L PROBE [ ARGUMENTY ]
stap [ VOLBY ] --dump-probe-types
stap [ VOLBY ] --dump-probe-aliases
stap [ VOLBY ] --dump-functions
POPIS
Program stap je hlavním uživatelským rozhraním nástroje systemtap. Přijímá požadavky na sondování systému
(probing) zapsané v jednoduchém skriptovacím jazyce, překládá je do jazyka C, výsledný kód zkompiluje a
vytvoří jaderný modul, který následně zavede do běžícího linuxového jádra nebo dyninst instrumentačního
nástroje, aby prováděl požadovanou analýzu zkoumaného systému. Skript může být čten ze souboru
(JMÉNO_SOUBORU), ze standardního vstupu (v tom případě použijte "-" namísto JMÉNO_SOUBORU), z příkazové
řádky (prostřednictvím přepínače -e SKRIPT, případně -E SKRIPT). Program běží dokud není přerušen
uživatelem, nebo dokud skript nezavolá exit(), nebo dokud nedojde k nastřádání dostatečného množství tzv.
měkkých chyb (soft errors).
Jazyk, který je popsán níže v sekci SKRIPTOVACÍ JAZYK, je striktně typovaný, imperativní, bez
explicitních deklarací, procedurální, vhodný k prototypování a inspirovaný awk a C. Umožňuje spojit místo
ve zdrojovém kódu linuxového jádra, nebo uživatelské aplikace, případně systémovou událost s obslužnými
rutinami, což jsou bloky kódu vykonávané synchronně. Koncepčně to připomíná skriptování v gdb.
PŘEHLED DOKUMENTACE
Pro SystemTap existuje množství vzdělávacích, dokumentačních a referenčních materiálů jak v online
podobě, tak i v rámci distribučních balíčků. Online dokumentace se nachází na projektovém webu
https://sourceware.org/systemtap/
┌───────────────────────────┬────────────────────────────────────────────────────────┐
│ man stránky │ │
├───────────────────────────┼────────────────────────────────────────────────────────┤
│ stap (tato stránka) │ syntaxe jazyka, koncepty, funkce, volby │
├───────────────────────────┼────────────────────────────────────────────────────────┤
│ stapprobes │ sondážní body a jejich kontextové proměnné │
├───────────────────────────┼────────────────────────────────────────────────────────┤
│ stapref │ rychlá reference pro syntaxi jazyka │
├───────────────────────────┼────────────────────────────────────────────────────────┤
│ stappaths │ seznam důležitých umístění včetně knih a odkazů │
├───────────────────────────┼────────────────────────────────────────────────────────┤
│ stap-prep │ instalátor závislostí jako např. ladicích informací │
│ │ jádra │
├───────────────────────────┼────────────────────────────────────────────────────────┤
│ tapset::* │ vygenerovaný seznam tapsetů │
├───────────────────────────┼────────────────────────────────────────────────────────┤
│ probe::* │ vygenerovaný seznam tapsetových přezdívek │
├───────────────────────────┼────────────────────────────────────────────────────────┤
│ function::* │ vygenerovaný seznam tapsetových funkcí │
├───────────────────────────┼────────────────────────────────────────────────────────┤
│ macro::* │ vygenerovaný seznam tapsetových maker │
├───────────────────────────┼────────────────────────────────────────────────────────┤
│ stapvars │ vybrané globální proměnné definované v tapsetech │
├───────────────────────────┼────────────────────────────────────────────────────────┤
│ staprun, stapdyn, stapbpf │ programy pro spuštění zkompilovaných systemtap skriptů │
├───────────────────────────┼────────────────────────────────────────────────────────┤
│ systemtap │ systémová služba, analýza startu systému │
├───────────────────────────┼────────────────────────────────────────────────────────┤
│ stap-server │ kompilační server │
├───────────────────────────┼────────────────────────────────────────────────────────┤
│ stapex │ několik velmi jednoduchých příkladů │
├───────────────────────────┼────────────────────────────────────────────────────────┤
│ knihy │ │
├───────────────────────────┼────────────────────────────────────────────────────────┤
│ Beginner's Guide │ učebnice základů s praktickými ukázkami │
├───────────────────────────┼────────────────────────────────────────────────────────┤
│ Tutorial │ hutný úvod, cvičení │
├───────────────────────────┼────────────────────────────────────────────────────────┤
│ Language Reference │ podrobný manuál skriptovacího jazyka │
├───────────────────────────┼────────────────────────────────────────────────────────┤
│ Tapset Reference │ man stránky tapsetů v podobě knihy │
├───────────────────────────┼────────────────────────────────────────────────────────┤
│ odkazy │ │
├───────────────────────────┼────────────────────────────────────────────────────────┤
│ example scripts │ množství nástrojů pro správu systému, ukázkových │
│ │ skriptů a výukových hraček │
└───────────────────────────┴────────────────────────────────────────────────────────┘
VOLBY
Příkaz stap akceptuje následující volby. Jakákoliv jiná volba vypíše seznam podporovaných voleb. Volby
lze uvést na příkazové řádce, jak je obvyklé. Pokud existuje $SYSTEMTAP_DIR/rc, mohou být volby načteny
odtud a interpretovány nejdříve. Pokud není $SYSTEMTAP_DIR nastavena, použije se $HOME/.systemtap jako
výchozí.
V některých případech může výchozí hodnota volby záviset na konkrétní konfiguraci systému a proto zde ne‐
ní přímo uvedena. V takovém případě může pomoci "stap --help".
- Načte skript ze standardního vstupu namísto ze souboru JMÉNO_SOUBORU, pokud ovšem není dáno -e
SKRIPT.
-h --help
Zobrazí nápovědu.
-V --version
Zobrazí verzi.
-p NUM Zastaví po dokončení procesní fáze NUM. Procesní fáze jsou očíslované 1-5 (parse, elaborate,
translate, compile, run). Viz sekce ZPRACOVÁNÍ .
-v Zvýší upovídanost pro všechny procesní fáze. Tuto volbu lze opakovat pro zvýšení množství informa‐
tivního (?) výstupu.
--vp ABCDE
Zvýší upovídanost pro jednotlivé procesní fáze. Například, "--vp 002" přidá 2 jednotky upovídanos‐
ti procesní fázi 3. Kombinace "-v --vp 00004" přidá 1 jednotku upovídanosti všem procesním fázím,
a další čtyři jednotky fázi 5.
-k Zachová dočasný procesní adresář, který se jinak po dokončení skriptu smaže. To může být užitečné,
chceme-li zkoumat vygenerovaný C kód, nebo jej znovu použít pro vytvoření jaderného modulu.
-g Guru režim. Umožní použít potenciálně nebezpečné expertní konstrukce, jako například vložený (em‐
bedded) C kód v rámci systemtap skriptu.
-P Režim prohledávání prologu (prologue-searching). Ekvivalentem je --prologue-searching=always. Ak‐
tivuje heuristiku pro obcházení problémů s nekonzistentními ladicími informacemi pro kontextové
proměnné parametrů funkcí.
-u Vypne optimalizace jako např. odstraňování nepotřebného kódu (a mnoho dalších) během 2., či 3.
procesní fáze (elaboration, translation).
-w Potlačí všechny varovné hlášení.
-W Zachází s varováními stejně jako s chybami.
-b Tzv. "bulk" režim pro přenos dat z jádra k uživateli. V tomto režimu jsou data pro jednotlivé CPU
přenášena odděleně a zapisována do samostatných souborů. Pro jejich případné sloučení lze použít
příkaz stap-merge.
-t Sbírá různé časovací informace jako například počet aktivací (probe hits) pro jednotlivé sondy,
průměrný čas strávený v jednotlivých sondách, atd.
-s NUM Nastaví velikost bufferu pro přenos dat ze systemtap modulu k uživateli na NUM MB. Na víceproceso‐
rovém systému v "bulk" režimu bude mít tuto velikost každý jednotlivý buffer.
-I DIR Přidá DIR mezi cesty ve kterých se vyhledávají tapset skripty. Více informací obsahuje popis pro‐
cesní fáze 2.
-D NAME=VALUE
Přidá danou direktivu do Makefile systemtap modulu. Toho lze využít například k předefinování růz‐
ných omezení popsaných níže.
-B NAME=VALUE
Předá danou direktivu příkazu make při sestavování systemtap modulu. Toho lze využít k přidání ne‐
bo změně "kconfig" voleb.
-a ARCH
Použije režim křížového překladu (cross compilation) pro danou cílovou architekturu. Tato volba
vyžaduje přístup ke kompilačnímu serveru a obvykle se používá spolu s volbami -B CROSS_COMPI‐
LE=arch-tool-prefix- a -r /build/tree.
--modinfo NAME=VALUE
Přidá pár klíč/hodnota ve formě makra MODULE_INFO do vygenerovaného modulu. Toho lze využít k na‐
stavení nebo úpravě různých jaderných kontrol souvisejících s modulem.
-G NAME=VALUE
Nastavuje hodnotu globální proměnné NAME na VALUE při volání programu staprun. Tak lze nastavit
hodnotu skalární globální proměnné skriptu.
-R DIR Prohledává DIR na systemtap runtime zdroje. Výchozí hodnotu DIR lze zobrazit např. prostřednictvím
"stap --help".
-r /DIR
Použije daný jaderný "build tree". Lze také nastavit prostřednictvím proměnné prostředí SYSTEM‐
TAP_RELEASE .
-r RELEASE
Určí "release" jádra v rámci "build tree" /lib/modules/RELEASE/build. Lze též nastavit prostřed‐
nictvím proměnné prostředí SYSTEMTAP_RELEASE .
-m MODULE
Použije dané jméno pro vygenerovaný jaderný modul namísto obvyklého náhodně vygenerovaného jména.
Takto vygenerovaný modul se pak navíc zkopíruje do aktuálního adresáře.
-d MODULE
Přidá do systemtap modulu ladicí informace o symbolech a informace pro odvíjení zásobníku pro daný
MODULE. Tak lze umožnit symbolické tracebacky pro MODULE i když do něj není explicitně vložena
sonda.
--ldd Přidá do systemtap modulu ladicí informace pro všechny uživatelské spustitelné soubory nebo DSO
knihovny, které ldd podezřívá z užitečnosti pro požadovanou analýzu. Totéž bude do systemtap modu‐
lu přidáno i pro moduly vyjmenované pomocí přepínačů -d. Upozornění: --ldd může systemtap modul
značně zvětšit.
--all-modules
Ekvivalent pro "-dkernel" a "-d" pro každý z momentálně zavedených modulů. Upozornění: --all-modu‐
les může systemtap modul značně zvětšit.
-o FILE
Přesměruje výstup do souboru FILE. V bulk režimu se použije pro každou CPU samostatný soubor s
prefixem FILE_ (FILE_cpu s -F) následovaným číslem CPU. Pro FILE je podporován strftime(3) formát.
-c CMD Zavede a nastartuje systemtap modul, spustí příkaz CMD, a vše ukončí spolu s CMD. Vedlejším efek‐
tem je nastavení target() na pid CMD.
-x PID Nastaví target() na PID. Takto lze psát skripty se zaměřením na daný proces. V tomto případě sys‐
temtap skript běží bez ohledu na životní cyklus procesu PID.
-e SKRIPT
Spustí SKRIPT. Příklad: stap -e "probe oneshot { log("hello") }"
-E SKRIPT
Spustí SKRIPT. Ten běží spolu s hlavním skriptem určeným pomocí -e nebo načteným ze souboru. Tuto
volbu lze opakovat pro načtení většího počtu skriptů. Taktéž ji lze použít v kombinaci s -l/-L.
-l PROBE
Namísto obvyklého spuštění systemtap skriptu, tato volba vypíše všechny sondy které odpovídají pa‐
rametru PROBE. PROBE může obsahovat zástupné symboly a přezdívky, ale ne seznam čárkou oddělených
sondážních bodů. Pokud PROBE neodpovídá žádné dostupné sondě, bude výsledkem chyba.
-L PROBE
Podobá se "-l", ale navíc vypíše dostupné lokální proměnné.
-F Bez -o tato volba zavede systemtap modul, spustí sondy a odpojí se od běžícího modulu. V kombinaci
s volbou -o spustí staprun na pozadí jako démon a vypíše jeho pid.
-S size[,N]
Nastavuje maximální velikost výstupního souboru a případně také počet výstupních souborů. V přípa‐
dě, že dojde k překročení maximální velikosti výstupního souboru size , přepne systemtap svůj vý‐
stup do dalšího souboru. Pakliže počet výstupních souborů překročí N , systemtap odstraní nejstar‐
ší výstupní soubor. Druhý z argumentů lze vynechat.
-T TIMEOUT
Ukončit skript po uplynutí TIMEOUT sekund.
--skip-badvars
Ignoruje neidentifikovatelné nebo nedostupné kontextové proměnné a, aniž by došlo k chybě, nahradí
jejich hodnotu nulou.
--prologue-searching[=WHEN]
Režim prologue-searching. Aktivuje heuristiku k vyrovnání se s nekvalitními ladicí informacemi pro
kontextové proměnné funkčních parametrů. WHEN může být "never" (nikdy), "always" (vždy), nebo "au‐
to" (tj. zapnuto na základě heuristiky). Když WHEN chybí, předpokládá se "always". Bez explicitní
specifikace se předpokládá "auto".
--suppress-handler-errors
Zabalí všechny obslužné rutiny do obálky podobné následujícímu kódu:
try { ... } catch { next }
blok, který způsobuje chyby v době běhu, bude tiše potlačen. Potlačené chyby se nebudou vyhodnoco‐
vat proti limitu MAXERRORS. V tomto režimu je taktéž potlačeno testování MAXSKIPPED , takže při
běhu skriptu může dojít k libovolnému množství chyb. Celkové počty chyb budou nicméně reportovány
při ukončení skriptu.
--compatible VERSION
Z uživatelského hlediska se tato volba pokouší napodobit chování systemtapu dané verze a umožnit
tak běh starším skriptům. Viz též sekce ZASTARÁVÁNÍ.
--check-version
Tato volba slouží k ověření, zda aktivní skript obsahuje konstrukce závislé na verzi systemtapu.
Viz též sekce ZASTARÁVÁNÍ.
--clean-cache
Tato volba smaže zastaralé položky v cache adresáři. To se normálně děje po úspěšném ukončení
skriptu, ale tato volba vyčistí cache explicitně, a pak ukončí systemtap. Viz sekce CACHE.
--color[=WHEN], --colour[=WHEN]
Tato volba ovládá obarvování výstupu. WHEN může být "never" (nikdy), "always" (vždy), nebo "auto"
(zapnuto pokud jde výstup do terminálu). Pokud WHEN chybí, předpokládá se "auto". Barvy lze měnit
prostřednictvím proměnné prostředí SYSTEMTAP_COLORS. Formát je následující:
klíč1=hodnota1:klíč2=hodnota2:klíč3=hodnota3 ...atd. Platné klíče jsou: "error", "warning",
"source", "caret", a "token". Hodnotami jsou "Select Graphic Rendition" (SGR) parametry. Viz doku‐
mentace k použitému terminálu. Příklad výchozího nastavení je:
error=01;31:warning=00;33:source=00;34:caret=01:token=01. Pokud SYSTEMTAP_COLORS chybí, použije se
výchozí nastavení. Pokud to je prázdné nebo chybné, obarvování se vypne.
--disable-cache
Tato volba vypne veškeré používání cache. Žádné soubory nebudou do cache adresáře zapsány, ani z
něj čteny.
--poison-cache
Tato volba zachází se soubory v cache jako s neplatnými. Žádné soubory nebudou z cache čteny, ale
nové soubory budou do cache zapsány na základě aktuálního běhu. Tato volba má pomoci hledat chybu
v případě, kdy se cache systemtapu zdá fungovat chybně. Pokud tato volba pomohla, provděpodobně je
v někde v systemtapu chyba, o které by vývojáři rádi věděli. Prosím, nahlašte ji.
--privilege[=stapusr | =stapsys | =stapdev]
Tato volba zkontroluje skript na přítomnost konstruktů, které nejsou povoleny pro zadanou úroveň
oprávnění (viz NEPRIVILEGOVANÍ UŽIVATELÉ). Pokud skript nepovolené konstrukty obsahuje, kompilace
skončí chybou.
Pokud je stapusr nebo stapsys specifikováno při použití kompilačního serveru (viz --use-server),
pak server zkontroluje skript a, pokud kompilace uspěje, server kryptograficky podepíše výsledný
modul, kde specifikuje, že daný modul je bezpečný pro použití uživatelem s danou úrovní oprávnění.
Pokud se --privilege nespecifikuje, -pN se také nespecifikuje s N < 5 a daný uživatel není root
ani člen skupiny stapdev, pak stap automaticky přidá odpovídající --privilege volbu k již specifi‐
kovaným volbám.
--unprivileged
Ekvivalent pro --privilege=stapusr.
--use-server[=HOSTNAME[:PORT] | =IP_ADDRESS[:PORT] | =CERT_SERIAL]
Specifikuje kompilační server(y) pro kompilaci, a/nebo - v kombinaci s --list-servers a
--trust-servers (viz níže) pro výpis serverů. Pokud je tato volba použita bez parametrů v neprivi‐
legovaném režimu (viz --privilege) , pak výchozí server, který bude pro kompilaci použit, bude ně‐
který z dostupných kompatibilních serverů "online SSL peer", a zároveň "module signer". Jinak bude
jako výchozí server použit některý z dostupných kompatibilních serverů "online SSL peer".
--use-server lze použít opakovaně a v tomto případě bude seznam použitelných serverů postupně roz‐
šiřován v daném pořadí. Servery lze specifikovat pomocí hostaname, IP adresy, nebo seriálním čís‐
lem certifikátu (získaným prostřednictvím --list-servers). Poslední možnost je nejběžnější pro
(od)nastavování důvěryhodnosti serveru. Viz --trust-servers níže.
Pokud je server specifikován pomocí hostname nebo IP adresy, pak je volitelně možné určit i číslo
portu. To je vhodné pro přístup k serverům, které nejsou na lokální síti, nebo pro specifikování
konkrétního serveru.
IP adresou může být jak IPv4, tak IPv6.
Pokud existuje více než jedno rozhraní s danou link-local IPv6 adresou, pak je možné zvolit kon‐
krétní rozhraní připojením znaku "%" a názvu rozhraní k adrese, například:
"fe80::5eff:35ff:fe07:55ca%eth0".
Pro určení čísla portu IPv6 adresy je nutné uzavřít adresu do hranatých závorek , aby došlo k od‐
dělení adresy od čísla portu. Například: "[fe80::5eff:35ff:fe07:55ca]:5000" nebo
"[fe80::5eff:35ff:fe07:55ca%eth0]:5000".
Pokud --use-server nebylo specifikováno, -pN nebylo specifikováno s N < 5, a uživatel není root,
není člen skupiny stapdev, ale je členem skupiny stapusr, pak stap automaticky přidá --use-server
k již specifikovaným volbám.
--use-server-on-error[=yes|=no]
Požádá stap, aby zkusil kompilaci znovu s použitím kompilačního serveru, pokud lokální kompilace
selže. Pokud tato volba není specifikována, pak se za výchozí považuje --use-server-on-error=no
--use-server-on-error je ekvivalentem pro --use-server-on-error=yes.
Kompilace může být přerušena pro určitý typ chyby, jako například nedostatek dat nebo zdrojů. K
tomu může dojít i během rekompilace. Pro rekompilaci budou servery voleny automaticky tak, jako by
byla použita volba --use-server bez parametrů.
--list-servers[=SERVERS]
Zobrazí stav požadovaných SERVERS, kde SERVERS je čárkou oddělený seznam atributů popisujících
servery. Sjednocení atributů slouží k vygenerování seznamu serverů. Dostupné atributy jsou:
all specifikuje všechny známé servery (důvěryhodné servery "SSL peer", důvěryhodné servery "mo‐
dule signer", servery ve stavu "online").
specified
určuje servery specifikované pomocí --use-server.
online vybere ze seznamu jen ty servery, které jsou aktuálně ve stavu "online".
trusted
vybere ze seznamu jen důvěryhodné servery "SSL peer".
signer vybere ze seznamu jen servery "module signer", viz --privilege.
compatible
vybere jen kompatibilní servery ve smyslu kernel release a architektury.
Pokud není dán žádný argument, pak výchozí volbou je specified. Pokud žádné servery nebyly speci‐
fikovány pomocí --use-server, pak budou vypsány výchozí servery pro --use-server.
Poznamenejme, že --list-servers používá avahi-daemon k detekci online serverů. Pokud tato služba
není dostupná, pak --list-servers nebude detekovat žádné online servery. Aby --list-servers dete‐
koval servery poslouchající na IPv6 adresách, musí konfigurační soubor avahi démona, /etc/ava‐
hi/avahi-daemon.conf , obsahovat "use-ipv6=yes". Po případné úpravě konfiguračního souboru je tře‐
ba službu restartovat.
--trust-servers[=TRUST_SPEC]
Nastavit nebo odvolat natavení důvěryhodnosti kompilačního serveru specifikovaného pomocí
--use-server podle TRUST_SPEC, kde TRUST_SPEC je čárkou oddělený seznam typů důvěryhodnosti. Pod‐
porované typy jsou:
ssl důvěřovat specifikovaným serverům jako "SSL peer".
signer důvěřovat specifikovaným serverům jako "module signer" (viz --privilege). Jen root může na‐
stavit signer.
all-users
důvěřovat specifikovaným serverům jako "SSL peer" pro všechny uživatele na localhostu. Vý‐
chozí chování je nastavit tento typ důvěřování jen pro aktuálního uživatele. Důvěra typu
"module signer" se vždy vztahuje na všechny uživatele. Jen root může nastavit all-users.
revoke ruší určenou relaci důvěry. Výchozí chování je zapnutí relace důvěry.
no-prompt
nežádat uživatele o potvrzení před provedením akce. Výchozí chování je požádat o potvrzení
před provedením akce.
Pokud žádný argument není nastaven, použije se výchozí hodnota ssl. Pokud pomocí --use-server, ne‐
byly určené žádné servery, žádná relace důvěry nebude nastavena ani zrušena.
Dokud se nespecifikuje no-prompt, uživatel bude požádán o potvrzení požadované akce.
--dump-probe-types
Vypíše všechny podporované typy sond a skončí. Pokud je též nastaveno --privilege=stapusr , pak
tento seznam bude omezen tak, aby vidět byly pouze sondy, které má daný uživatel právo použít.
--dump-probe-aliases
Vypíše všechny přezdívky nalezené v tapset skriptech a skončí.
--dump-functions
Vypíše všechny veřejné funkce nalezené v tapset skriptech a skončí. Také vypíše jejich parametry a
typy. Návratový typ "unknown" značí, že daná funkce nevrací hodnotu. Poznamenejme, že ne všechny
návratové typy / typy parametrů je vždy možné při syntaktické analýze stanovit. Nestanovené typy
budou též označeny jako "unknown". Funkce --dump-functions je náročná na paměť a proto nemusí
správně fungovat s --use-server pokud na cílovém systému narazí na rlimit pro paměť procesu, na‐
příklad prostřednictvím konfiguračního souboru ~stap-server/.systemtap/rc, viz stap-server(8).
--remote URL
Provede skript na vzdáleném stroji. Tuto volbu je možné opakovat pro provedení skriptu na více
strojích. Procesní fáze 1-4 se provedou lokálně, jak je běžné, a pak během fáze 5, se modul zkopí‐
ruje na specifikované stroje a na nich provede. Přijatelné URL jsou:
[USER@]HOSTNAME, ssh://[USER@]HOSTNAME
Tento režim využívá SSH, volitelně s využitím specifického uživatelského jména username.
Pokud je použit uživatelský ssh_config, je třeba do něj přidat SendEnv LANG pro zachování
nastavení lokalizace.
libvirt://DOMAIN, libvirt://DOMAIN/LIBVIRT_URI
Tento režim využívá ke spuštění skriptu stapvirt v doméně obsluhované libvirt démonem. Vo‐
litelně je možno specifikovat LIBVIRT_URI pro připojení ke specifickému driveru nebo vzdá‐
lenému stroji. Například pro připojení k místnímu privilegovanému QEMU driveru použijte:
--remote libvirt://MyDomain/qemu:///system
Viz <http://libvirt.org/uri.html> pro podrobnosti ohledně podporovaných formátů URI. Viz
též stapvirt(1).
unix:PATH
V tomto režimu dojde k připojení přes UNIX soket. Toho lze využít pro připojení přes QEMU
virtio-serial port pro spuštění skriptu uvnitř běžícího virtuálního stroje.
direct://
Loopback režim pro spouštění na localhostu.
--remote-prefix
Oprefixuje každou řádku výstupu "N: ", kde N je index vzdáleného stroje ze kterého daný výstup po‐
chází.
--download-ladicíinfo[=OPTION]
Podle OPTION zapne, vypne, nebo nastaví timeout pro funkci automatického stahování balíčků s ladi‐
cími informacemi, kterou nabízí ABRT. Přípustné hodnoty pro OPTION jsou:
yes povolí automatické stahování bez časového omezení. Totéž jako --download-debuginfo bez pa‐
rametru.
no explicitně vypne automatické stahování Totéž jako nepoužití --download-debuginfo vůbec.
ask ukáže výstup ABRTu a dotáže se uživatele, zda se má pokračovat v downloadu. Žádný timeout
nebude nastaven.
<timeout>
specifikuje timeout jako pozitivní celé číslo vyjadřující maximální počet sekund pro down‐
load.
--rlimit-as=NUM
Určí maximální velikost virtuální paměti procesu v bajtech. Bez specifikace NUM nebude žádný limit
nastaven.
--rlimit-cpu=NUM
Určí limit pro čas CPU v sekundách. Bez specifikace NUM není žádný limit nastaven.
--rlimit-nproc=NUM
Určí maximální počet procesů které může systemtap vytvořit. Bez specifikace NUM není žádný limit
nastaven.
--rlimit-stack=NUM
Nastaví maximální velikost zásobníku v bajtech. Bez specifikace NUM není žádný limit nastaven.
--rlimit-fsize=NUM
Nastaví maximální velikost souboru, který je možno vytvořit, v bajtech. Bez specifikace NUM není
žádný limit nastaven.
--sysroot=DIR
Nastaví "sysroot" adresář, kde budou umístěny cílové soubory (programy, knihovny atd.) Po nastave‐
ní -r RELEASE bude v adresáři "sysroot" hledán "build" adresář jádra, ovšem po nastavení -r /DIR
nebude "sysroot" prohledáván na "build" adresář jádra.
--sysenv=VAR=VALUE
Nastaví alternativní hodnotu proměnné prostředí pokud se tato hodnota na vzdáleném systému liší.
Předpokládá se, že proměnné vyjadřující cesty budou uvedeny jako relativní cesty vzhledem k
--sysroot (pokud je nastaven).
--suppress-time-limits
Potlačí -DSTP_OVERLOAD*, -DMAXACTION a -DMAXTRYLOCK. Vyžaduje guru režim (-g).
--runtime=MODE
Nastaví runtime režim pro procesní fázi 5. Validní hodnoty jsou kernel (výchozí), dyninst a bpf.
Viz sekce ALTERNATIVNÍ RUNTIME.
--dyninst
Zkratka pro --runtime=dyninst.
--save-uprobes
Na strojích, kde si SystemTap musí sestavit svůj vlastní modul "uprobes" (jádra před 3.5), tato
volba instruuje SystemTap, aby po sestavení tento pomocný modul zachoval v aktuálním adresáři.
--target-namespaces=PID
Nastavuje cílový "namespace" (jmenný prostor procesů) na "namespace" do kterého patří PID. Volba
souvisí s "namespace-aware" tapset funkcemi. Pokud cílový "namespace" není specifikován, použije
se "namespace" v kterém běží stap.
--monitor=INTERVAL
Umožňuje zobrazovat informace o stavu modulu (čas běhu, jméno modulu, id uživatele, který modul
aktivoval, informace o paměti, globální proměnné, seznam sond včetně jejich statistik). Je možno
nastavit volitelný parametr INTERVAL, který určuje obnovovací frekvenci stavového okna v sekun‐
dách. Činnost modulu lze ovládat následujícími klávesami:
r přenastaví všechny globální proměnné na jejich výchozí hodnoty nebo na nulu, pokud výchozí
hodnota nebyla určena.
s cyklicky mění hodnoty daného atributu za účelem změny třídění seznamu sond.
t umožňuje aktivovat/deaktivovat sondu indexem.
navigační-klávesy
Klávesami j/k/Up/Down lze posouvat seznam sond. Klávesami d/u/PgDn/PgUp lze rolovat v sta‐
tistice modulu.
ARGUMENTY
Všechny další argumenty z příkazové řádky se předají kompilátoru ke zpracování. Viz níže.
SKRIPTOVACÍ JAZYK
Skriptovací jazyk systemtapu připomíná awk a C. Existují v něm dva hlavní konstrukty: sondy a funkce. V
jejich rámci se používají příkazy a výrazy se syntaxí podobnou syntaxi jazyka C.
OBECNÁ SYNTAXE
Bílé místo se ignoruje. Podporovány jsou komentáře tří typů:
# ... shell styl, do konce řádku, mimo $# a @#
// ... C++ styl, do konce řádku
/* ... C styl ... */
Literály jsou buďto řetězce uzavřené v uvozovkách (dovolují obvyklé C escape sekvence se zpětnými lomít‐
ky, které lze řetězit podobně jako v C), nebo celá čísla (dekadická, hexadecimální, nebo oktalová, zapsa‐
ná stejně jako v C). Maximální délka řetězce je rozumně omezená na několik set bajtů. Celá čísla jsou
64-bitová se znaménkem. Parser formálně přijímá i kladná čísla nad 2**63, pro které pak používá modulo
aritmetiku z důvodu přetečení (wrap around).
Na konci příkazové řádky lze skriptům předat parametry. V rámci skriptu k nim pak lze přistupovat pro‐
střednictvím $1 ... $<NN> pokud jde literály neuzavřené do uvozovek, nebo @1 ... @<NN> pokud jde o řetěz‐
cové literály uzavřené do uvozovek. Počet argumentů je přístupný prostřednictvím $# (jakožto číslo neuza‐
vřené do uvozovek) nebo prostřednictvím @# (jakožto číslo do uvozovek uzavřené). Tyto symboly lze použit
na místě libovolné lexikální jednotky skriptu, a k jejich vyhodnocení dojde již v počáteční fázi překladu
(preprocessing).
FÁZE PŘEDZPRACOVÁNÍ (PREPROCESSING)
Součástí lexikální analýzy je jednoduchá fáze předzpracování. V ní lze (ne)vyhodnocovat části kódu na zá‐
kladě podmínky. Příslušná syntaxe se obecně podobá ternárnímu operátoru: podmínka ? výraz1 : výraz2
%( PODMÍNKA %? VÝRAZ-1 %)
%( PODMÍNKA %? VÝRAZ-1 %: VÝRAZ-2 %)
PODMÍNKA je buďto výraz, jehož formát je určen prvním klíčovým slovem, nebo porovnání řetězcových či nu‐
merických literálů, nebo výraz složený z takových podmínek s využitím operátorů || a &&. Nicméně, závorky
zde zatím nejsou podporovány, takže je důležité mít na zřeteli, že && má při vyhodnocení přednost před
||.
Pokud první částí podmínky je identifikátor kernel_vr nebo kernel_v odkazující se k verzi jádra s přípo‐
nou ("2.6.13-1.322FC3smp"), nebo bez přípony ("2.6.13"), pak následovat musí jeden z operátorů porovnání:
<, <=, ==, !=, >, a >=, a třetí částí podmínky je řetězcový literál vyjadřující verzi jádra v RPM-stylu.
Podmínka se považuje za splněnou, pokud verze běžícího jádra (volitelně předefinovaná volbou -r ) se
srovnává se zadanou hodnotou. Srovnání provádí glibc funkce strverscmp().
Pokud operátorem je jednoduchá rovnost (==), nebo nerovnost (!=), a pravý operand obsahuje zástupné sym‐
boly (* nebo ? nebo [), , pak celý výraz bude interpretován jako "wildcard (mis)match" a bude vyhodnocen
glibc funkcí fnmatch().
Pokud první částí podmínky je arch odkazující se k architektuře procesoru (pojmenované podle ARCH/SUBARCH
v terminologii jádra), pak druhou částí podmínky je jeden z operátorů: == nebo !=, a třetí částí podmínky
je požadovaný řetězcový literál, který může obsahovat zástupné symboly ("wildcard (mis)match").
Podobně, pokud první složkou podmínky je identifikátor jako CONFIG_* odkazující se ke konfigurační volbě
jádra, pak druhou částí podmínky je == nebo !=, a třetí částí podmínky je řetězcový literál odpovídající
volby (obvykle "y", nebo "m"). Neexistující, nebo nenastavené konfigurační volby v tomto kontextu odpoví‐
dají prázdnému řetězci. Vyhodnocení opět probíhá jako "wildcard (mis)match" s využitím fnmatch().
Pokud první částí je identifikátor systemtap_v, pak se test odkazuje k verzi systemtapu, kterou lze voli‐
telně pro staré skripty nastavit prostřednictvím volby --compatible. Operátor porovnání je jako u ker‐
nel_v , a pravým operandem je řetězec vyjadřující verzi jádra. Viz též sekce ZASTARÁVÁNÍ níže.
Pokud první částí podmínky je systemtap_privilege, pak se test odkazuje k úrovni oprávnění se kterou je
systemtap skript překládán. V tomto případě je podmínkou jeden z operátorů == nebo !=, a třetí částí pod‐
mínky je jeden z řetězcových literálů "stapusr", "stapsys", nebo "stapdev".
Pokud první částí podmínky je identifikátor guru_mode, pak test ověřuje, zda je systemtap skript překlá‐
dán v "guru" režimu (-g). Operátorem pro tento případ může být == nebo !=, a třetí částí podmínky je čís‐
lo. Buďto 1, nebo 0.
Pokud prvním indetifikátorem je runtime, testuje se runtime režim (--runtime). Viz sekce ALTERNATIV‐
NÍ RUNTIME níže pro informaci o dostupných runtime backendech. Porovnávací operátor v tomto případě je ==
nebo !=, a třetí částí podmínky je řetězcový literál odpovídající runtime. Porovnání je typu "wildcard
(mis)match" s využitím fnmatch()
Poslední možností je situace, kdy PODMÍNKA srovnává prosté číselné, nebo řetězcové literály.
VÝRAZ-1 a VÝRAZ-2 představují výskyt nuly nebo více obecných lexikálních jednotek (které mohou obsahovat
další vložené podmínky preprocesoru), a jsou preprocesorem předány na vstup parseru v závislosti na vy‐
hodnocení uvedené podmínky. Například následující kód vyvolá kompilační chybu v případě že verze běžícího
jádra na cílovém systému je novější, než 2.6.5:
%( kernel_v <= "2.6.5" %? **ERROR** %) # "invalid token sequence"
Naproti tomu následující kód umožní elegantně se vyrovnat s různými verzemi jádra:
probe kernel.function (
%( kernel_v <= "2.6.12" %? "__mm_do_fault" %:
%( kernel_vr == "2.6.13*smp" %? "do_page_fault" %:
UNSUPPORTED %) %)
) { /* ... */ }
%( arch == "ia64" %?
probe syscall.vliw = kernel.function("vliw_widget") {}
%)
MAKRA PREPROCESORU
Preprocesor přijímá jednoduchá makra a vyhodnocuje je v rámci samostatné procesní fáze před vyhodnocením
podmínek.
Makra se definují následující konstrukcí:
@define NAME %( BODY %)
@define NAME(PARAM_1, PARAM_2, ...) %( BODY %)
Makra (a také parametry uvnitř těla maker) jsou přístupná přidáním prefixu "@" před jejich jméno"
@define foo %( x %)
@define add(a,b) %( ((@a)+(@b)) %)
@foo = @add(2,2)
K expanzi maker v současnosti dochází v samostatné preprocesní fázi před zpracováním podmínek. Proto do‐
jde k vyhodnocení všech maker v rámci kondicionálu bez ohledu na konkrétní podmínku. To může vést k neza‐
mýšleným chybám:
// Následující kód způsobí chybu:
%( CONFIG_UPROBE == "y" %?
@define foo %( process.syscall %)
%:
@define foo %( **ERROR** %)
%)
// Následující kód bude fungovat správně:
@define foo %(
%( CONFIG_UPROBE == "y" %? process.syscall %: **ERROR** %)
%)
První příklad je chybný, protože vyvolá duplicitní definici makra "foo".
Za normálních okolností je definice platná lokálně - pouze v souboru kde se vyskytuje. Makro definované v
tapset skriptu tedy není veřejně použitelné v rámci uživatelského skriptu. Makra, která mají být veřejně
dostupná, lze sdružovat do knihoven s příponou ".stpm" nacházející se v "tapset search path". Tyto soubo‐
ry mohou obsahovat @define konstrukty, které budou dostupné nejen ve všech tapsetech, ale i v uživatel‐
ských skriptech. Volitelně mohou být definice maker v rámci ".stpm" souborů zabaleny v kondicionálech
preprocesoru.
KONSTANTY
V rámci tapset skriptů, nebo guru skriptů je možno přistupovat ke konstantním symbolům, jako jsou napří‐
klad makra jazyka C, prostřednictvím vestavěného operátoru @const(). Pokud je potřeba přidat příslušný
#include dodatečného hlavičkového souboru, lze tak učinit prostřednictvím vloženého kódu jazyka C.
@const("STP_SKIP_BADVARS")
PROMĚNNÉ
Identifikátory pro proměnné a funkce jsou alfanumerické sekvence, které mohou obsahovat _ a $. Nesmí za‐
čínat číslicí (stejně jako v C). Proměnné jsou lokální vzhledem ke svému bloku (funkce nebo sondy) a je‐
jich životnost je spojena s tímto blokem.
Skalární proměnné jsou implicitně řetězcového, nebo celočíselného typu. Asociativní pole mohou také obsa‐
hovat řetězcové nebo celočíselné hodnoty a jako klíč jim slouží n-tice řetězců nebo celých čísel. Zde je
několik příkladů:
var1 = 5
var2 = "bar"
array1 [pid()] = "name" # jednoduchý číselný klíč pole
array2 ["foo",4,i++] += 5 # n-tice jako klíč pole
if (["hello",5,4] in array2) println ("yes") # test na členství
Překladač provádí typové odvození (type inference) na všech identifikátorech včetně indexů polí a parame‐
trů funkcí. Nekonzistentní zacházení s typy způsobí chybu překladu.
Proměnné lze definovat jako globální, takže mohou být sdíleny mezi sondami a funkcemi, a žijí stejně
dlouho jako celé systemtap sezení. Pro globální proměnné existuje jediný jmenný prostor. Přístup ke glo‐
bálním proměnným je chráněn zámky, viz BEZPEČNOST A OCHRANA SOUKROMÍ. Globální proměnnou lze deklarovat
kdekoli ve vnější úrovni zdrojového kódu, tedy mimo bloky sond a funkcí. Globální proměnné, kterým byla
přiřazena hodnota, ale nikdy nebyla čtena, budou automaticky zobrazeny na konci systemtap sezení. Překla‐
dač se pokusí odvodit datový typ z hodnot a případně, pokud jde o pole, i z klíčů. Volitelně lze globální
proměnnou inicializovat řetězcovým, nebo číselným literálem. Zde jsou příklady deklarace globálních pro‐
měnných:
global var1, var2, var3=4
Globální proměnné lze také použít jako parametry systemtap modulu. Toho lze dosáhnout buďto použitím pře‐
pínače stap -G, nebo modul připravit předem pomocí stap -p4 a parametry mu předat později při jeho zavá‐
dění na příkazové řádce programu staprun. Viz staprun(8).
Rozsah platnosti globální proměnné lze omezit na tapset soubor, nebo na uživatelský skript prostřednic‐
tvím klíčového slova "private". V tom případě je klíčové slovo "global" volitelné. Následující deklarace
označuje var1 a var2 jako privátní globální proměnné:
private global var1=2
private var2
Pole mají omezenou velikost parametrem MAXMAPENTRIES. Viz BEZPEČNOST A OCHRANA SOUKROMÍ
Volitelně lze polím (která jsou vždy globální) nastavit maximální velikost v hranatých závorkách, čímž se
předefinuje MAXMAPENTRIES pro dané pole. Poznamenejme, že velikost se vztahuje jen k počtu prvků, nikoliv
k celkové velikosti pole v paměti. Příklad:
global tiny_array[10], normal_array, big_array[50000]
Polím lze nastavit příznak "%". To způsobí, že pokud do pole přidáme více prvků, než pro kolik je dimen‐
zováno, začnou staré prvky mizet (LIFO). To platí jak pro asociativní, tak pro statistická pole, viz ní‐
že. Příklad:
global wrapped_array1%[10], wrapped_array2%
Mnohé sondy poskytují kontextové proměnné, což jsou hodnoty získané za běhu z jádra, nebo zkoumané uživa‐
telské aplikace. Jejich identifikátory začínají znakem $. Sekce KONTEXTOVÉ PROMĚNNÉ v manuálové stránce
stapprobes(3stap) obsahuje jejich seznamy pro jednotlivé typy sond. Tyto kontextové proměnné se stanou
normálními řetězcovými nebo numerickými proměnnými použitelnými ve skriptu, jakmile provedeme příslušné
přiřazení (např. foo=$foo). Podívejte se níže na sekci PŘETYPOVÁNÍ, kde je popsáno jak takovou proměnnou
přetypovat zpět na ukazatel je-li to třeba.
PŘÍKAZY
Příkazy umožňují procedurální řízení běhu skriptu. Mohou se vyskytovat uvnitř funkcí a obslužných rutin
sond. Celkový počet příkazů, které je v reakci na nějakou událost možno spustit, je omezen na hodnotu de‐
finovanou makry MAXACTION_* ve vygenerovaném C-kódu a pohybuje se kolem 1000.
EXP Vyhodnotit řetězcový, nebo číselný výraz a zahodit hodnotu.
{ STMT1 STMT2 ... }
Vykonat každý příkaz v sekvenci v tomto bloku. Poznamenejme, že oddělovače a znaky pro ukončení
příkazu nejsou mezi jednotlivými příkazy nezbytné.
; Prázdný příkaz, nedělat nic. Je užitečný jako volitelný oddělovač mezi příkazy ke zlepšení detekce
syntaktických chyb a k upřesnění některých syntaktických nejednoznačností gramatiky.
if (EXP) STMT1 [ else STMT2 ]
Porovnat číselný výraz EXP s nulou. Pak vykonat příkaz STMT1 (EXP není nula), nebo příkaz STMT2
(EXP je nula).
while (EXP) STMT
Dokud má číselný výraz EXP nenulovou hodnotu, spouštěj STMT.
for (EXP1; EXP2; EXP3) STMT
Vykoná EXP1 jako inicializaci. Dokud EXP2 má nenulovou hodnotu, bude vykonávat STMT a iterační vý‐
raz EXP3.
foreach (VAR in ARRAY [ limit EXP ]) STMT
Cyklení přes každý prvek globálního pole ARRAY s přiřazením aktuálního prvku proměnné VAR. Pole
není v rámci STMT dovoleno měnit. Přidáním operátoru + nebo - za identifikátor VAR nebo ARRAY, se
zajistí iterování přes setříděné pole jedním, nebo druhým směrem. Pokud pole obsahuje statistické
agregátory, pak přidáním požadovaného operátoru @operator mezi ARRAY a symbol + nebo - určíme tří‐
dicí agregační funkci. Viz příklad níže v sekci STATISTIKA. Výchozí je @count. S využitím volitel‐
ného klíčového slova limit lze maximální počet iterací omezit na EXP. Poznamenejme, že EXP se vy‐
hodnocuje na začátku smyčky.
foreach ([VAR1, VAR2, ...] in ARRAY [ limit EXP ]) STMT
Podobně jako výše, ovšem v tomto případě je klíčem pole n-tice hodnot. Třídicí příponu lze použít
maximálně na jednom z prvků n-tice.
foreach ([VAR1, VAR2, ...] in ARRAY [INDEX1, INDEX2, ...] [ limit EXP ]) STMT
Podobně jako výše, ovšem iterovat se bude pouze přes prvky, kde klíč vyhovuje dané hodnotě. Pro
určení indexu lze použít znak *, se kterým bude zacházeno jako se zástupným symbolem.
foreach (VAR0 = VAR in ARRAY [ limit EXP ]) STMT
Tato varianta foreach uchová aktuální hodnotu při každé iteraci ve VAR0, takže bude odpovídat
ARRAY[VAR]. Tohle analogicky funguje s n-ticí klíčů. Třídicí přípony na VAR0 mají stejný význam
jako na ARRAY.
foreach (VAR0 = VAR in ARRAY [INDEX1, INDEX2, ...] [ limit EXP ]) STMT
Podobné jako výše, ovšem iteruje se pouze přes prvky, kde klíče vyhovují daným hodnotám. Pro urče‐
ní indexu lze použít znak * se kterým bude zacházeno jako se zástupným symbolem.
break, continue
Ukončit, nebo znovu iterovat vnitřní smyčku. Aplikovatelné na while nebo for nebo foreach.
return EXP
Vrátit hodnotu EXP z funkce. Příkaz return není ve funkci povinný. Pokud se vynechá, bude funkce
mít speciální návratový datový typ "unknown".
next Ihned ukončí obslužnou rutinu sondy. To je obzvlášť užitečné u přezdívek, které používají filtro‐
vací podmínky.
try { STMT1 } catch { STMT2 }
Vykonej příkazy v prvním bloku STMT1. Pokud při tom dojde k chybě běhu, ukonči STMT1 a začni pro‐
vádět STMT2. Případné chyby v STMT2 se budou propagovat do vnějšího catch bloku, pokud tam takový
je.
try { STMT1 } catch(VAR) { STMT2 }
Podobně jako v předchozím případě, ale navíc se chybová hláška, jakožto řetězec, uchová v proměnné
VAR.
delete ARRAY[INDEX1, INDEX2, ...]
Odstraní z pole prvky určené n-ticí klíčů. Pokud n-tice klíčů obsahuje symbol * na místě indexu,
bude s * zacházeno jako jako se zástupným symbolem.
Není chybou pokusit se smazat prvek, který neexistuje.
delete ARRAY
Smazat všechny prvky pole ARRAY.
delete SCALAR
Maže hodnotu SCALAR. Celočíselné proměnné budou vynulovány, řetězcové proměnné nastaveny na "", a
statistické proměnné budou nastaveny do výchozího prázdného stavu.
VÝRAZY
SystemTap podporuje množství operátorů, které mají syntaxi a sémantiku velmi podobnou jejich C a awk pro‐
tějškům. Aritmetické operace se provádějí v souladu s pravidly jazyka C pro celá čísla se znaménkem. Dě‐
lení nulou nebo přetečení rozsahu se detekuje a způsobí chybu.
binární numerické operátory
* / % + - >> << & ^ | && ||
binární operátory nad řetězci
. (spojení řetězců)
číselné přiřazovací operátory
= *= /= %= += -= >>= <<= &= ^= |=
řetězcové přiřazovací operátory
= .=
unární číselné operátory
+ - ! ~ ++ --
operátory pro srovnávání čísel, řetězců a práci s regulárními výrazy
< > <= >= == != =~ !~
ternární operátor
podmínka ? exp1 : exp2
seskupovací operátor
( exp )
volání funkce
fn ([ arg1, arg2, ... ])
operátor testující členství v poli
exp in array
[exp1, exp2, ...] in array
[*, *, ... ]in array
REGULÁRNÍ VÝRAZY
Skriptovací jazyk systemtapu podporuje práci s regulárními výrazy. Základní operace testující (ne)shodu
řetězce s regulárním výrazem:
exp =~ regex
exp !~ regex
První operand musí být výraz vyhodnotitelný na řetězec; druhý operand musí být řetězcový literál obsahu‐
jící platný regulární výraz.
Syntaxe regulárních výrazů podporuje většinu rozšířených regulárních výrazů POSIX standardu. Výjimkou je
znovupoužití částí regulárního výrazu ("\1").
Po úspěšném nalezení je text vyhovující regulárnímu výrazu dostupný prostřednictvím tapsetových funkcí
matched() a ngroups() následovně:
if ("an example string" =~ "str(ing)") {
matched(0) // -> vrací "string", t.j. celý odpovídající řetězec
matched(1) // -> vrací "ing", t.j. první odpovídající podřetězec
ngroups() // -> vrací 2, t.j. počet odpovídajících skupin řetězců
}
SONDY
Hlavním syntaktickým konstruktem skriptovacího jazyka jsou sondy (probes). Sondy spojují abstraktní udá‐
losti s bloky příkazů a vytvářejí tak obslužné rutiny událostí. Obecná syntaxe je následující:
probe PROBEPOINT [, PROBEPOINT] { [STMT ...] }
probe PROBEPOINT [, PROBEPOINT] if (CONDITION) { [STMT ...] }
Události jsou určeny syntaxí nazývanou sondážní body (probe points). Existuje množství variant sondážních
bodů. Některé jsou definovány překladačem a mnohé další jsou definovány v tapset skriptech jako přezdív‐
ky. Sondážní body mohou využívat zástupné znaky, být seskupovány, může být určováno jejich pořadí, či mo‐
hou být deklarovány jako volitelné. Více podrobností o syntaxi a sémantice sondážních bodů viz
stapprobes(3stap).
Obslužná rutina sondy se interpretuje relativně ke kontextu dané události. Pro události související s
kernel kódem může tento kontext obsahovat proměnné definované ve zdrojovém kódu jádra. Takové "kontexto‐
vé" proměnné jsou pak přístupné ve skriptu z prefixem "$". Jsou přístupné pouze pokud byly kompilátorem
jádra zachovány navzdory optimalizacím. To je stejné omezení s jakým se potýká debugger když pracuje s
optimalizovaným kódem. Navíc musí tyto objekty být v momentě vykonávání obslužné rutiny sondy přítomny
přímo v nastránkované (in-paged) paměti, protože systemtap nesmí zapříčinit žádné dodatečné stránkování.
Některé sondy mají velmi málo kontextových proměnných. Viz stapprobes(3stap).
Proby mohou být doplněny podmínkou pro uzamčení, sestávající z jednoduchého booleovského výrazu. Sonda je
"odemčená" (tedy neaktivní) vyhodnocuje-li se zamykací podmínka na false. V tomto stavu některé sondy
snižují nebo zcela eliminují svoji režii, tedy nekonzumují systémové prostředky. Jakmile se zamykací pod‐
mínka vyhodnotí na true bude sonda brzy znovu uzamčena a její obslužná rutina začne brzy být opět volána
když nastane příslušná událost. Přestože je zamykání rychlé, trvá nenulový čas, a některé události ne‐
musejí být zachyceny. V případech kdy toto může představovat problém, je lepší zamykání sond nepoužívat.
Nové sondážní body lze definovat pomocí přezdívek (probe aliases). Definice přezdívky vypadá podobně jako
definice sondy samotné, ale namísto aktivování sondy v daném místě pouze definují nové jméno - přezdívku
pro již existující sondážní bod. Existují dva typy přezdívek: "prologue" a "epilogue", které jsou defino‐
vány pomocí "=" nebo resp. "+=".
Přezdívka typu "prologue" vznikne tak, že se blok příkazů, který následuje definici této přezdívky, přidá
před sondu ke které se váže jako její prolog. Naproti tomu přezdíka typu "epilogue" vznikne tak, že blok
příkazů, který následuje definici této přezdívky, se přidá za sondu ke které se váže jako její epilog.
Například:
probe syscall.read = kernel.function("sys_read") {
fildes = $fd
if (execname() == "init") next # přeskočit zbytek sondy
}
definuje nový sondážní bod. syscall.read, který se rozšiřuje na kernel.function("sys_read"), s daným pří‐
kazem jako prologem, což je výhodné k předdefinování některých proměnných pro danou přezdívku a/nebo pro
přeskočení dané sondy v závislosti na podmínce. Naproti tomu
probe syscall.read += kernel.function("sys_read") {
if (tracethis) println ($fd)
}
definuje nový sondážní bod s daným příkazem jako epilogem, což může být užitečné k provedení činností v
závislosti na hodnotách proměnných nastavených uživatelem přezdívky. Poznamenejme, že v každém případě
jsou příkazy v obslužné rutině přezdívky vykonávány za běhu, takže v danou chvíli zejména nedochází k vy‐
hodnocování/substituci maker.
Přezdívku lze použít stejně jako vestavěnou sondu překladače.
probe syscall.read {
printf("reading fd=%d\n", fildes)
if (fildes > 10) tracethis = 1
}
FUNKCE
Systemtap skripty mohou definovat funkce. Ty mohou přijímat libovolný počet skalárních (celočíselných ne‐
bo řetězcových) parametrů, a vrací jednu skalární funkční hodnotu. Příklad funkce:
function thisfn (arg1, arg2) {
return arg1 + arg2
}
Povšimněme si absence explicitních deklarací typů. Typy, jsou odvozeny (inferred) překladačem. Nicméně,
pokud je to potřeba, může definice funkce zahrnovat explicitní deklarace návratového typu a/nebo typů ar‐
gumentů. To je užitečné zejména pro vložené C funkce. V následujícím příkladě je automatické odvození ty‐
pu nutné jen pro arg2 (řetězec):
function thatfn:string (arg1:long, arg2) {
return sprint(arg1) . arg2
}
Funkce se mohou volat navzájem až do určitého limitu zanoření. Tento limit je definován makrem MAXNESTING
ve vygenerovaném zdrojovém kódu modulu a pohybuje se okolo 10.
Funkce lze označit za privátní použitím klíčového slova "private". Tím se omezí jejich platnost soubor
(tapset nebo uživatelský skript) ve kterém jsou definovány. Příklad:
private function three:long () { return 3 }
TISK
Existuje několik funkcí, se kterými překladač zachází neobvykle. Poznamenejme, že data jsou generována v
jaderném modulu a před tiskem musí být přenesena do uživatelského prostoru. Tyto funkce formátují hodnoty
pro pohodlný tisk do výstupního proudu systemtapu. Varianty funkce
sprint* vracejí formátovaný řetězec namísto aby ho přímo vypisovaly.
print, sprint
Výpis jedné nebo více hodnot libovolného typu spojených dohromady.
println, sprintln
vypisují hodnoty stejně jako print a sprint, ale navíc připojují znak nového řádku.
printd, sprintd
Přijímají řetězcový oddělovač a dvě nebo více hodnot libovolného typu, a vytisknou je proložené
tímto oddělovačem. Oddělovačem musí být řetězcový literál - konstanta.
printdln, sprintdln
Vytisknou hodnoty proložené oddělovačem podobně jako printd a sprintd, ale zároveň připojí znak
konce řádku.
printf, sprintf
přijímají formátovací řetězec s množinou hodnot odpovídajících typů a všechny je vytisknou. Formá‐
tovacím řetězcem musí být řetězcový literál - konstanta.
Formátovací řetězec příkazu printf je podobný jako v jazyce C s tím, že zde probíhá typová kontrola.
%b Vypisuje binární blob dané hodnoty namísto ASCII textu. Specifikátor "width" určuje počet
bajtů k vypsání. Validní specifikace jsou: %b %1b %2b %4b %8b. Výchozí je (%b), t.j. 8 baj‐
tů.
%c Znak.
%d,%i Celé číslo se znaménkem.
%m Bezpečně čte paměť jádra na dané adrese, vrací její obsah. Volitelný specifikátor přesnosti
(ne šířky pole) určuje počet bajtů k přečtení. Výchozí hodnota je 1 bajt. %10.4m vytiskne 4
bajty paměti v rámci 10 znaků širokého pole.
%M Stejné jako %m, ale výstup je hexadecimální. Minimální šířka výstupu je určitelná volitel‐
ným specifikátorem r - výchozí hodnota je 1 bajt (2 hexadecimální znaky). %10.4M vytiskne 4
bajty paměti jako 8 hexadecimálních znaků v rámci 10 znaků širokého pole.
%o Oktalové číslo bez znaménka.
%p Ukazatel bez znaménka.
%s Řetězec.
%u Desítkové číslo bez znaménka.
%x Hexadecimální hodnota bez znaménka, malá písmena.
%X Hexadecimální hodnota bez znaménka, velká písmena.
%% Vypíše znak %.
Znak # zapíná alternativní formátování: Oktalovým číslům přidá prefix "0", hexadecimálním "0x", nebo
"0X", a netisknutelným znakům v řetězci přidá prefix "escape" sekvence.
Příklady:
a = "alice", b = "bob", p = 0x1234abcd, i = 123, j = -1, id[a] = 1234, id[b] = 4567
print("hello")
Vypíše: hello
println(b)
Vypíše: bob\n
println(a . " is " . sprint(16))
Vypíše: alice is 16
foreach (name in id) printdln("|", strlen(name), name, id[name])
Vypíše: 5|alice|1234\n3|bob|4567
printf("%c is %s; %x or %X or %p; %d or %u\n",97,a,p,p,p,j,j)
Vypíše: a is alice; 1234abcd or 1234ABCD or 0x1234abcd; -1 or 18446744073709551615\n
printf("2 bytes of kernel buffer at address %p: %2m", p, p)
Vypíše: 2 byte of kernel buffer at address 0x1234abcd: <binary data>
printf("%4b", p)
Vypíše (these values as binary data): 0x1234abcd
printf("%#o %#x %#X\n", 1, 2, 3)
Vypíše: 01 0x2 0X3
printf("%#c %#c %#c\n", 0, 9, 42)
Vypíše: \000 \t *
STATISTIKA
Často je výhodné sbírat statistická data způsobem, který netrpí problémy s exkluzivním zamykáním globál‐
ních proměnných, kde se data udržují. Systemtap nabízí řešení ve formě speciálního operátoru pro uchová‐
vání statistických dat a sady agregačních pseudofunkcí.
Agregační operátor je <<<, a připomíná přiřazení, nebo operaci pro zápis do výstupního proudu známou z
C++. Levý operand je skalární proměnná (nebo /skalární/ prvek pole - viz příklad níže), která musí být
deklarována jako globální. Pravým operandem je číselný výraz. Význam je intuitivní: Přidej dané číslo na
hromadu nad kterou bude později možno provádět statistické operace. Seznam funkcí pro extrakci statistic‐
kých údajů je uveden níže. Příklad:
foo <<< 1
stats[pid()] <<< memsize
Funkce pro extrakci statistiky jsou neobvyklé. Pro každý výskyt extrakční funkce pracující s daným iden‐
tifikátorem zajistí překladač výpočet požadovaného statistického údaje. Statistický subsystém tedy fungu‐
je "na požádání" a výpočet probíhá v reálném čase na všech dostupných CPU.
Zde je seznam extrakčních funkcí. Prvním argumentem každé z nich je ta stejná l-hodnota, která byla pou‐
žita pro akumulaci statistiky operátorem <<<. Extrakční funkce @count(v), @sum(v), @min(v), @max(v),
@avg(v), @variance(v[, b]) počítají počet, sumu, minimum, maximum, aritmetický průměr, a střední kvadra‐
tickou odchylku přes všechny nashromážděné hodnoty. Funkčními hodnotami jsou celá čísla. Pole obsahující
agregační data lze třídit a/nebo přes ně iterovat. Viz cyklus foreach výše.
Střední kvadratická odchylka se vyčísluje s použitím Welfordova algoritmu. Výpočty jsou prováděny v celo‐
číselné aritmetice, proto mohou trpět nízkou přesností. Pro zlepšení přesnosti lze využít volitelný para‐
metr b, tzv. bitový posun, s hodnotami od 0 (výchozí hodnota) do 62. Pro danou statistickou veličinu,
resp. jí odpovídající globální proměnnou ve skriptu, lze použít pouze jednu jedinou hodnotu bitového po‐
sunu. Vyšší hodnoty bitového posunu zvyšují přesnost, ale zároveň zvyšují riziko přetečení.
$ stap -e \
> 'global x probe oneshot { for(i=1;i<=5;i++) x<<<i println(@variance(x)) }'
12
$ stap -e \
> 'global x probe oneshot { for(i=1;i<=5;i++) x<<<i println(@variance(x,1)) }'
2
$ python3 -c 'import statistics; print(statistics.variance([1, 2, 3, 4, 5]))'
2.5
$
K přetečení může dojít zejména při interním násobení velkých čísel. Pokud k tomu dojde, může střední kva‐
dratická odchylka vycházet záporná, což je normálně nepřípustné. Zvažte normalizování vašich dat. Přičte‐
ní, či odečtení konstanty ke všem hodnotám statistického vzorku nemění hodnotu střední kvadratické od‐
chylky. Podělení všech hodnot statistického vzorku konstantou způsobí zmenšení střední kvadratické od‐
chylky o čtverec dané konstanty.
Dostupné jsou též histogramy. Například @hist_linear(v,start,stop,interval) reprezentuje lineární histo‐
gram od "start" do "stop" s inkrementem "interval". Inkrement musí být kladný. Podobně @hist_log(v) před‐
stavuje binárně logaritmický histogram. Histogram lze vytisknout některou z rodiny print funkcí. Výsled‐
kem je ASCII-art. Příklad:
probe timer.profile {
x[1] <<< pid()
x[2] <<< uid()
y <<< tid()
}
global x // pole
global y // skalár
probe end {
foreach ([i] in x @count+) {
printf ("x[%d]: avg %d = sum %d / count %d\n",
i, @avg(x[i]), @sum(x[i]), @count(x[i]))
println (@hist_log(x[i]))
}
println ("y:")
println (@hist_log(y))
}
PŘETYPOVÁNÍ
Jakmile se ukazatel uloží do celočíselné proměnné v rámci systemtap skriptu, překladač ztrácí informaci o
typu, která je potřebná k dereferencování.
(viz KONTEXTOVÉ PROMĚNNÉ man stránky stapprobes(3stap)). Použitím operátoru @cast() sdělujeme kompiláto‐
ru, jak má interpretovat takové číslo jakožto typovaný ukazatel. Příklad:
@cast(p, "type_name"[, "module"])->member
Takto bude p interpretován jako ukazatel do struktury/unionu type_name a dereferencovat member . Lze při‐
pojit další ->subfield a dereferencovat tak další úrovně. Poznamenejme, že pro přímé dereferencování uka‐
zatele se doporučuje použít funkcí {kernel,user}_{char,int,...}($p). Více v sekci stapfuncs(5).
POZNÁMKA: stejný operátor -> se používá jak pro přímý odkaz na člena, tak pro dereferenci ukazatele. Sys‐
temtap automaticky interpretuje tuto dvojakost. Volitelná složka module informuje překladač, kde má hle‐
dat informaci o daném typu. module lze uvést vícekrát jako seznam s oddělovačem :. Pokud module není ex‐
plicitně určen, budou pro jeho určení využity ladicí informace, nebo bude nastaven na "kernel" pro funkce
a všechny ostatní typy sond.
Překladač může vytvořit svůj vlastní modul s informacemi o typech odvozením z hlavičkových souborů uza‐
vřených ve špičatých závorkách v případě, že ladicí informace nejsou k dispozici. Hlavičkovým souborům
jádra je třeba přidat řetězec "kernel" jako předponu. Ostatní hlavičkové soubory budou zpracovány s vý‐
chozími volbami kompilátoru. Lze specifikovat více hlavičkových souborů za sebou pro vyřešení závislostí.
@cast(tv, "timeval", "<sys/time.h>")->tv_sec
@cast(task, "task_struct", "kernel<linux/sched.h>")->tgid
@cast(task, "task_struct",
"kernel<linux/sched.h><linux/fs_struct.h>")->fs->umask
Hodnoty získané operátorem @cast lze přehledně vytisknout (pretty-print) připojením operátoru $ a $$ jak
je popsáno v sekci KONTEXTOVÉ PROMĚNNÉ man stránky stapprobes(3stap).
V guru režimu (-g) umožňuje překladač také přiřadit novou hodnotu dereferencovaným ukazatelům.
Přetypování je také užitečné v případě void* členů jejichž typ lze určit až za běhu. Příklad:
probe foo {
if ($var->type == 1) {
value = @cast($var->data, "type1")->bar
} else {
value = @cast($var->data, "type2")->baz
}
print(value)
}
EMBEDDED C
V guru režimu přijímá překladač vložený C kód v uživatelských skriptech. Takový kód je uzavřen mezi znač‐
kami %{ a %} a je doslovně, bez analýzy, vložen do vnější úrovně vygenerovaného kódu systemtap modulu.
Protože je vložen do vnější úrovně, je možné takto definovat #include direktivy a různé pomocné definice
použitelné ve zbytku kódu.
Dalším místem, kde je vložené C povoleno, je tělo funkce. V tomto případě bude tělo systemtap funkce do‐
slovně tvořeno vloženým C kódem uzavřeným mezi značky %{ a %}. Takto vložený C kód může vykonávat libo‐
volnou rozumnou a bezpečnou činnost. Existuje množství nedokumentovaných a komplexních omezení ohledně
atomicity, souběžnosti, spotřeby zdrojů a časových omezení, takže jde o pokročilou techniku.
Paměťová umístění vyhrazená pro vstupní a výstupní hodnoty jsou zpřístupněna pomocí maker STAP_ARG_* a
STAP_RETVALUE. Chyby lze signalizovat pomocí STAP_ERROR, výstup pomocí STAP_PRINTF a návratovou hodnotu
lze předat prostřednictvím STAP_RETURN. Zde je několik příkladů:
function integer_ops (val) %{
STAP_PRINTF("%d\n", STAP_ARG_val);
STAP_RETVALUE = STAP_ARG_val + 1;
if (STAP_RETVALUE == 4)
STAP_ERROR("wrong guess: %d", (int) STAP_RETVALUE);
if (STAP_RETVALUE == 3)
STAP_RETURN(0);
STAP_RETVALUE ++;
%}
function string_ops (val) %{
strlcpy (STAP_RETVALUE, STAP_ARG_val, MAXSTRINGLEN);
strlcat (STAP_RETVALUE, "one", MAXSTRINGLEN);
if (strcmp (STAP_RETVALUE, "three-two-one"))
STAP_RETURN("parametr měl být be three-two-");
%}
function no_ops () %{
STAP_RETURN(); /* funkce bez návratové hodnoty */
%}
Typy funkčních hodnot a typ návratové hodnoty odvodí překladač ze způsobu volání dané funkce. Před vytvá‐
řením vlastních vložených C funkcí je vhodné prostudovat zdrojový kód, který překladač generuje pro běžné
funkce skriptovacího jazyka a tím se inspirovat.
Poslední místo, kde je vložené C povoleno, je r-hodnota ve výrazu. V tomto případě se C-kód uzavře mezi
značky %{ a %} a interpretuje se jako běžná hodnota výrazu. Předpokládá se pak, že jde o 64 bitové číslo
se znaménkem, ovšem pokud se použije značka /* string */, bude hodnota výrazu interpretována jako řetě‐
zec. Příklad:
function add_one (val) {
return val + %{ 1 %}
}
function add_string_two (val) {
return val . %{ /* string */ "two" %}
}
K nastavení bezpečnosti a optimalizace lze použít následující značky:
/* pure */
znamená, že C kód nemá žádné vedlejší efekty a může být v rámci optimalizace zcela zahozen pokud
nemá vazby na zbytek kódu.
/* stable */
znamená, že C kód má vždy stejnou hodnotu (při vyvolání v rámci libovolné obslužné rutiny sondy),
takže opakovaná volání mohou být nahrazena zapamatovanou hodnotou. Takové funkce nesmí přijímat
parametry a musí být /*pure*/.
/* unprivileged */
znamená, že C kód je tak bezpečný, že ho mohou používat i neprivilegovaní uživatelé.
/* myproc-unprivileged */
znamená, že C kód je tak bezpečný, že ho mohou používat i neprivilegovaní uživatelé, ovšem jen při
analýze svých vlastních uživatelských procesů.
/* guru */
znamená, že C kód je tak nebezpečný, že vyžaduje použití guru režimu -g.
/* unmangled */
ve vložené C funkci zpřístupní zastaralou (pre-1.8) syntaxi pro přístup k funkčním parametrům. V
tomto případě lze uvnitř funkce kromě STAP_ARG_foo a STAP_RETVALUE použít také THIS->foo a
THIS->__retvalue .
/* unmodified-fnargs */
ve vložené C funkci znamená, že parametry nejsou uvnitř těla funkce měněny.
/* string */
ve vložené C funkci znamená, že výraz má typ const char * a mělo by s ním být nakládáno jako s ře‐
tězcovou hodnotou namísto numerické (což je výchozí chování).
BUILT-INS
Skripty instalované v umístění definovaném ve stappaths(7) poskytují množství vestavěných sondážních bo‐
dů. Ty jsou popsány v man stránce stapprobes(3stap).
ZPRACOVÁNÍ SKRIPTU
Systemtap zpracovává skript v pěti procesních fázích: "parse", "elaborate", "translate", "compile" a
"run". Překladač zahájí fázi 1 lexikální analýzou uživatelského skriptu spolu se všemi tapset skripty
(což jsou soubory s příponou *.stp) nalezenými v tapset adresáři. Adresáře vyjmenované prostřednictvím -I
jsou následně zpracovány také, a to v guru režimu. Adresářová struktura se prohledává do hloubky. Některé
podadresáře jsou specifické pro verzi jádra (volba -R ), a podle ní jsou (nebo nejsou) prohledávány, tak‐
že skripty specifičtější pro danou verzi jádra mohou předefinovat své méně specifické protějšky. Napří‐
klad pro verzi jádra 2.6.12-23.FC3 by byly prohledávány následující adresáře: 2.6.12-23.FC3/*.stp,
2.6.12/*.stp, 2.6/*.stp, a nakonec *.stp v tomto pořadí. Pokud překlad skončí na konci fáze 1 (-p1), pak
překladač na standardní výstup vypíše derivační strom (parse tree).
Ve fázi 2 překladač analyzuje vstupní skript, aby vyhodnotil symboly a datové typy. Odkazy na proměnné,
funkce a přezdívky, které se nepodaří vyhodnotit lokálně, se vyhodnotí proti tapset skriptům. Pokud je
určitý symbol nalezen v tapset skriptu, pak daný tapset bude celý přidán do fronty pro zpracování překla‐
dačem. Tento iterativní proces skončí jakmile jsou vyhodnoceny všechny symboly s využitím dané podmnožiny
tapset skriptů.
Dále se ověří validnost sondážních bodů. Sondy, které se odkazují k umístěním ve zdrojovém kódu ("syn‐
chronní sondážní body") vyžadují, aby byly nainstalovány příslušné ladicí informace. V obslužných ruti‐
nách sond se naleznou cílové proměnné (ty, které začínají znakem "$") a dekódují se jejich "run-time" lo‐
kace.
Dále se všechny sondy a funkce optimalizují. Cílem je odstranit zbytečné proměnné, výrazy a funkce, které
nemají vedlejší účinky. U vložených C funkcí se předpokládá, že mají vedlejší účinky pokud ovšem neobsa‐
hují kouzelnou značku /* pure */. Vzhledem k tomu, že optimalizace mohou způsobit latentní chyby jako je
například typová nekompatibilita, nebo neplatné kontextové proměnné, může být v některých případech uži‐
tečné optimalizace vypnout přepínačem -u.
Nakonec se z kontextu odvodí datové typy proměnných, funkcí, parametrů, polí a indexů. Ukončení překladu
po fázi 2 (-p2) způsobí vypsání seznamu všech sond, funkcí a proměnných spolu s jejich odvozenými typy.
Nekonzistentní nebo neodvoditelné typy způsobí chybu překladu.
Ve fázi 3 překladač zapíše vygenerovaný C kód a vytvoří Makefile který slouží k jeho přeložení do podoby
jaderného modulu. Tyto soubory budou umístěny v dočasném adresáři. Zastavení překladače v této fázi (-p3)
způsobí vypsání C souboru na standardní výstup.
Ve fázi 4 překladač vyvolá jaderný "build systém", aby sestavil systemtap modul. Při tom se v daném do‐
časném adresáři volá příkaz make. K úspěšnému provedení tohoto kroku je třeba, aby byl nainstalován "bu‐
ild systém" jádra, tj. hlavičkové soubory, config a Makefile soubory a to v obvyklém umístění /lib/modu‐
les/VERSION/build. Zastavení překladače v této fázi (-p4) může být užitečné, pokud chceme modul archivo‐
vat. Je to také poslední šance zastavit systemtap před zavedením a spuštěním modulu.
Ve fázi 5 překladač zavolá pomocný program staprun a předá mu vzniklý systemtap modul. Program staprun
zavede modul do jádra, spustí jej a zajišťuje komunikaci s ním dokud činnost modulu neskončí. Jakákoliv
chyba běhu, která se vyskytne v obslužných rutinách sond, jako např. vyčerpání dostupné paměti, dělení
nulou, příliš hluboké zanoření, nebo překročení "run-time" limitů, způsobí měkkou chybu (soft error). Po‐
kud počet měkkých chyb překročí MAXERRORS, zastaví se všechny sondy (kromě těch, které obsluhují chyby),
a zastaví se sezení. Nakonec staprun odstraní modul z jádra a provede úklid.
NEOBVYKLÉ UKONČENÍ
Je dobré neukončovat stap proces násilím, například prostřednictvím signálu SIGKILL, protože proces sta‐
pio (potomek procesu stap) a systemtap modul by se nemusely korektně ukončit. Pokud se to přecejen stane,
pošlete všem zbývajícím stapio procesům SIGTERM nebo SIGINT a použijte rmmod pro odstranění systemtap mo‐
dulu z jádra.
PŘÍKLADY
Viz stapex(3stap) , kde se nachází několik krátkých příkladů, nebo viz adresář "examples" v RPM balíčcích
"systemtap-client", či "systemtap-testsuite", kde se nachází rozsáhlá sbírka příkladů. Viz stap‐
paths(7stap) pro podrobný popis konkrétních umístění. Příklady jsou také zveřejněny na webové stránce
projektu systemtap.
CACHE
Překladač systemtapu ukládá do cache výstup fáze 3 (tj. vygenerovaný C kód) a výstup fáze 4 (tj. zkompi‐
lovaný jaderný modul) pokud tyto fáze skončí bez chyb. Obsah cache se použije pokud se znovu překládá
stejný skript a za předpokladu, že platí stejné podmínky (verze jádra, verze systemtapu atp.). Cache se
nachází v adresáři $SYSTEMTAP_DIR/cache . Velikost cache lze omezit umístěním souboru cache_mb_limit do
cache adresáře, přičemž tento soubor obsahuje ASCII číselnou hodnotu limitu, která vyjadřuje velikost
cache v MiB. Pokud tento soubor neexistuje, vytvoří se nový s výchozí hodnotou 256. Jde o měkký limit v
tom smyslu, že cache bude promazána až po určité době. Dočasně tedy může velikost cache překročit stano‐
vený limit. Zmíněnou periodu je možno nastavit prostřednictvím souboru cache_clean_interval_s umístěného
opět v cache adresáři. Předpokládá se, že tento soubor obsahuje ASCII celé číslo vyjadřující časový in‐
terval pro promazávání cache v sekundách. Pokud tento soubor neexistuje, vytvoří se nový s výchozí hodno‐
tou 300.
BEZPEČNOST A OCHRANA SOUKROMÍ
Systemtap může být použit jako mocný administrativní nástroj. Může zpřístupnit privátní uživatelské in‐
formace v rámci interních jaderných struktur. To se netýká dyninst runtime, viz ALTERNATIVNÍ RUNTIME .
Překladač zajišťuje dodržování mnoha různých bezpečnostních omezení během kompilace a běhu modulu. Snaží
se zajistit, aby žádná sonda neběžela příliš dlouho, aby nealokovala příliš mnoho paměti, neprováděla ne‐
bezpečné operace, nebo nežádoucím způsobem neovlivňovala systém. Při práci s globálními proměnnými se vy‐
užívají zámky pro čtení a zápis, aby nedocházelo k chybám při souběhu. Pravidelně dochází k testu na de‐
adlocky. Pro zjištění nepřiměřeného použití zámků lze použít přepínač -t. Experimentování se skripty je
tedy v zásadě bezpečné. Guru"režim -g umožňuje administrátorům obejít většinu bezpečnostních opatření a
umožnit tak invazivní zásahy a změny stavu systému, použít vložené C a obecně zvýšit riziko průšvihu. Za
normálních okolností je pro všechny moduly aktivní ochrana proti přetížení. Tu lze vypnout přepínačem
--suppress-time-limits.
Chyby zachycené při běhu za normálních okolností vedou k čistému ukončení skriptu s chybovou hláškou.
Přepínač --suppress-handler-errors umožňuje zcela ignorovat měkké chyby, takže ani po nastřádání jejich
většího počtu nedojde k ukončení skriptu.
OPRÁVNĚNÍ
Aby bylo možné spustit systemtap modul v rámci výchozí kernel runtime, musí uživatel splnit jednu z ná‐
sledujících podmínek:
• být root.
• být členem skupin stapdev a stapusr
• být členem skupin stapsys a stapusr ; nebo
• být členem skupiny stapusr .
Uživatel root, nebo uživatel, který je členem skupin stapdev a stapusr , může přeložit a spustit libovol‐
ný systemtap skript.
Uživatel, který je členem skupin stapsys a stapusr, může použít předem připravené systemtap moduly za ná‐
sledujících podmínek:
• Modul byl podepsán kompilačním serverem "trusted signer", tj. systemtap kompilačním serverem, který
podepsal modul klientovi, který použil volbu --privilege. Viz stap-server(8).
• Modul byl sestaven s použitím jedné z voleb --privilege=stapsys nebo --privilege=stapusr.
Členové pouze skupiny stapusr mohou používat jen předem připravené moduly za následujících podmínek:
• Modul je umístěn v adresáři /lib/modules/VERSION/systemtap. Tento adresář musí být vlastněn uživate‐
lem root a nesmí být otevřený pro zápis všem.
nebo
• Modul byl podepsán kompilačním serverem "trusted signer", tj. systemtap kompilačním serverem, který
podepsal modul klientovi, který použil volbu --privilege. Podrobnější informace viz stap-server(8).
• Modul byl přeložen s volbou --privilege=stapusr.
Jaderné moduly vygenerované programem stap se zavádějí do jádra a spouštějí pomocí programu staprun. Sta‐
prun je součástí systemtap balíčku určeného k zavádění a odstraňování modulů (za daných podmínek). Slouží
také k přenosu dat mezi systemtap modulem a uživatelelm. Protože staprun neprovádí žádné bezpečnostní
kontroly modulu se kterým pracuje, bylo by od administrátora systému nemoudré přidat nedůvěryhodného uži‐
vatele do skupiny stapdev nebo stapusr .
SECUREBOOT
Pokud má systém v rámci UEFI firmware zapnutý SecureBoot, všechny jaderné moduly musejí být kryptografic‐
ky podepsány. (Některá jádra dovolují vypnout SecureBoot za běhu kombinací kláves SysRq-X. Poté nemusí
být moduly podepsané.) Kompilační server systemtapu může podepisovat moduly klíčem MOK (Machine Owner
Key) který sdílí s daným systémem. Pro více informací viz následující wiki:
https://sourceware.org/systemtap/wiki/SecureBoot
LIMITY NA ZDROJE
Mnoho omezení pro využívání prostředků systému se nachází ve formě maker ve vygenerovaném C kódu system‐
tap modulu. Ty lze předefinovat prostřednictvím přepínače -D. Seznam zmíněných maker:
MAXNESTING
Maximální počet zanořených funkčních volání. Výchozí hodnota se určuje při analýze skriptu. Skrip‐
ty založené na rekurzi obdrží 10 bonusových slotů.
MAXSTRINGLEN
Maximální délka řetězce. Výchozí hodnota je 128 znaků.
MAXTRYLOCK
Maximální počet iterací při čekání na uvolnění zámku na globální proměnné před tím, než se vyhlásí
deadlock a sonda se přeskočí. Výchozí hodnota je 1000 iterací.
MAXACTION
Maximální počet příkazů, které mohou být vykonány během jednoho hitu sondy (s vypnutými přerušení‐
mi). Výchozí hodnota je 1000.
MAXACTION_INTERRUPTIBLE
Maximální počet příkazů, které mohou být vykonány během jedné aktivace (probe hit) sondy, která se
provádí s povolenými přerušeními. (jako např. sondy begin a end). Výchozí hodnota je 10 * MAXACTI‐
ON.
MAXBACKTRACE
Maximální počet zásobníkových rámců, které budou zpracovány při výpisu backtrace. Relevantní tap‐
set je [u]context-unwind.stp, a výchozí hodnota je 20.
MAXMAPENTRIES
Maximální počet řádků v každém jednom globálním poli. Výchozí hodnota je 2048. Jednotlivá pole mo‐
hou být deklarována s odlišným limitem. Příklad:
global big[10000],little[5]
nebo je možno využít modifikátoru % , čímž se zapne array-wrapping (nahrazování "starých" prvků)
jako v následujícím příkladu:
global big%
Viz sekce o polích.
MAXERRORS
Maximální množství měkkých chyb, které ještě nezpůsobí ukončení skriptu. Výchozí hodnotou je 0,
tedy skript skončí při první měkké chybě. Poznamenejme, že --suppress-handler-errors tento limit
vypíná.
MAXSKIPPED
Maximální počet přeskočených sond, který ještě nevede k ukončení skriptu. Výchozí hodnotou je 100.
Pozn., že systemtap lze spustit s přepínačem -t (timing), který zobrazí podrobnosti ohledně počtu
přeskočených sond. Při použití -DINTERRUPTIBLE=1 se nebudou brát v potaz sondy přeskočené kvůli
re-entranci. Dále poznamenejme, že --suppress-handler-errors vypíná i tento limit.
MINSTACKSPACE
Minimální množství volného místa na zásobníku jádra dostatečné pro start sondy. Výchozí hodnota
1024 bajtů. Tato hodnota by měla být dostačující pro vlastní potřebu obslužné rutiny včetně malé
rezervy.
MAXUPROBES
Maximální množství současně zamčených uživatelských sond (uprobes). Výchozí hodnota je o něco málo
vyšší, než počet uživatelských sond ve skriptu. Tato hodnota musí být relativně velká, protože
jednotlivé uživatelské sondy (každá z nich okupuje přibližně 46 bajtů), se alokují pro každý pro‐
ces a pro každou odpovídající sondu ve skriptu.
STP_MAXMEMORY
Maximální velikost paměti (v kilobajtech), kterou je systemtap modul oprávněn použít. Výchozí hod‐
nota je neomezená. Limit zahrnuje velikost modulu samotného plus dodatečné alokace. Zahrnuty jsou
jen přímé alokace provedené systemtap runtime. Nepřímé alokace, které provádějí např, "kprobes",
"uprobes", atd., nejsou započteny.
STP_OVEROAD_THRESHOLD, STP_OVERLOAD_INTERVAL
Maximální počet cyklů, které lze strávit v sondách za daný čas (též vyjádřený v cyklech). Při pře‐
kročení této podmínky dojde k přetížení a skript se zastaví. Výchozí hodnoty jsou 5e+8 a 1e+9, což
odpovídá max. 50% povolenému vytížení.
STP_PROCFS_BUFSIZE
Velikost procfs bufferů pro čtení (v bajtech). Výchozí hodnota je
MAXSTRINGLEN. Tento limit lze nastavit specificky pro jednotlivé sondy pomocí syntaxe .maxsize(MA‐
XSIZE) .
Pokud skript obsahuje sondy vázané na přerušení, je možné, že k přerušení dojde tak často, že handler da‐
ného přerušení ještě nedoběhne zatímco dojde k dalšímu přerušení. V tomto případě bude obslužná rutina
přeskočena, aby se zamezilo reentranci. Tento problém lze obejít použitím -DINTERRUPTIBLE=0kodstíněníbě‐
žícíobslužnérutinyoddanéhopřerušení. Tento přístup přináší jistou režii, ale v běžných případech zamezí
reentranci. Nicméně, sondy v NMI handlerech a v samotném procesu stap, mohou stále být přeskočeny, aby se
zamezilo reentranci.
Vznikne-li problém při běhu programu stap nebo staprun když už sondy běží, je možné bezpečně zabít oba
tyto uživatelské procesy a odstranit systemtap modul pomocí rmmod. Část výstupu se tak nicméně může ztra‐
tit.
NEPRIVILEGOVANÍ UŽIVATELÉ
Systemtap umožňuje přístup k interním datům jádra a tedy potenciálně k soukromým datům uživatele. Z toho‐
to důvodu je plný přístup k systemtapu omezen na uživatele root a na uživatele, kteří jsou členy skupin
stapdev a stapusr.
Nicméne omezená sada funkcí systemtapu může být dostupná důvěryhodným neprivilegovaným uživatelům. Tito
uživatelé jsou členy pouze skupiny stapusr plus případně skupiny stapsys.
Tito uživatelé mohou zavést do jádra předem připravený modul, který byl podepsán důvěryhodným kompilačním
serverem. Viz popis voleb --privilege a --use-server. Viz také README.unprivileged mezi zdrojovými soubo‐
ry systemtapu. Tam je mj. popsáno jak nastavit důvěryhodný kompilační server.
Omezení která plynou z volby --privilege=stapsys mají zabránit neprivilegovaným uživatelům v
• záměrném poškozování systému.
Omezení, která plynou z volby --privilege=stapusr mají zabránit neprivilegovaným uživatelům v
• záměrném poškozování systému.
• získání přístupu k neveřejným / soukromým informacím.
• snižování výkonu procesů vlastněných jinými uživateli systému. Určitému vlivu na výkon celého
systému nelze zabránit, neboť sondy neprivilegovaného uživatele budou v příslušný čas aktivní.
Nicméně hlavním cílem zde je, aby neprivilegovaný uživatel nežádoucím nezpůsobem zasahoval do
procesů jiných uživatelů.
OMEZENÍ NA SONDY
Člen skupin stapusr a stapsys má přístup ke všem sondám.
Člen pouze skupiny stapusr může použít následující sondy:
• begin, begin(n)
• end, end(n)
• error(n)
• never
• process.*, s tím, že cílový proces je jeho vlastní.
• timer.{jiffies,s,sec,ms,msec,us,usec,ns,nsec}(n)*
• timer.hz(n)
OMEZENÍ SKRIPTOVACÍHO JAZYKA
Následující vlastnosti skriptovacího jazyka jsou pro neprivilegovaného uživatele nedostupné:
• jakákoliv funkcionalita podmíněná guru režimem (-g).
• vložený C kód.
RUNTIME OMEZENÍ
Neprivilegovaných uživatelů se týkají také následující omezení runtime:
• Lze použít jen výchozí runtime kód (viz -R).
Na členy pouze skupiny stapusr se vztahují dodatečná omezení:
• Analýza procesů vlastněných jinými uživateli není dovolena.
• Přístup do paměti jádra není dovolen ani pro zápis, ani pro čtení.
OMEZENÍ NA VOLBY PŘÍKAZOVÉ ŘÁDKY
Některé volby příkazové řádky poskytují přístup k funkcionalitě, která nesmí být přístupná žádnému nepri‐
vilegovanému uživateli. Konkrétně
• Nesmí nastavit -g .
• Následující volby nesmějí být použity klientem kompilačního serveru:
-a, -B, -D, -I, -r, -R
OMEZENÍ NA PROMĚNNÉ PROSTŘEDÍ
Neprivilegovaní uživatelé nesmějí nastavit následující proměnné prostředí:
SYSTEMTAP_RUNTIME
SYSTEMTAP_TAPSET
SYSTEMTAP_DEBUGINFO_PATH
OMEZENÍ NA TAPSETY
Obecně jsou tapset funkce přístupné členům skupiny stapusr pokud nepřistupují k informacím, které by ne‐
měl právo získat libovolný uživatelský program běžící s identitou daného uživatele.
Existují dvě skupiny tapset funkcí pro neprivilegované uživatele. První kategorie sestává z funkcí, které
mohou použít všichni uživatelé, jako napřiklad:
cpu:long ()
exit ()
str_replace:string (prnt_str:string, srch_str:string, rplc_str:string)
Druhou skupinou jsou tzv. myproc-unprivileged funkce, které mohou sbírat informace pouze o procesech,
které daný uživatel vlastní. Skripty, které mají používat myproc-unprivileged funkce musí testovat is_my‐
proc() a volat takové funkce jen když výsledek je 1. Skript se ihned ukončí, pokud tato podmínka nebude
splněna. Přiklady myproc-unprivileged funkcí:
print_usyms (stk:string)
user_int:long (addr:long)
usymname:string (addr:long)
Pokud se uživatel patřící pouze do skupiny stapusr pokusí použít tapset funkci, která nespadá do žádné ze
zmíněných dvou kategorií, dojde k chybě při kompilaci.
ALTERNATIVNÍ RUNTIME BACKENDY
Jak již bylo zmíněno, systemtap používá jako výchozí tzv. "kernel runtime backend", který pracuje na
principu jaderného modulu. To přináší výše zmíněná bezpečnostní úskalí. Systemtap nově obsahuje dva pro‐
totypy nových "backendů", které lze aktivovat volbami --runtime=dyninst a --runtime=bpf.
--runtime=dyninst využívá Dyninst a lze jej použít k instrumentaci uživatelských procesů. Není založen na
bázi jaderných modulů a nevyžaduje rootovské oprávnění. Zůstávají v něm ale v platnosti omezení na povo‐
lené typy sond.
Dyninst backend pracuje v režimu připojení se k cílovému procesu, proto vyžaduje volbu -c COMMAND, nebo
-x PID process. Napřiklad:
stap --runtime=dyninst -c "stap -V" \
-e "probe process.function("main")
{ println("hi from dyninst!") }"
Pro správnou funkci dyninst runtime může být nezbytné zapnout na cílovém systému SELinux volbu
allow_execstack:
# setsebool allow_execstack 1
--runtime=bpf překládá systemtap skript na extended Berkeley Packet Filter (eBPF) program. Linuxové jádro
kontroluje eBPF programy z hlediska bezpečnosti, a spouští je na svém interním virtuálním stroji. Tento
"runtime backend" je v časné fázi vývoje, a momentálně trpí řadou omezení, viz stapbpf(8).
NÁVRATOVÝ KÓD
V případě úspěšného běhu vrátí příkaz stap kód 0 (exit code). V opačném případě se na standardní chybový
výstup může vypsat chybová hláška a stap vrátí nenulový kód. Pro zvýšení upovídanosti použijte -v nebo
-vp N .
V "listing" režimu (-l and -L), se chyby obvykle potlačují. Pokud byla nalezena alespoň jedna sonda vyho‐
vující zadaným požadavkům, stap skončí s návratovým kódem 0.
Skript, který skončí svůj běh na žádost uživatele použitím ^C / SIGINT, se považuje za úspěšně ukončený.
ZASTARÁVÁNÍ
Během vývoje systemtapu dochází občas ve skriptovacím jazyce k nekompatibilním změnám, takže staré skrip‐
ty mohou přestat fungovat. V takovém případě může pomoci volba --compatible VERSION kde se určí poslední
známá verze systemtapu, se kterou daný skript fungoval.
Při použití volby --check-version vypíše systemtap varování pokud narazí při lexikální analýze na nekom‐
patibilní element. Informace o zastarávání se udržují v souboru NEWS.
Smyslem mechanizmu zastarávání je přinést žádoucí inovace skriptovacího jazyka a současně nerozbít kompa‐
tibilitu se starými existujícími skripty. Mechanizmus zastarávání by tedy měl být chápán především jako
služba přinášející pohodlí uživatelům (a nepohodlí vývojářům) spíše než naopak.
Poznamenejme, že tapset identifikátory s předponou "_" jsou považovány za interní a občas podstupují změ‐
ny při kterých je těžké zaručit zpětnou kompatibilitu i při použití mechanizmu zastarávání. V případě po‐
třeby, prosím, navrhněte takový symbol k regulernímu zveřejnění.
SOUBORY
Důležité soubory a jim příslušné cesty dokumentuje manuálová stránka stappaths (7).
VIZ TAKÉ
stapprobes(3stap),
function::*(3stap),
probe::*(3stap),
tapset::*(3stap),
stappaths(7),
staprun(8),
stapdyn(8),
systemtap(8),
stapvars(3stap),
stapex(3stap),
stap-server(8),
stap-prep(1),
stapref(1),
awk(1),
gdb(1)
CHYBY
Prosím, použijte následující bugzilla link, nebo náš mailing list. http://sourceware.org/systemtap/,
<systemtap@sourceware.org>.
error::reporting(7stap), https://sourceware.org/systemtap/wiki/HowToReportBugs
STAP(1)