SystemTap の使用は、主に SystemTap のスクリプト (*.stp) を使用することで行ないます。スクリプトでは SystemTap がどのような種類の情報を 収集し、その収集した情報に対して何かを行なうのかを指し示します。スクリプトは、 AWK や C 言語に似た SystemTap スクリプト言語で記述します。言語の定義について、 詳しくは http://sourceware.org/systemtap/langref/ をお読みください。

SystemTap スクリプトの主な考え方は、 イベント に対して 命名を行ない、それらを ハンドラ に渡す、という流れを 構築するというものです。 SystemTap がスクリプトを実行すると、特定のイベントに 対して監視を行ないます。イベントが発生すると、 Linux カーネルはサブルーチン としてハンドラを動かし、元の実行に戻ります。そのため、イベントはハンドラを 動作させるためのトリガー (きっかけ) という位置づけになります。ハンドラでは、 指定したデータを指定した形式で記録または表示させることができます。

なお、 SystemTap 言語ではごく少数のデータ型 (整数、文字列、およびそれらの 連想配列) を使用し、完全な構造制御 (ブロック、条件分岐、ループ、関数) を 扱うことができます。また、簡易な文章構造 (セミコロンによる区切りは任意) に なっているほか、詳細な宣言を行なう必要はありません (データ型は自動的に 推測され、チェックされます) 。

SystemTap のスクリプトやそれらの文法について、詳しくは 5.3項 「スクリプトの文法」 のほか、 stapprobes や stapfuncs の マニュアルページをお読みください。マニュアルページは、 systemtap-docs パッケージに 含まれています。

tap セットとは事前に作成された探査用のライブラリで、 SystemTap スクリプト内 から使用することができる関数群を含んでいます。ユーザが SystemTap スクリプトを 実行すると、 SystemTap はスクリプトの探査イベントやハンドラが、 tap セット ライブラリ内に存在するかどうかを確認します。その後 SystemTap はスクリプトが C 言語のコードに変換される前に、それら必要な探査や関数を読み込みます。 SystemTap スクリプト自身と同様に、 tap セットのファイル名には *.stp という拡張子が付けられています。

ただし SystemTap スクリプトとは異なり、 tap セットは直接実行するためのもの ではありません。他のスクリプトから定義を引き出すための書庫として存在 しています。そのため tap セットライブラリは、イベントや関数を簡単に 作成できるようにするための抽象層と言えます。 tap セットはイベントを 指定したいユーザに対して、各種の便利な関数の別名を規定しています。 たとえばバージョンごとに異なるような特定のカーネル関数に対して、 わかりやすい別名が用意されていたりします。

SystemTap でもっとも使用されるコマンドは、 stap と staprun の 2 つです。これらは rootから実行するか、 もしくは stapdev または stapusr のメンバーのユーザから 実行する必要があります。

それぞれのコマンドについてオプションの一覧を表示するには、コマンドに --help オプションを付けて実行してください。また、詳しい説明 については、それぞれ stap と staprun のマニュアルページをお読みください。

また、 SystemTap を実行するだけのユーザに対して、 root の権限を付与せずに 済ませる方法として、それぞれ下記に示す SystemTap 用のグループに所属させる方法が あります。 これらはいずれも openSUSE の既定の設定では用意されていませんが、下記の グループを作成して適切な権限を与えることで、上記を実現することができます。

下記の一覧では、 SystemTap における主なファイルとディレクトリについて、 概要を説明しています。

SystemTap スクリプトでは、複数の調査を記述することができます。調査は下記の 形式で記述されなければなりません:

probe イベント {ステートメント}

それぞれの調査には対応するステートメントブロックが存在します。この ステートメントブロックは { } で括られていなければ ならず、イベントごとにステートメントが存在しなければなりません。

probe begin
{
   printf ("hello world\n")
   exit ()
}

スクリプト内に複数のステートメントが記述されている場合、 SystemTap はこれらの ステートメントを書かれている順番に実行します。ステートメントの間には区切りと なる文字や終了を表わす文字を記述する必要はありません。また、ステートメントの ブロックは他のステートメントのブロック内にネストする (入れ子の形式にする) こともできます。一般的に SystemTap スクリプトで使用するステートメントブロックは、 C プログラミング言語でのそれと同じです。

SystemTap では数多くの内蔵イベントをしようすることができます。

一般的なイベントの書式は、ドットで区切って記述する形態です。このような仕組み により、イベントを分類から絞り込むことができるようになっています。また、 それぞれのコンポーネント (イベントのパーツ) では、関数呼び出しのような形式で 文字列または数値のパラメータを指定することができるます。さらに、コンポーネント には * を指定することができます。これは該当する他の探査点に 展開される動作になります。それ以外にも、探査点に ? を付加 して、展開に失敗した場合でもエラーとしない、任意指定のものとすることができます。 なお、探査点に対して ! を付加すると、任意指定かつ十分なもの とすることができます。

SystemTap では探査点に対して複数のイベントを設定することができます。これらは カンマ (,) で区切って指定します。複数のイベントが 単一の探査に対して設定された場合、 SystemTap は指定したいずれかのイベントが 発生した際に実行を行ないます。

一般的には、イベントは下記のような分類に分けることができます:

probe timer.s(4)
{
   printf("hello world\n")
}

利用可能なイベントについて、詳しくは stapprobes の マニュアルページをお読みください。マニュアルページ内の See Also の項には、特定のサブシステムや コンポーネントに対応するイベントについて、他のマニュアルページへの リンクが書かれています。

Each SystemTap event is accompanied by a corresponding handler defined for that event, consisting of a statement block.

function 関数名(パラメータ) {ステートメント}
probe イベント {関数名(パラメータ)}

printf ("%s(%d) open\n", execname(), pid())

[...]
vmware-guestd(2206) open
hald(2360) open
[...]
   

foo = gettimeofday( )

global count_jiffies, count_ms
probe timer.jiffies(100) { count_jiffies ++ }
probe timer.ms(100) { count_ms ++ }
probe timer.ms(12345)
{
  hz=(1000*count_jiffies) / count_ms
  printf ("jiffies:ms ratio %d:%d => CONFIG_HZ=%d\n",
    count_jiffies, count_ms, hz)
  exit ()
  }