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 スクリプトを実行するには、ユーザーは 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「標準入力からスクリプトを実行」 では、
echo が標準入力に渡したスクリプトを実行するように stap に指示します。stap で使用するオプションはすべて、- スイッチの前に挿入する必要があります。たとえば、例2.1「標準入力からスクリプトを実行」 をより詳細な出力にするには、以下のようなコマンドになります。
echo "probe timer.s(1) {exit()}" | stap -v -
stap の詳細については、man stap を参照してください。
SystemTap インストルメンテーション (クロスインストルメンテーション中に SystemTap スクリプトから構築されたカーネルモジュール) を実行するには、
staprun を代わりに使用します。staprun およびクロスインストルメンテーションの詳細は、「他のコンピューター用のインストルメンテーション生成」 を参照してください。
注記
stap の -v オプションと -o オプションは staprun でも機能します。staprun の詳細については、man staprun を参照してください。
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 になります。
