SystemTap スクリプトを動作させると、 SystemTap セッションが起動します。また、スクリプトが実行されるまでの間に、いくつかのパスが実行されます。その後、スクリプトはカーネルモジュールとしてコンパイルされ、読み込まれます。スクリプトを以前に実行していて、システムコンポーネント (コンパイラやカーネルのバージョン、ライブラリパスやスクリプトの内容) に変更がない場合、 SystemTap は再度スクリプトをコンパイルするようなことはありません。その代わり、 SystemTap のキャッシュ ( ~/.systemtap ) 内に保存されている *.c と *.ko のデータを使用します。

タップの動作が完了すると、モジュールの読み込みも解除されます。たとえば 4.2項 「インストールと設定」 にあるテストスクリプトと、対応する説明をお読みください。

SystemTap を動作させるにはカーネルに関する情報が必要となることから、カーネル関連の追加パッケージをインストールしなければなりません。また、 SystemTap でプローブを設定したいカーネルごとに、それぞれ下記のパッケージをインストールする必要があります。さらに、下記のパッケージをインストールする場合は、プローブを設定したいカーネルのフレーバー (下記では * と記してあります) とバージョンが厳密に一致したパッケージをインストールする必要があります。

重要: デバッグ情報 (debuginfo) パッケージのリポジトリについて

お使いのシステムでオンライン更新を有効にしていれば、 openSUSE Leap 15.7 に対応する *-Debuginfo-Updates という名前のオンラインリポジトリ内に、 「debuginfo」 パッケージが存在しています。このリポジトリを有効にするには、 YaST をお使いください。

従来型の SystemTap 設定を行う場合は、下記のパッケージをインストールしてください (YaST もしくは zypper を利用してインストールします。

マニュアルページや SystemTap のスクリプト例など、様々な目的でのヘルプ情報を必要とする場合は、これらに加えて systemtap-docs パッケージもインストールしてください。

マシン内に必要なパッケージを全てインストールできていて、 SystemTap を使用するための準備が整っているかどうかを確認するには、下記のコマンドを root で実行します:

# stap -v -e 'probe vfs.read {printf("read performed
"); exit()}'

上記のコマンドを実行すると、スクリプトを実行して現在動作しているカーネルに対してプローブを設定し、出力を返します。出力が下記のような内容になっていれば、 SystemTap は問題なく配置できたことになります:

Pass 1: parsed user script and 59 library script(s) in 80usr/0sys/214real ms.
Pass 2: analyzed script: 1 probe(s), 11 function(s), 2 embed(s), 1 global(s) in
 140usr/20sys/412real ms.
Pass 3: translated to C into
 "/tmp/stapDwEk76/stap_1856e21ea1c246da85ad8c66b4338349_4970.c" in 160usr/0sys/408real ms.
Pass 4: compiled C into "stap_1856e21ea1c246da85ad8c66b4338349_4970.ko" in
 2030usr/360sys/10182real ms.
Pass 5: starting run.
 read performed
Pass 5: run completed in 10usr/20sys/257real ms.

テスト時に何らかのエラーメッセージが表示された場合、まずは出力された内容をご確認ください。出力された内容に必要なパッケージに関する情報が書かれている場合は、まず必要なパッケージが正しくインストールされていることを確認してください。また、カーネルをインストールした場合は、システムを再起動して新しいカーネルを読み込む必要があります。

SystemTap のスクリプトは、下記に示す 2 つのコンポーネントから構成されています:

イベントとそれに対応するハンドラをまとめて、 プローブ と呼びます。 SystemTap のイベントは プローブポイント 、対応するハンドラは プローブボディ とも呼びます。

コメントは SystemTap スクリプト内の任意の箇所に配置することができます。コメントの書式は、 #, /* */ , // のいずれかです。

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

probe1 begin2
{3
   printf4 ("hello world
")5
   exit ()6
}7

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

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

printf ("1%s2(%d3) open
4", execname(), pid())

[...]
vmware-guestd(2206) open
held(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
",
    count_jiffies, count_ms, hz)
  exit ()
  }

systemtap-docs パッケージをインストールしていれば、 /usr/share/doc/packages/systemtap/examples 内に SystemTap のスクリプト例がいくつか用意されています。

本章では、 /usr/share/doc/packages/systemtap/examples/network/tcp_connections.stp にあるシンプルなスクリプト例を詳しく説明します:

#! /usr/bin/env stap

probe begin {
  printf("%6s %16s %6s %6s %16s
",
         "UID", "CMD", "PID", "PORT", "IP_SOURCE")
}

probe kernel.function("tcp_accept").return?,
      kernel.function("inet_csk_accept").return? {
  sock = $return
  if (sock != 0)
    printf("%6d %16s %6d %6d %16s
", uid(), execname(), pid(),
           inet_get_local_port(sock), inet_get_ip_source(sock))
}

この SystemTap スクリプトは着信側の TCP 接続を監視して、リアルタイムに望まない接続を識別する仕組みを提供するものです。それぞれコンピュータが受け入れた着信側 TCP 接続に対して、下記のような情報を表示します:

スクリプトを実行するには、下記のように入力して実行します:

stap /usr/share/doc/packages/systemtap/examples/network/tcp_connections.stp

すると、画面内に出力が表示されるようになります。スクリプトを手作業で停止するには、 Ctrl–C を押します。

DTrace のようにユーザスペースで動作するアプリケーションをデバッグする目的で、 openSUSE Leap 15.7 では、 SystemTap でユーザスペースのプローブを行うことができます。ユーザスペースのプローブでは、アプリケーション内の任意の場所にプローブポイントを設置することができます。これにより、 SystemTap はカーネルスペースとユーザスペースの両方を調査できることになり、結果としてシステム全体を調査できるようになっています。

ユーザスペースのプローブを設置する際に必要となる utrace インフラストラクチャと uprobe カーネルモジュールを取得するには、 4.2項 「インストールと設定」 に示されているパッケージに加え、 kernel-trace パッケージをインストールする必要があります。

utrace はユーザスペースの処理を制御するためのフレームワークを実装するものです。様々なトレーシング 「エンジン」 で使用することのできるインターフェイスを提供し、これ自身は読み込み可能なカーネルモジュールとして提供されます。エンジンは特定のイベントに対してコールバック関数を登録し、トレース対象のスレッドに結びつけられます。コールバックはカーネル内の 「安全な」 場所から行われるため、関数が実行できる処理の種類に大きな余裕ができることになります。 utrace では、たとえばシステムコールの開始と終了、 fork() やタスクに送信されるシグナルなど、様々なイベントを監視することができます。 utrace のインフラストラクチャについて、詳しくは https://sourceware.org/systemtap/wiki/utrace (英語) をお読みください。

SystemTap では、ユーザスペースプロセス内での関数の開始および終了のプローブに対応しているほか、コード内にマーカーを設定してプローブしたり、特定のプロセス内イベントを監視したりすることもできます。

現在実行しているカーネルが utrace に対応しているかどうかを調べるには、下記のコマンドを実行します:

> sudo grep CONFIG_UTRACE /boot/config-`uname -r`

ユーザスペースのプローブについて、詳しくは https://sourceware.org/systemtap/SystemTap_Beginners_Guide/userspace-probing.html (英語) をお読みください。

本章では、 SystemTap の概要部までしか言及できていません。 SystemTap に関する詳細な情報を得たい場合は、それぞれ下記を参照してください (英語のみの提供である場合もあります):

なお、 SystemTap の言語リファレンスとチュートリアルについては、 /usr/share/doc/packages/systemtap ディレクトリ内にも用意されています。また、スクリプトの例については、上記の example サブディレクトリをご覧ください。