2.3. SystemTap スクリプトの実行
SystemTap スクリプトはコマンド stap で実行されます。stap は、標準入力またはファイルから SystemTap スクリプトを実行できます。
stap および staprun を実行するには、システムに対する昇格された特権が必要です。ただし、すべてのユーザーが SystemTap 実行のためだけに
root アクセスを付与されるわけではありません。たとえば、権限のないユーザーが自身のマシン上で SystemTap インストルメンテーションを実行する必要がある場合もあります。
通常のユーザーが
root アクセスなしで SystemTap を実行できるようにするには、ユーザーを以下の両方のユーザーグループに追加します。
- stapdev
- このグループのメンバーは stap を使用して SystemTap スクリプトを実行したり、staprun を使用して SystemTap インストルメンテーションモジュールを実行したりできます。stap の実行では、SystemTap スクリプトがカーネルモジュールにコンパイルされ、それがカーネルに読み込まれます。これにはシステムに対する権限の昇格が必要となり、
stapdevメンバーにはそれが付与されます。ただし、この権限はstapdevメンバーに有効なrootアクセスも付与することになります。このため、stapdevグループのメンバーシップは、rootアクセスを信頼して付与できるメンバーにのみ許可してください。 - stapusr
- このグループのメンバーが SystemTap インストルメンテーションモジュールの実行に使用できるのは、staprun のみです。さらに、これらのモジュールは
/lib/modules/kernel_version/systemtap/からのみ実行できます。このディレクトリーを所有できるのはrootユーザーのみで、書き込みが可能なのもrootユーザーのみでなければならない点に注意してください。
SystemTap スクリプトの実行
SystemTap スクリプトを実行するには、ユーザーは stapdev と stapusr の 両方 のグループに属する必要があります。
以下は、一般的に使用される stap オプションのリストです。
- -v
- SystemTap セッションの出力をさらに詳細なものにします。このオプション (たとえば、stap -vvv script.stp) を繰り返して、スクリプトの実行に関する詳細を提供できます。スクリプトの実行中にエラーが発生すると、これは特に便利なものになります。SystemTap スクリプトの一般的なエラーに関する詳細は、5章SystemTap のエラーを理解する を参照してください。
-o filename- 標準出力を filename に送信します。
-S size、count- ファイルのサイズを size で指定されたメガバイト数に制限し、ファイル数を count の数に制限します。ファイル名には、連続番号の接尾辞が付きます。このオプションは、SystemTap に logrotate 演算を実装します。
-oとともに使用すると、-Sはログファイルのサイズを制限します。 -x process ID-c command- SystemTap ハンドラー関数の
target()を指定されたコマンドに設定します。指定コマンドへの完全パスを使用する必要があります。たとえば、cp を指定する代わりに、(stap script -c/bin/cp のように) /bin/cp を使用します。target() の詳細については、SystemTap 関数 を参照してください。 -e 'script'- systemtap 翻訳の入力に、ファイルではなく script 文字列を使用します。
-F- SystemTap のフライトレコーダーモードを使用し、スクリプトをバックグラウンドプロセスにします。フライトレコーダーモードの詳細は、「SystemTap フライトレコーダーモード」 を参照してください。
stap は、
- スイッチを使用して標準入力からスクリプトを実行するように指示することもできます。例を示します。
例2.1 標準入力からスクリプトを実行
echo "probe timer.s(1) {exit()}" | stap -
例2.1「標準入力からスクリプトを実行」 は、stap に、echo によって標準入力に渡されたスクリプトを実行するように指示します。stap で使用するオプションはすべて、- スイッチの前に挿入する必要があります。たとえば、例2.1「標準入力からスクリプトを実行」 をより詳細な出力にするには、以下のようなコマンドになります。
echo "probe timer.s(1) {exit()}" | stap -v -
stap の詳細については、man stap を参照してください。
SystemTap インストルメンテーション (クロスインストルメンテーション中に SystemTap スクリプトから構築されたカーネルモジュール) を実行するには、staprun を代わりに使用します。staprun とクロスインストルメンテーションの詳細については、「他のコンピューター用のインストルメンテーション生成」 を参照してください。
注記
stap オプション
-v および -o も staprun で機能します。staprun の詳細については、staprun(1) man ページを参照してください。
2.3.1. SystemTap フライトレコーダーモード
SystemTap のフライトレコーダーモードを使用すると、SystemTap スクリプトは長期間の実行が可能になり、最近の出力のみにフォーカスできるようになります。フライトレコーダーモード (
-F オプション) は、生成される出力の量を制限します。フライトレコーダーモードには、メモリー内モードとファイルモードの 2 種類があります。どちらの場合も、SystemTap スクリプトはバックグラウンドプロセスとして実行されます。
2.3.1.1. メモリー内フライトレコーダー
フライトレコーダーモード (
-F オプション) をファイル名なしで使用すると、SystemTap はカーネルメモリー内のバッファーを使用してスクリプトの出力を保存します。次に、SystemTap インストルメンテーションモジュールが読み込まれてプローブの実行が開始し、インストルメンテーションが外されてバックグラウンドに置かれます。関心のあるイベントが発生すると、インストルメンテーションは再度アタッチされ、メモリーバッファー内の最近の出力と継続中の出力が閲覧可能となります。以下のコマンドでは、フライトレコーダーのメモリー内モードを使用してスクリプトが開始されます。
stap -F /usr/share/doc/systemtap-version/examples/io/iotime.stp
スクリプトが開始されると、実行中のスクリプトに再接続するためのコマンドを示すメッセージが表示されます。
Disconnecting from systemtap module. To reconnect, type "staprun -A stap_5dd0073edcb1f13f7565d8c343063e68_19556"
関心のあるイベントが発生したら、実行中のスクリプトに再度アタッチしてメモリーバッファー内の最近のデータを出力し、継続中の出力を得るために、以下のコマンドを使用します。
staprun -A stap_5dd0073edcb1f13f7565d8c343063e68_19556
カーネルバッファーはデフォルトでは 1MB のサイズですが、
-s オプションを使用してバッファーのメガバイト単位のサイズを指定する (2 の累乗に切り上げる) ことが可能です。たとえば、SystemTap コマンドライン上で -s2 とすると、バッファーを 2MB に指定します。
2.3.1.2. ファイルフライトレコーダー
フライトレコーダーモードは、ファイルにデータを保存することもできます。保持するファイルの数とサイズは、
-S オプションにコンマ区切りの 2 つの数字の引数を続けて制御します。最初の引数は、各出力ファイルのメガバイト単位の最大サイズです。2 つ目の引数は、保存する最新ファイルの数です。ファイル名は、-o オプションの後に名前を付けて指定します。SystemTap は数値の接尾辞をファイル名に付けてファイルの順序を示します。以下のコマンドでは、SystemTap がフライトレコーダーモードで開始され、出力は /tmp/pfaults.log.[0-9]+ という名前のファイルに保存されます。各ファイルのサイズは 1MB 以下となり、最新の 2 ファイルが保存されます。
stap -F -o /tmp/pfaults.log -S 1,2 pfaults.stp
コマンドが出力する数字は、プロセス ID です。プロセスに
SIGTERM を送信すると、SystemTap スクリプトはシャットダウンし、データ収集が停止されます。たとえば、以前のコマンドでプロセス ID が 7590 となっている場合、以下のコマンドを実行すると SystemTap スクリプトはシャットダウンします。
kill -s SIGTERM 7590
スクリプトが生成した最新の 2 ファイルのみが保存され、それより古いファイルは削除されます。したがって、ls -sh/tmp/pfaults.log.* は次の 2 つのファイルのみを示します。
1020K /tmp/pfaults.log.5 44K /tmp/pfaults.log.6
最新のデータは数字の大きい方のファイルで、上記の場合は
/tmp/pfaults.log.6 になります。
