1. DTraceリファレンス・ガイド
  2. dtraceコマンド・リファレンス

8 dtraceコマンド・リファレンス

dtraceコマンドは、DTrace機能の汎用フロントエンド・ユーティリティです。このコマンドは、D言語のコンパイラを呼び出すシンプルなインタフェースを実装します。また、dtraceコマンドで、DTraceのカーネル機構からバッファに格納されたトレース・データを取得したり、一連の基本ルーチンを使用して、トレース・データをフォーマット設定して出力することができます。この章は、dtraceコマンドの全般的なリファレンス情報です。

dtraceコマンドの説明

dtraceコマンドでは、DTraceで提供される重要なサービスのすべてにアクセスできる汎用インタフェースを利用できます。次のことを行うオプションがあります。

  • DTraceによって現在公開されている一連のプローブとプロバイダをリストするオプション

  • 任意のプローブ記述指定子(provider、module、function、name)を使用して直接プローブを有効化するオプション。

  • Dコンパイラを実行し、1つ以上のDプログラム・ファイルまたはコマンドラインに直接入力されたプログラムをコンパイルするオプション。

  • プログラム安定性レポートを生成するためのオプション。「DTraceの安定性機能」を参照してください。

  • DTraceのトレース動作やバッファリング動作を変更したり、追加のDコンパイラ機能を有効化するためのオプション。「オプションおよびチューニング可能パラメータ」を参照してください。

dtraceコマンドを使用して、#!宣言のコマンドを使用してインタプリタ・ファイルを作成して、Dスクリプトを作成することもできます。「スクリプト」を参照してください。また、-eオプションをdtraceに指定して使用すると、実際にトレースを有効にせずにDプログラムをコンパイルしそのプロパティを決定できます。

dtraceコマンドのオプション

dtraceコマンドには、次のオプションを指定できます。 

dtrace [-CeFGhHlqSvVwZ]
[-b bufsz] [-c command] [-D name[=value]] [-I pathname] [-L pathname]
[-o pathname] [-p PID] [-s source_pathname]
[-U name] [-x option[=value]] [-X a|c|s|t]
[-P provider[[predicate]action]]
[-m [[provider:]module[[predicate]action]]]
[-f [[provider:]module:]function[[predicate]action]]
[-n [[[provider:]module:]function:]name[[predicate]action]]
[-i probe-id[[predicate]action]]

D言語の構文に従って、predicateは任意のD述語をスラッシュ(//)で囲んだ形式、actionは任意のD文のリストを中カッコ({ }),で囲んだ形式で指定します。

Dプログラムのコードを、-P、-m、-f、-nまたは-iオプションの引数として指定する場合、シェルによって解釈されないように、このテキストを適切な引用符で囲む必要があります。

オプションは、次のとおりです。

-b bufsize

主トレース・バッファのサイズを設定し、k (KB)、m (MB)、g (GB)またはt (TB)のいずれかのサイズ接尾辞を含めることができます。バッファ領域を割り当てることができない場合、dtraceは、bufresizeプロパティの設定に応じてバッファ・サイズを削減しようとするか終了します。

-c command

指定したコマンドを実行し、実行が完了したら終了します。-cオプションを複数指定した場合、dtraceはすべてのコマンドが終了すると終了し、終了時に各子プロセスの終了ステータスを報告します。dtraceコマンドは、Dプログラムで最初のコマンドのプロセスIDを$targetマクロ変数として使用できるようにします。

-C

Dプログラムをコンパイルする前に、Cプリプロセッサ(cpp)を実行します。-D、-H、-Iおよび-Uオプションを使用して、Cプリプロセッサにオプションを渡すことができます。-Xオプションを使用して、C標準への適合度を選択します。

-D name[=value]

-Cオプションを使用してcppを呼び出すときに、指定マクロ名およびオプション値を定義します。-Dオプションは、コマンドに複数回指定できます。

-e

要求をコンパイルした後、プローブを有効にする前に終了します。このオプションと-Dオプションを組み合せると、Dプログラムを実行したり、対応するインストゥルメンテーションを有効にしたりせずに、Dプログラムがコンパイルされることを確認できます。

-f [[provider:]module:] function [[predicate]action]

トレースまたはリストする必要がある関数を指定します(オプションでプロバイダとモジュールも指定します)。 オプションのDプローブ節を追加できます。-fオプションは、コマンドに複数回指定できます。

-F

関数およびシステム・コールのエントリ・ポイントとリターン・ポイントの出力を組み合せることで、トレース出力を減らします。dtraceコマンドは、entryプローブ・レポートをインデントし、returnプローブ・レポートをインデントしません。このコマンドは、関数開始プローブのレポートからの出力の先頭に->を付け、関数終了プローブのレポートからの出力に<-を付けます。dtraceコマンドは、システム・コール開始プローブのレポートからの出力の先頭に=>を付け、システム・コール終了プローブのレポートからの出力に<=を付けます。

-G

埋め込まれたDプログラムを含むELFファイルを生成します。このコマンドは、別のプログラムにリンクできる再配置可能なELFオブジェクトを使用して、プログラムで指定されたDTraceプローブを保存します。-oオプションを指定すると、dtraceはELFファイルを指定されたパス名に保存します。-oオプションを指定しない場合、ELFファイルにはDプログラムのソース・ファイルと同じ名前が割り当てられますが、拡張子は.sではなく.oになります。これ以外の場合、ELFはd.outという名前で保存されます。

-h

-sオプションに対する引数として指定されたファイル内のプローブ定義に基づいてヘッダー・ファイルを作成します。-oオプションを指定すると、コマンドはヘッダー・ファイルを指定されたパス名に保存します。-oオプションを指定しない場合、ヘッダー・ファイルにはDプログラムのソース・ファイルと同じ名前が割り当てられますが、拡張子は.dではなく.hになります。このヘッダー・ファイルをインクルードするように、トレースするプログラムのソース・ファイルを修正する必要があります。

-H

cppを-Cオプションを指定して呼び出すと、stderrのインクルード・ファイルのパス名が出力されます。

-i probe_ID [[predicate]action]

トレースまたはリストする必要があるプローブ名を指定します。プローブIDは、dtrace -lで表示される10進数の整数で指定する必要があります。 オプションのDプローブ節を追加できます。-iオプションは、コマンドに複数回指定できます。

-I pathname

-Cオプションを指定してcppを呼び出すときに、指定したディレクトリ・パスを#includeファイルの検索パスに追加します。指定されたディレクトリは、デフォルトのディレクトリ・リストの先頭に挿入されます。

-l

プローブを有効化しないで一覧表示します。dtraceコマンドは、-f、-i、-m、-n、-Pおよび-sオプションの引数に基づいて、プローブのリストをフィルタします。オプションを指定しない場合、このコマンドはすべてのプローブをリストします。

-L pathname

指定したディレクトリ・パスをライブラリ検索パスの最後に追加します。このオプションを使用して、Dプログラムの共通定義を含むDTraceライブラリへのパスを指定します。

-m [[provider:]module [[predicate]action]]

トレースまたはリストするモジュールを指定します。オプションでプロバイダを指定できます。オプションのDプローブ節を追加できます。-mオプションは、コマンドに複数回指定できます。

-n [[[provider:]module:] function:]name [[predicate]action]

トレースまたはリストするプローブ名を指定します。オプションのDプローブ節を追加できます。オプションで、プロバイダ、モジュールおよび関数を指定できます。-nオプションは、コマンドに複数回指定できます。

-o pathname

-Gおよび-lオプションまたはトレース・データの出力ファイルを指定します。

-p PID

プロセスIDを指定してプロセスを取得し、そのシンボル表をキャッシュして、プロセスの完了時に終了します。複数の-pオプションを指定すると、すべてのプロセスが終了したときにdtraceが終了します。さらに、このコマンドは各プロセスの終了時に、終了ステータスを報告します。dtraceコマンドは、指定された最初のプロセスIDを、マクロ変数$targetとしてDプログラムで使用できるようにします。

-P provider['D-probe_clause']

トレースまたはリストするプロバイダを指定します。オプションのDプローブ節を追加できます。-Pオプションは、コマンドに複数回指定できます。

-q

非出力モードを設定します。dtraceコマンドは、情報メッセージ、列ヘッダー、CPU ID、プローブIDおよび追加の改行を抑制します。stdoutには、printa()、printf()およびtrace() Dプログラム文によってトレースおよび書式設定されたデータのみが表示されます。このオプションは、Dプログラムで#pragma D option quietを指定することと同じです。

-s source_pathname

次のように、dtraceコマンドでコンパイルするDプログラムのソース・ファイルの名前を指定します。

  • -hオプションを指定すると、dtraceはファイル内のプローブ定義を使用してヘッダー・ファイルを作成します。

  • -Gオプションを指定すると、dtraceは、他のプログラムにリンクできる再配置可能なELFオブジェクトを生成します。

  • -eオプションを指定するとdtraceはプログラムをコンパイルしますが、インストゥルメンテーションは有効にしません。

  • -1オプションを指定すると、dtraceはプログラムをコンパイルして一致するプローブのセットをリストしますが、インストゥルメンテーションは有効にしません。

  • オプションを指定しないと、dtraceはDプログラムで指定されたインストゥルメンテーションを有効にしてトレースを開始します。

-S

Dコンパイラの中間コードを表示します。Dコンパイラは、各Dプログラムに対して生成された中間コードのレポートをstderrに書き込みます。

-U name

-Cオプションを使用してcppを呼び出すときに、指定された名前を未定義にします。-Uオプションは、コマンドに複数回指定できます。

-v

冗長モードを設定します。dtraceコマンドは、指定されたDプログラムの最小インタフェース安定性と依存レベルを示すプログラム安定性レポートを生成します。

-V

dtraceによってサポートされるDプログラミング・インタフェースの最も高いバージョンをstdoutに書き込みます。

-vVの組合せによって、dtrace-utilsパッケージのユーザー空間バイナリのバージョンなど、他のバージョン情報が追加されます。

-w

Dプログラムでの破壊アクションを許可します。このオプションを指定しない場合、このコマンドでは破壊アクションを含むDプログラムはコンパイルまたは有効化されません。このオプションは、Dプログラムで#pragma D option destructiveを指定することと同じです。

-x option[=value]

DTraceランタイム・オプションまたはDコンパイラ・オプションを有効化または変更します。

-X a|c|t

-Cオプションを指定してcppを呼び出すときに、オプション-std=gnu99 (1999 C標準に準拠し、GNU拡張を含む)を含めます。

-Xs

-Cオプションを使用してcppを呼び出すときに、オプション-traditional-cpp (K&R Cに準拠)を含めます。

-Xモードにかかわらず、次のように追加のCプリプロセッサ定義が常に指定され、すべてのモードで有効になります。

  • __linux

  • __unix

  • __SVR4

  • __`uname -s` (たとえば、__Linux)

  • __SUNW_D=1

  • __SUNW_D_64

  • __SUNW_D_VERSION=0xMMmmmuuu

    MMは16進のメジャー・リリース値、mmmは16進のマイナー・リリース値、uuuは16進のマイクロ・リリース値です。DTraceのバージョニングの詳細は、「DTraceのバージョニング」を参照してください。

-Z

どのプローブにも一致しないプローブの説明を許可します。このオプションを指定しないと、プローブの説明が既知のプローブと一致しない場合、dtraceコマンドはエラーを報告して終了します。

dtraceコマンドのオペランド

dtraceコマンドラインに0個以上の追加引数を指定して、-sオプションまたはコマンドラインで指定された任意のDプログラムで使用する$1や$2などのマクロ変数のセットを定義できます。マクロ変数の詳細は、「スクリプトの作成」で説明します。

dtraceコマンドの終了ステータス

dtraceコマンドでは、次の終了値が返されます。

0

指定されたリクエストの処理が正常に完了したことを示します。Dプログラム・リクエストに対して、終了ステータス0は、プログラムのコンパイル、プローブの有効化、または匿名状態の取得が正常に実行されたことを表します。 dtraceコマンドは、指定されたトレース・リクエストでエラーや欠落が発生した場合でも0を返します。

1

致命的エラーが発生したことを示します。Dプログラム・リクエストに対して、終了ステータス1は、プログラムのコンパイルに失敗した、または指定されたリクエストに応答できなかったことを表します。

2

指定されたコマンドライン・オプションまたは引数が無効であることを示します。