SYSTEMTAP

JMÉNO

POUŽITÍ

POPIS

Existují volby a parametry, které ovlivňují globální chování služby nebo jednotlivých skriptů. Mezi skripty lze vytvořit závislosti, tak že nastartování jednoho automaticky způsobí nastartování jiného.

Konfigurační soubor initskriptu se nachází v ${prefix}/etc/systemtap/config. Přijatelné parametry jsou detailně popsány v sekci GLOBÁLNÍ PARAMETRY.

Skript musí být umístěn v adresáři ${prefix}/etc/systemtap/script.d a musí mít příponu .stp. Poznamenejme, že když se systemtap skripty pouštějí z příkazové řádky, jak je obvyklé, není přípona .stp povinná. Jméno skriptu smí obsahovat jen alfanumerické znaky a '_', a nesmí začínat číslem. Adresář pro skripty lze změnit nastavením parametru SCRIPT_PATH v konfiguračním souboru.

PŘÍKAZY

start

Start skriptů. Pokud žádné skripty nebyly určeny, nastartují se skripty určené nastavením DEFAULT_START. Pokud DEFAULT_START není nastaveno, nastartují se všechny skripty v adresáři skriptů. Pro skripty, které již běží se příkaz "start" ignoruje. Příkaz "start" selže, pokud start skriptů selže (viz též nastavení PASSALL).

Pokud je zapnutá volba AUTOCOMPILE, příkaz se pokusí sestavit (nebo obnovit sestavení) skriptů v případě, že je platná jedna z následujících podmínek:

-

Cache se zkompilovanými skripty neexistuje.

-

Čas modifikace (mtime) původního skriptu se změnil.

-

Skript se spouští s jinými volbami.

-

Změnil se výstup `uname -a`.

stop

Zastavit skripty. Pokud žádné skripty nebyly určeny, zastaví se všechny běžící skripty. Pro skripty, které neběží, se tento příkaz bude ignorovat. Příkaz selže pokud selže zastavení některého ze skriptů (viz též nastavení PASSALL).

restart

Zastavit a opět nastartovat skripty.

status

Zobrazit stav skriptů a jejich závislosti.

compile

Přeložit skripty, ale nestartovat je. Pokud skripty již byly přeloženy, dotázat se na potvrzení dříve, než dojde k přepsání cache. Kompilovat pro běžící jádro, nebo pro jádro určené prostřednictvím volby -r.

onboot

Učinit určené skripty součástí initramfs, aby mohly být spuštěny během startu stroje. Tento příkaz je dostupný jen na systémech, které používají dracut. Pokud se neurčí žádný skript, všechny systemtap skripty se z initramfs odstraní.

Initramfs se vytváří pro aktuální jádro, nebo pro jádro určené volbou -r. Výchozí umístění initramfs je /boot/initramfs-KVER.img, kde KVER odpovídá výstupu `uname -r`. Příkaz "onboot" dále obnoví nastavení zavaděče systému tak, aby byl použit nový initramfs. Pokud se má vytvořit initramfs v jiném umístění, použijte volbu -o. V tomto případě se nastavení zavaděče systému nezmění.

Pokud výstupní soubor již existuje, bude přepsán pokud není dán přepínač -b , kdy se původnímu souboru přidá přípona .bak namísto přepsání. Pokud ale .bak soubor již existuje, nebude přepsán.

UPOZORNĚNÍ: Nepoužívejte volbu -o příkazu stap(1) u "onboot" skriptů, protože skript poběží dříve, než se namountuje kořenový souborový systém. Pokud potřebujete více místa pro výstup, zvětšete velikost bufferu.

cleanup

Odstranit specifikované skripty z cache. Pokud není specifikován žádný skript, budou smazány všechny. Smaže se jen cache pro aktuální jádro, nebo pro jádro určené volbou -r. Před smazáním cache bude požadováno potvrzení.

VOLBY

-c CONFIG_FILE

Určuje alternativní konfigurační soubor.

-R

Při použití s start a stop příkazy značí, že mají být vzaty v potaz závislosti mezi skripty a to rekurzivně.

-r KERNEL_RELEASE

Při použití s compile, onboot, a cleanup příkazy, určuje cílové jádro. Formát KERNEL_RELEASE musí odpovídat formátu `uname -r`.

-y

Odpověz ano na všechny dotazy.

-o PATH.IMG

Při použití s příkazem onboot určuje umístění initramfs. Pokud se určí, konfigurace zavaděče se nezmění. Pokud určen není, konfigurace zavaděče se změní tak, aby byl při následujícím startu použit nový initramfs.

-b

Při použití s příkazem onboot, zazálohuje existující initramfs připojením přípony .bak namísto aby existující initramfs přepsal, což se stane není-li tato volba použita.

GLOBÁLNÍ PARAMETRY

SCRIPT_PATH

Určuje absolutní cestu adresáře pro skripty, se kterými může služba pracovat. Skripty musí mít příponu .stp. Výchozí hodnota je ${prefix}/etc/systemtap/script.d.

CONFIG_PATH

Určuje absolutní cestu adresáře pro konfigurační soubory skriptů. Tyto konfigurační soubory obsahují volby specifické pro jednotlivé skripty. Musí mít příponu .conf. Výchozí umístění je ${prefix}/etc/systemtap/conf.d.

CACHE_PATH

Umístění cache adresáře. Výchozí umístění je ${prefix}/var/cache/systemtap.

TEMP_PATH

Umístění dočasného adresáře, kam systemtap odkládá dočasné soubory, které vznikají při kompilaci systemtap jaderného modulu. Výchozí umístění je /tmp.

STAT_PATH

Absolutní cesta k adresáři se stavovými soubory pro jednotlivé skripty. Výchozí umístění je ${prefix}/var/run/systemtap.

LOG_FILE

Absolutní cesta k logovacímu souboru. Všechny zprávy se posílají do tohoto souboru (včetně kompilačních chybových hlášení a hlášení o chybách běhu). Výchozí umístění je ${prefix}/var/log/systemtap.log.

PASSALL

Pokud tato volba je nastavena (yes), pak systemtap služba pracující s mnoha skripty zahlásí chybu, pokud kterýkoliv ze skriptů zhavaruje. Pokud tato volba není nastavena (no) vypíše systemtap služba v takovém případě jen varování.

RECURSIVE

Pokud tato volba je nastavena (yes), služba systemtap bude brát v potaz závislosti mezi skripty a to rekurzivně (odpovídá volbě -R). Tato volba je platná jen pokud byly na příkazové řádce určeny skripty. Výchozí hodnota je no.

AUTOCOMPILE

Pokud je tato volba nastavena (yes), služba systemtap se pokusí zkompilovat určené skripty pokud nenalezne odpovídající validní položky v cache. Jinak související příkaz selže. Výchozí hodnota je yes.

DEFAULT_START

Určuje skripty, které se mají nastartovat jako výchozí. Pokud je tato volba vynechána (nebo nastavena na prázdnou hodnotu), nastartují se všechny skripty v adresáři. Výchozí hodnota je "".

ALLOW_CACHEONLY

Pokud je tato volba nastaveba (yes), služba umožní nastartování také skriptům, pro něž existují v cache validní data, ale v adresáři pro skripty jejich zdrojový kód chybí. Výchozí hodnota je no.

VAROVÁNÍ: S touto volbou může služba nastartovat neočekávané skripty nacházející se v cache. Před startem služby je vhodné obsah cache zkontrolovat.

LOG_BOOT_ERR

Protože "boot-time" skripty se spouštějí dříve než je namountován kořenový souborový systém, nelze chybový výstup programy staprun posílat do LOG_FILE jak je obvyklé. Nicméně log lze přesměrovat do /run/systemtap/$script.log nastavením LOG_BOOT_ERR na yes. Pokud STAT_PATH je odlišná od výchozí hodnoty, budou logovací soubory přesunuty na požadované místo dříve, než se spustí jakýkoliv příkaz služby. Výchozí hodnota je no.

Zde je ukázka konfiguračního souboru.

SCRIPT_PATH=/var/systemtap/script.d/
PASSALL=yes
RECURSIVE=no

PARAMETRY SKRIPTŮ

<SCRIPT>_OPT

Určuje volby, které se předají příkazu stap(1) před vykonáním skriptu. Zde SCRIPT je jméno skriptu bez přípony .stp. Poznamenejme, že volba -F se použije vždy.

Při kompilaci skriptů se ignorují následující volby: -p, -m, -r, -c, -x, -e, -s, -o, -h, -V, -k.

Při spouštění skriptů se ignorují následující volby: -h, -V, -v, -t, -p, -I, -e, -R, -r, -m, -k, -g, -P, -D, -b, -u, -q, -w, -l, -d, -L, -F, a všechny dlouhé volby.

<SCRIPT>_REQ

Určuje závislosti skriptu (t.j. určuje, který skript je vyžadován daným skriptem). Pokud foo.stp vyžaduje (nebo potřebuje běžet po) bar.stp, nastavte

foo_REQ="bar"

Více skriptů lze nastavit jako mezerami oddělený seznam.

Příklad konfiguračního souboru:

script1_OPT="-o /var/log/script1.out"
script2_OPT="-o /var/log/script2.out"
script2_REQ="script1"

PŘÍKLADY

INSTALACE SKRIPTŮ

Nakopírujme SystemTap skript (např. "script1.stp") do relevantního adresáře:

# cp script1.stp /etc/systemtap/script.d/

Pak můžeme nastavit volby pro daný skript. Například:

# vi /etc/systemtap/conf.d/group1
script1_OPT="-o /var/log/group1.out"

Pokud poté nainstalujeme skript, např. "script2.stp", který má být spuštěn po "script1.stp", máme zde závislost mezi skripty. Tu ošetříme následovně:

# cp script2.stp /etc/systemtap/script.d/
# vi /etc/systemtap/conf.d/group1
script2_OPT="-o /var/log/group2.out"
script2_REQ="script1"

V tomto případě, pokud stap(1) selže při startu, služba SystemTap se ani nepokusí nastartovat script2.

TESTOVÁNÍ

Po nainstalování skriptů můžeme ověřit, že fungují takto:

# service systemtap start
# service systemtap stop

Mohli bychom být konkrétnější, například takto:

# service systemtap start script1
# service systemtap stop script1

Pokud nenastaly chyby, máme vše připraveno k použití.

ZAPNUTÍ SLUŽBY

Jakmile jsme spokojeni se skripty a testování dopadlo úspěšně, můžeme SystemTap službu zapnout tak, aby se automaticky nastartovala po zavedení systému:

# chkconfig systemtap on

MAZÁNÍ SKRIPTŮ

Skripty se smažou prostým jejich odstraněním z adresáře pro skripty a také odstraněním jejich konfiguračních souborů plus případně relevantních nastavení:

# rm /etc/systemtap/script.d/script2.stp
# vi /etc/systemtap/conf.d/group1

Pokud skript stále běží, měli bychom jej zastavit:

# service systemtap stop script2

Také můžeme smazat relevantní cache:

# service systemtap cleanup script2

PŘÍPRAVA NA POVÝŠENÍ JÁDRA

Obvykle není třeba dělat nic neobvyklého když se startuje nové jádro. Služba SystemTap pozná, že verze jádra se liší proti obsahu cache a rekompiluje skripty. Kompilaci lze provést předem, abychom se vyhnuli kompilaci v době závádění systému:

# service systemtap compile myscript -r <NEW_KERNEL_VERSION>

IMPORT ZKOMPILOVANÝCH SKRIPTŮ

V prostředí, kde nejsou k dispozici kompilační nástroje (např. kompilátor, nebo ladicí informace), jako je např. produkční systém, lze skripty přeložit na jiném (vývojářském) stroji:

# service systemtap compile myscript -r \


>   <KERNEL_VERSION_OF_TARGET_MACHINE>
# tar czf stap-scripts-<kernel-version>.tar.gz \


>   /var/cache/systemtap/<kernel-version> \


>   /etc/systemtap/conf.d/<configfile>

A poté je přesunout na cílový stroj.

STARTOVÁNÍ SKRIPTŮ V DOBĚ ZAVÁDĚNÍ SYSTÉMU (ONBOOT PROBING)

lužba SystemTap umožňuje také nastartovat skripty poblíž začátku procesu zavádění OS tím, že vytvoří initramfs obsahující systemtap modul pro daný skript. Tato funkcionalita je dostupná jen na systémech, které používají dracut. Spuštění skriptu v této časné fázi startu OS zpřístupňuje informace, které je jinak obtížné získat.

Nejdříve nainstalujeme skript do odpovídajícího adresáře a provedeme potřebná nastavení:

# cp myscript.stp /etc/systemtap/script.d
# vi /etc/systemtap/conf.d/myscript.conf

Pro přidání skriptu do initramfs použijeme příkazonboot:

# service systemtap onboot myscript

Pokud daný skript není zkompilovaný a uložený v cache, dojde ke kompilaci. Ve výchozím umístění bude vytvořen nový initramfs. Mohli bychom použít volbu -b pro vytvoření zálohy původního initramfs. Nyní můžeme restartovat systém.

POUŽITÍ ALTERNATIVNÍHO INITRAMFS

Pokud bychom chtěli nastartovat skript během následujícího bootu, ale ne později, můžeme použít volbu -o k určení alternativního umístění initramfs:

# service systemtap onboot myscript \
>   -o /boot/special_initramfs.img

Jakmile je initramfs vytvořen, je možné jej použít prostou úpravou parametrů jádra při startu systému.

VYTVOŘENÍ INITRAMFS PRO JINÉ JÁDRO

Stejně jako u příkazu compile, můžeme i zde použít volbu -r, abychom určili jádro pro které chceme vytvořit initramfs. To může být užitečné např. chceme-li se připravit na upgrade. Například:

# service systemtap onboot myscript \
>   -r 3.12.6-200.fc19.x86_64

ODSTRANĚNÍ SKRIPTŮ Z INITRAMFS

K odstranění skriptů z initramfs stačí spustit příkaz onboot bez parametrů:

# service systemtap onboot

Takto se vytvoří nový initramfs bez SystemTap modulů.

HLEDÁNÍ CHYB ONBOOT MECHANIZMU

Přidáním parametru 'rdinitdebug' mezi parametry jádra lze zvýšit upovídanost programu dracut. Další informace lze získat z dmesg/journalctl -ae. Chybový výstup programu staprun lze získat nastavením LOG_BOOT_ERR na yes.

VIZ TÉŽ

CHYBY

error::reporting(7stap), https://sourceware.org/systemtap/wiki/HowToReportBugs

Index

JMÉNO

POUŽITÍ

POPIS

PŘÍKAZY

VOLBY

GLOBÁLNÍ PARAMETRY

PARAMETRY SKRIPTŮ

PŘÍKLADY

VIZ TÉŽ

CHYBY