EN JA
DTRACE(1)
DTRACE(1) FreeBSD General Commands Manual DTRACE(1)

名称

dtrace動的トレース (追跡) コンパイラとトレース (追跡) ユーティリティ

書式

dtrace [ -32 | -64][ -aACeFGhHlqSvVwZ][ -b bufsz][ -c cmd][ -D name [ =value]][ -I path][ -L path][ -o output][ -s script][ -U name][ -x arg [ =value]][ -X a | c | s | t][ -p pid][ -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]]

解説

DTrace は、Solaris から移植された総合的な動的トレース (追跡) フレームワークです。 DTrace は、管理者、開発者とサービスマンがオペレーティングシステムとユーザプログラムの振る舞いに関する任意の質問に簡潔に答えることを可能とする強力なインフラストラクチャを提供しています。

dtrace コマンドは、次のものを含む DTrace 機能によって提供される必要不可欠なサービスへの一般的なインタフェースを供給しています:

  • 現在、DTrace によって公表されたプローブとプロバイダのセットをリストするオプション
  • プローブ記述指定子 (プロバイダ、モジュール、関数、名前) のいずれかを使用して直接的なプローブを有効にするオプション
  • D コンパイラを実行して、コマンド行に直接書かれた 1 つ以上の D プログラムファイルまたはプログラムをコンパイルするオプション
  • 匿名のトレース (追跡) プログラムを生成するオプション
  • プログラムの安定性のレポートを生成するオプション
  • 振る舞いをトレースし、バッファリングする DTrace を変更して、追加の D コンパイラ機能を有効にするオプション

利用者は、インタプリタファイルを作成するために shebang (#!) 宣言で、それを使用することによって D スクリプトを作成するために dtrace を使用することができます。また、利用者は、D プログラムをコンパイルして、実際に -e オプションを使用してトレースを有効にしないでそれらの特性を決定することを試みるために dtrace を使用することができます。

オプション

-P, -m, -f, -n-i オプションによって受け付けられた引数は、スラッシュ (/) で囲まれたオプションの D 言語 predicate と大括弧 ({}) で囲まれた、オプションの D 言語の action 文リストを含むことができます。コマンド行で指定された D プログラムコードは、シェルによってメタ文字の解釈を避けるために適切にクォート (引用) されなければなりません。

次のオプションが、サポートされます:

-32 | -64
D コンパイラは、オペレーティングシステムのカーネルの従来のデータモデルを使用してプログラムを作成します。 -32 オプションが指定されるなら、 dtrace によって、D コンパイラは、32 ビットのデータモデルを使用して強制的に D プログラムをコンパイルします。 -64 オプションが指定されるなら、 dtrace によって、D コンパイラは、64 ビットのデータモデルを使用して強制的に D プログラムをコンパイルします。これらのオプションは、通常 dtrace がデフォルトとして従来のデータモデルを選択するように、必要ではありません。データモデルは、整数タイプと他の言語の特性のサイズに影響します。 32 ビットと 64 ビットのカーネルの両方で、いずれかのデータモデルのためにコンパイルされた D プログラムを実行することができます。また、 -32-64 オプションは、 -G オプションによって作成された elf(5) ファイル形式 (ELF32 または ELF64) を決定します。
-a
匿名でトレースされた状態を要求して、トレースされたデータを表示します。利用者は、新しいデータを待ち続けているのではなく、匿名のトレース状態を消費する直後に、 dtrace が終了するように強制する -a オプションと -e オプションを組み合わせることができます。
-A
匿名のトレースのためにディレクティブ (指示) を生成し、それらを /boot/dtrace.dof に書き込みます。このオプションは、匿名のトレースのために指定されたプローブを有効とするために 1 組の dtrace 設定ファイルディレクティブを構成して、次に終了します。デフォルトで、 dtrace は、ファイル /boot/dtrace.dof にディレクティブを格納することを試みます。代替の出力ファイルを指定するために -o オプションを使用して、この振る舞いを変更することができます。
-b bufsz
プリンシパルのトレースバッファサイズ bufsz を設定します。トレースバッファサイズは、サイズ接尾辞 k、m、g または t のいずれかを含むことができます。バッファ空間を割り付けることができないなら、 dtrace は、バッファサイズを減少することを試み、bufresize 特性の設定に依存して終了します。
-c cmd
指定されたコマンド cmd を実行し、完了すれば、終了します。 2 つ以上の -c オプションがコマンド行に存在しているなら、 dtrace は、すべてのコマンドが終了したとき、それを終了するような、各子プロセスのための終了ステータスを報告して、終了します。最初のコマンドのプロセス ID は、コマンド行で指定されるあらゆる D プログラム、または $target マクロ変数を通して -s オプションを使用して利用可能とされます。
-C
それらをコンパイルする前に、D プログラムで C プリプロセッサ cpp(1) を実行します。利用者は、 -D, -U, -I-H オプションを使用して C プリプロセッサにオプションを渡すことができます。 -X オプションを使用するなら、利用者は、C 標準の適合の程度を選択することができます。 C プリプロセッサを呼び出すとき、D コンパイラによって定義されたトークンのセットの記述については、 -X を参照してください。
-D name [ =value]
( -C オプションを使用して有効にされた) cpp(1) を呼び出すときに、 name を定義します。利用者が追加の value を指定するなら、name は、対応する値に代入されます。このオプションは、それぞれの cpp(1) の呼び出しに -D オプションを渡します。
-e
あらゆる要求をコンパイルし、匿名のトレース状態 ( -a オプション) を消費した後に終了しますが、あらゆるプローブを有効にする前です。利用者は、匿名のトレースデータを印刷して終了するために -a オプションと、このオプションを組み合わせることができます。また、利用者は、このオプションと D コンパイラオプションを組み合わせることもできます。この組み合わせは、プログラムが実際にそれらを実行しないでコンパイルし、対応する計装を有効にすることを検証します。
-f [ [ provider:] module:] function [ [ predicate] action]
トレースまたはリスト ( -l オプション) する関数名を指定します。対応する引数は、プローブ記述形式 provider:module:function, module:function または function のいずれかを含むことができます。不特定のプローブ記述フィールドは、空白のままにされ、それらのフィールドの値にかかわらずあらゆるプローブに一致します。 function 以外の修飾子が記述で指定されないなら、対応する function があるすべてのプローブは、一致されます。オプションの D プローブ節で -f 引数を末尾に付けることができます。利用者は、一度に、コマンド行で 2 つの以上の -f オプションを指定することができます。
-F
関数エントリを識別することによって、トレースの出力を結合して、返ります。関数エントリのプローブレポートは、字下げされ、それらの出力は、‘ ->’が前に付けられます。関数リターンのプローブレポートは、字下げされず、それらの出力は、‘ <-’が前に付けられます。システムコールのエントリプローブレポートは、字下げされ、それらの出力は、‘ =>’が前に付けられます。システムコールのリターンプローブレポートは、字下げされず、それらの出力は、‘ <=’が前に付けられます。
-G
組み込まれた DTrace プログラムを含んでいる ELF ファイルを生成します。プログラムで指定された DTrace プローブは、別のプログラムにリンクできるリロケータブル ELF オブジェクトの内部に保存されます。 -o オプションが存在しているなら、ELF ファイルは、このオペランドのための引数として指定されたパス名を使用して保存されます。 -o オプションが存在していなくて、名前が filename.d であるファイルに DTrace プログラムが、含まれているなら、 ELF ファイルは、名前 filename.o を使用して保存されます。そうでなければ、ELF ファイルは、名前 d.out を使用して保存されます。
-h
指定されたプロバイダ定義でプローブに対応するマクロを含むヘッダファイルを生成します。このオプションは、 -G オプションをつけて後で使用するために他のソースファイルによって含まれているヘッダファイルを生成するために使用されるべきです。 -o オプションが存在しているなら、ヘッダファイルは、そのオプションのための引数として指定されたパス名を使用して保存されます。 -o オプションが存在していなくて、名前が filename.d であるファイルに DTrace プログラムが、含まれているなら、ヘッダファイルは、名前 filename.h を使用して保存されます。
-H
( -C オプションを使用して有効にされた) cpp(1) を呼び出すときに、含まれているファイルのパス名を印刷 (表示) します。このオプションは、 -H オプションを、それぞれの cpp(1) 呼び出しに渡し、各行あたり 1 つ、標準エラーに、パス名のリストを表示します。
-i probe-id [ [ predicate] action]
トレースまたはリスト ( l オプション) するために プローブ識別子 (probe-id) を指定します。利用者は、`dtrace -l` によって表示されるように 10 進整数を使用してプローブ ID を指定することができます。オプションの D プローブ節で -i 引数を末尾に付けることができます。利用者は、一度に、2 つ以上の -i のオプションを指定することができます。
-I path
( -C オプションを使用して有効にされる) cpp(1) を呼び出すとき、#include ファイルのために検索パスに指定されたディレクトリ path を追加します。このオプションは、それぞれの cpp(1) 呼び出しに -I を渡します。指定された path は、デフォルトのディレクトリのリストの前方の検索パスに挿入されます。
-l
それらを有効にする代わりにプローブをリストします。 -l オプションが指定されるなら、 dtrace は、 -P, -m, -f, -n, -i-s オプションを使用して与えられた記述に一致するプローブのレポートを作成します。これらのオプションのいずれも指定されないなら、このオプションは、すべてのプローブをリストします。
-L path
DTrace ライブラリのために検索パスに指定されたディレクトリ path を追加します。 DTrace ライブラリは、D プログラムを書くとき、使用できる共通の定義を含むために使用されます。指定された path は、デフォルトのライブラリ検索パスの後に追加されます。
-m [ provider:] module [ [ predicate] action]
トレースまたはリスト ( -l オプション) するモジュール名を指定します。対応する引数は、プローブ記述形式 provider:module または module のいずれかを含むことができます。不特定のプローブ記述フィールドは、空白のままにされ、それらのフィールドの値にかかわらずあらゆるプローブに一致します。 module 以外の修飾子が記述で指定されないなら、対応する module があるすべてのプローブが一致されます。オプションの D プローブ節で -m 引数を末尾に付けることができます。一度に、コマンド行で 2 つ以上の -m オプションを指定することができます。
-n [ [ [ provider:] module:] function:] name [ [ predicate] action]
トレースまたはリスト ( -l オプション) するプローブ名を指定します。対応する引数は、プローブ記述形式 provider:module:function:name, module:function:name, function:name または name のいずれかを含むことができます。不特定のプローブ記述フィードは、空白のままにされ、それらのフィールドの値にかかわらずあらゆるプローブに一致します。 name 以外の修飾子が記述で指定されないなら、対応する name があるすべてのプローブが一致されます。オプションの D プローブ節で -n 引数を末尾に付けることができます。一度に、コマンド行で 2 つ以上の -n オプションを指定することができます。
-o output
-A, -G-l オプション、またはトレースデータ自体のための output ファイルを指定します。 -A オプションが存在し、 -o が存在していないなら、デフォルトの出力ファイルは、 /boot/dtrace.dof です。 -G オプションが存在し、 -s オプションの引数が、形式 filename.d で、 -o が存在していないなら、デフォルトの出力ファイルは、 filename.o です。そうでなければ、デフォルトの出力ファイルは、 d.out です。
-p pid
指定されたプロセス ID pid を grab (とらえる) し、シンボルテーブルをキャッシュし、完了すれば終了します。コマンド行に 2 つ以上の -p オプションが存在しているなら、 dtrace は、終了した各プロセスの終了ステータスを報告して、すべてのコマンドが終了したとき、終了します。最初のプロセス ID は、コマンド行で指定されるあらゆる D プログラム、または $target マクロ変数を通して -s オプションを使用して利用可能とされます。
-P provider [ [ predicate] action]
トレースまたはリスト ( -l オプション) するプロバイダ名を指定します。残っているプローブ記述フィールドのモジュール、関数と名前は、空白のままにされ、それらのフィールドの値にかかわらずあらゆるプローブに一致します。オプションの D プローブ節で -P 引数を末尾に付けることができます。利用者は、一度に、コマンド行で 2 つの以上の -P オプションを指定することができます。
-q
quiet (静かな) モードに設定します。 dtrace は、指定されたオプションと D プログラムによって一致されたプローブの数のようなメッセージを削除して、カラムヘッダ、CPU ID、プローブ ID を印刷せず、または改行文字を出力に挿入します。‘ dtrace()’と‘ printf()’のような D プログラム文によってトレースされ、書式化されるデータのみが、標準出力に表示されます。
-s script
指定された D プログラムのソースファイルをコンパイルします。 -e オプションが存在しているなら、プログラムは、コンパイルされますが、計装 (instrumentation) は、有効にされません。 -l オプションが存在しているなら、プログラムは、コンパイルされ、それと一致するプローブのセットは、リストされますが、計装は、有効にされません。 -e, -l, -G または -A のいずれも存在していないなら、D プログラムによって指定された計装は、有効にされ、トレースは、始まります。
-S
D コンパイラの中間コードを表示します。 D コンパイラは、それぞれの D プログラムのために生成された中間コードのレポートを標準エラーに出力します。
-U name
( -C オプションを使用して有効にされる) cpp(1) を呼び出すとき、指定された name を未定義とします。このオプションは、それぞれの cpp(1) 呼び出しに -U オプションを渡します。
-v
verbose (冗長) モードを設定します。 -v オプションが指定されるなら、 dtrace は、指定された D プログラムのために最小のインタフェースの安定性と依存レベルを表示したプログラム安定性レポートを作成します。
-V
dtrace によってサポートされた最も高い D プログラミングのインタフェースバージョンを報告します。バージョン情報は、標準出力に印刷 (出力) され、 dtrace コマンドは、終了します。
-w
-s, -P, -m, -f, -n または -i オプションを使用して指定された D プログラムの破壊的な動作を許可にします。 -w オプションが指定されないなら、 dtrace は、破壊的な動作を含む D プログラムのコンパイルまたは有効にすることを許可しません。
-x arg [ =value]
DTrace ランタイムオプションまたは D コンパイラオプションを有効にするか、または変更します。ブール値オプションは、それらの名前を指定することによって、有効にされます。値があるオプションは、等号 (=) でオプション名と値を分けることによって設定されます。
-X a | c | s | t
( -C オプションを使用して有効にされる) cpp(1) を呼び出すとき、選択されるべきである ISO C 規格への準拠の度合いを指定します。 -X オプション引数は、引数文字の値に依存する __STDC__ マクロの値と存在に影響します。
 
-X オプションは、次の引数をサポートします:
a
デフォルトです。 ISO C によって要求されたセマンティック (意味論) の変更がある、 ISO C と K&R 互換性の拡張。これは、 -X が指定されないなら、デフォルトのモードです。 cpp(1) が、 -Xa オプションに関連して呼び出されるとき、事前に定義されたマクロ __STDC__ は、 0 の値があります。
c
適合しています。 K&R C 互換性の拡張がない、厳密な適合 ISO C。 cpp(1)-Xc オプションに関連して呼び出されるとき、事前に定義されたマクロ __STDC__ は、 1 の値があります。
s
K&R C のみ。 cpp(1)-Xs オプションに関連して呼び出されるとき、マクロ __STDC__ は、定義されません。
t
遷移。 ISO C によって要求されたセマンティック (意味論) の変更がない、 ISO C と K&R 互換性の拡張。 cpp(1)-Xt オプションに関連して呼び出されるとき、事前に定義されたマクロ __STDC__ は、 0 の値があります。

-X オプションが D コンパイラがどのように C プリプロセッサを呼び出すかに影響するだけであるように、 -Xa-Xt オプションは、D の視点と同等であり、両方とも、C 構築環境から設定の再使用を軽減するためにだけに提供されます。

-X モードにかかわらず、次の追加 C プリプロセッサ定義は、すべてのモードで常に指定されて有効です:

  • __sun
  • __unix
  • __SVR4
  • __sparc (SPARC システムだけで)
  • __sparcv9 (64 ビットのプログラムがコンパイルされるとき, SPARC システムだけで)
  • __i386 (32 ビットのプログラムがコンパイルされるとき, x86 システムだけで)
  • __amd64 (64 ビットのプログラムがコンパイルされるとき, x86 システムだけで)
  • __`uname -s`_`uname -r` (例えば, ‘ FreeBSD_9.2-RELEASE’)
  • __SUNW_D=1
  • __SUNW_D_VERSION=0x MMmmmuuu

    ここで、 MM は、16 進数のメジャーリリース値で、 mmm は、16 進数のマイナリリース値で、そして、 uuu は、16 進数のマイクロリリース値です。

-Z
0 のブローブに一致するプローブ記述を許可します。 -Z オプションが指定されないなら、 dtrace は、エラーを報告し、D プログラムファイル ( -s オプション) で指定された任意のプローブ記述、またはコマンド行 ( -P, -m, -f, -n または -i オプション) で、あらゆる知られているプローブに一致しない記述を含んでいるなら、終了します。

オペランド

利用者は、1 組のマクロ変数 ($1, $2 その他) を定義するために dtrace コマンド行で、0 以上の追加引数を指定することができます。 -s オプションを使用して指定された D プログラムまたはコマンド行で追加引数を使用することができます。

関連ファイル

/boot/dtrace.dof
匿名のトレース指示のためのファイル。

終了ステータス

次の終了ステータスが返されます:
0
成功して終了。

D プログラム要求について、0 の終了ステータスは、プログラムが成功してコンパイルされた、プローブが成功して有効にされたか、または匿名の状態が、成功して検索されたことを示します。 dtrace は、たとえ指定されたトレース要求がエラーまたは低下 (drop) に遭遇したとしても、0 を返します。

1
エラーが起こりました。

D プログラム要求について、1 の終了ステータスは、プログラムのコンパイルが失敗したか、または指定された要求を、満たすことができなかったことを示します。

2
不正なコマンド行オプションまたは引数が指定されました。

関連項目

cpp(1), dtruss(1), elf(5) Solaris Dynamic Tracing Guide.
October 5, 2013 FreeBSD