dtrace - DTrace 動的トレースコンパイラおよびトレースユーティリティー
dtrace [-32 | -64] [-aACeFGHhlqSvVwZ] [-b bufsz] [-c cmd] [-D name [=value]] [-I path] [-L path] [-o output] [-s script] [-U name] [-x arg [=val]] [-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 が提供する強力なインフラストラクチャーを使えば、管理者、開発者、およびサービス担当者は、オペレーティングシステムやユーザープログラムの動作に関するさまざまな質問に対して、簡潔に答えることができるようになります。
Oracle Solaris 11.4 DTrace (Dynamic Tracing) Guideでは、DTrace を使用してシステムの動作を監視、デバッグ、およびチューニングする方法について説明します。バンドルされている DTrace の監視ツール、計測プロバイダ、D プログラミング言語など、DTrace の各種機能の詳細については、このマニュアルを参照してください。
dtrace コマンドは、DTrace 機能が提供する基本サービスに対する汎用インタフェースを提供します。それらを次に示します。
DTrace によって現在公開されている一連のプローブやプロバイダを一覧表示するためのオプション
任意のプローブ記述指定子 (provider、module、function、name) を使ってプローブを直接有効にするためのオプション
D コンパイラを実行し、1 つ以上の D プログラムファイルまたはコマンド行に直接記述されたプログラムをコンパイルするためのオプション
匿名トレースプログラムを生成するためのオプション
プログラム安定性レポートを生成するためのオプション
DTrace のトレース動作やバッファリング動作を変更したり、追加の D コンパイラ機能を有効化したりするためのオプション
dtrace を使えば、D スクリプトを作成できます。それには、#! 宣言内にこの dtrace を指定してインタプリタファイルを作成します。また、dtrace を使えば、実際に –e オプションを使用してトレースを有効化することなく D プログラムのコンパイルを試行し、そのプロパティーを決定することもできます。詳しくは「オプション」の項を参照してください。dtrace ユーティリティーを使ってこれらのタスクを実行する方法の詳しい例については、Oracle Solaris 11.4 DTrace (Dynamic Tracing) Guideを参照してください。
–P、–m、–f、–n、および –i オプションが受け入れる引数には、1 つの D 言語 predicate をスラッシュ // で囲んだものと、一連の D 言語 action 文を中括弧 {} で囲んだものを、オプションで含めることができます。コマンド行で指定される D プログラムのコードは、メタ文字がシェルによって解釈されてしまわないように、適切に引用符で囲む必要があります。
サポートしているオプションは、次のとおりです。
D コンパイラは、オペレーティングシステムカーネルのネイティブデータモデルを使ってプログラムを生成します。isainfo –b コマンドを使えば、現在のオペレーティングシステムのデータモデルを確認できます。–32 オプションが指定された場合、dtrace は、32 ビットデータモデルを使って D プログラムをコンパイルするよう、D コンパイラに指示します。–64 オプションが指定された場合、dtrace は、64 ビットデータモデルを使って D プログラムをコンパイルするよう、D コンパイラに指示します。通常、これらのオプションを指定する必要はありません。オプションを省略しても、dtrace は、自動的にネイティブデータモデルを選択します。データモデルは、整数型のサイズとその他の言語プロパティに影響を及ぼします。いずれかのデータモデル用にコンパイルされた D プログラムは、32 ビットカーネル上でも、64 ビットカーネル上でも実行できます。オプション –32 と –64 では、–G オプションを指定したとき生成される ELF ファイルの形式 (ELF32 または ELF64) も指定できます。
匿名トレース状態を要求し、トレースされたデータを表示します。–a オプションと –e オプションを併用した場合、dtrace は、匿名トレース状態の終了後、新しいデータを待たずにただちに終了します。匿名トレースの詳細は、Oracle Solaris 11.4 DTrace (Dynamic Tracing) Guideを参照してください。
匿名トレース用の driver.conf(5) 指令を生成します。このオプションは、指定されたプローブが匿名トレース用に有効化されてから終了するまでの一連の dtrace(4D) 構成ファイルディレクティブを作成します。By default, dtrace attempts to store the directives to the file /etc/kernel/drv/dtrace.conf.–o オプションを使って別の出力ファイルを指定すれば、この動作を変更できます。
主トレースバッファーサイズ (bufsz) を設定します。このトレースバッファーサイズには、サイズサフィックス k、m、g、t のいずれかを含めることができます。dtrace は、バッファー領域の割り当てに失敗すると、バッファーサイズを減らそうとするか、終了します。どちらになるかは、bufresize プロパティーの設定によります。
指定されたコマンド cmd を実行し、その実行が完了したら終了します。コマンド行に –c オプションが複数指定されている場合、dtrace は、すべてのコマンドの終了後に終了しますが、それぞれの子プロセスが終了するたびにその終了ステータスを報告します。最初のコマンドのプロセス ID は、マクロ変数 $target により、コマンド行または –s オプションを使って指定された任意のプログラムに渡されます。マクロ変数の詳細は、Oracle Solaris 11.4 DTrace (Dynamic Tracing) Guideを参照してください。
D プログラムをコンパイルする前に、それらのプログラムに対して C プリプロセッサ cpp(1) を実行します。–D、–U、–I、–H の各オプションを使えば、C プリプロセッサにオプションを渡すことができます。–X オプションを使えば、C 標準への準拠レベルを選択できます。C プリプロセッサの呼び出し時に D コンパイラによって定義される一連のトークンについては、–X を参照してください。
–C オプションで有効化された cpp (1) を呼び出す際に、name を定義します。等号 (=) と追加の value を指定した場合、名前に対応する値が代入されます。このオプションは、cpp が呼び出されるたびに、それに –D オプションを渡します。
すべての要求をコンパイルし、匿名トレース状態を消費し終わったあと (–a オプション)、プローブを有効化する前に終了します。このオプションを –a オプションと組み合わせれば、匿名トレースデータを出力してから終了させることができます。このオプションを D コンパイラのオプションと組み合わせることもできます。この組み合わせを使用した場合、プログラムがコンパイルされるかどうかの検証は行われますが、それらのプログラムが実際に実行されたり対応する計測機能が有効化されたりすることはありません。
トレースまたは一覧表示 (–l オプション) の対象となる関数名を指定します。対応する引数には、プローブ記述形式 provider:module:function、module:function、function のいずれかを含めることができます。指定しなかったプローブ記述フィールドは空になります。この場合、これらのフィールドの値とは関係なくすべてのプローブが選択されます。function 以外の修飾子を指定しなかった場合、対応する function を持つすべてのプローブが選択されます。–f の引数の後にはオプションで、D プローブ節を付加することもできます。–f オプションは、コマンド行で一度に複数指定できます。
関数の開始 (entry) と終了 (return) を識別することにより、トレース出力をひとつにまとめます。関数の entry プローブの報告はインデントされ、 -> の後ろに出力されます。関数終了プローブのレポートはインデント解除され、<- の後ろに出力されます。システムコール開始プローブのレポートはインデントされ、=> の後ろに出力されます。システムコール終了プローブのレポートはインデント解除され、<= の後ろに出力されます。
埋め込まれた DTrace プログラムを含む ELF ファイルを生成します。プログラム内に指定された DTrace プローブは、ELF オブジェクトの内側に保存されます。このオブジェクトは再配置可能であり、別のプログラムにリンクできます。–o オプションが指定されている場合、ELF ファイルは、このオペランドの引数として指定されたパス名で保存されます。–o オプションが存在しておらず、かつ filename.d という名前のファイルに DTrace プログラムが格納されている場合、ELF ファイルは、 filename.o という名前で保存されます。それ以外の場合、ELF ファイルは名前 d.out として保存されます。
–C オプションで有効化された cpp(1) を呼び出す際に、インクルードされたファイルのパス名を出力します。このオプションは、cpp が呼び出されるたびに、それに –H オプションを渡します。その結果、一連のパス名が 1 行に 1 つずつ、stderr に出力されます。
指定したプロバイダ定義内のプローブに対応するマクロを格納するヘッダーファイルを生成します。このオプションは、あとで –G オプションとともに使用するほかのソースファイルによってインクルードされるヘッダーファイルを生成する場合に使用してください。–o オプションが存在している場合、ヘッダーファイルはこのオプションの引数として指定されたパス名を使って保存されます。–o オプションが存在せず、かつ DTrace プログラムが filename.d というファイルに格納されている場合、ヘッダーファイルは名前 filename.h として保存されます。
トレースまたは一覧表示 (–l オプション) の対象となるプローブ ID (probe-id) を指定します。プローブ ID を指定する際には、dtrace –l で表示される 10 進整数を使用します。–i の引数には、後ろに任意の D プローブ節を 1 つ付加できます。–i オプションは一度に複数指定できます。
–C オプションで有効化された cpp(1) を呼び出す際に、指定されたディレクトリ path を #include ファイルの検索パスに追加します。このオプションは、cpp の呼び出しのたびに –I オプションを渡します。指定された path は、検索パス内のデフォルトディレクトリリストの前に挿入されます。
指定されたディレクトリ path を、DTrace ライブラリの検索パスに追加します。DTrace ライブラリは、D プログラムを記述する際に使用可能な共通定義を格納する目的で使用されます。このオプションで指定された path は、デフォルトのライブラリ検索パスの後ろに追加されます。
プローブを有効化しないで一覧表示します。–l オプションが指定された場合、dtrace は、–P、–m、–f、–n、–i、–s の各オプションを使って指定された記述に一致するプローブのレポートを生成します。これらのオプションが 1 つも指定されなかった場合、このオプションはすべてのプローブを一覧表示します。
トレースまたは一覧表示 (–l オプション) の対象となるモジュール名を指定します。対応する引数には、プローブ記述形式 provider:module、module のいずれかを含めることができます。指定しなかったプローブ記述フィールドは空になります。この場合、これらのフィールドの値とは関係なくすべてのプローブが選択されます。module 以外の修飾子を指定しなかった場合、対応する module を持つすべてのプローブが選択されます。–m の引数には、後ろに任意の D プローブ節を 1 つ付加できます。–m オプションは、コマンド行で一度に複数指定できます。
トレースまたは一覧表示 (–l オプション) の対象となるプローブ名を指定します。対応する引数には、プローブ記述形式 provider:module:function:name、module:function:name、function:name、name のいずれかを含めることができます。指定しなかったプローブ記述フィールドは空になります。この場合、これらのフィールドの値とは関係なくすべてのプローブが選択されます。name 以外の修飾子を指定しなかった場合、対応する name を持つすべてのプローブが選択されます。–n の引数には、後ろに任意の D プローブ節を 1 つ付加できます。–n オプションは、コマンド行で一度に複数指定できます。
Specify the output file for the –A, –G, –h, and –l options, or for the traced data itself.If the –A option is present and –o is not present, the default output file is /etc/kernel/drv/dtrace.conf.If the –G option is present and the –s option's argument is of the form filename.d and –o is not present, the default output file is filename.o.それ以外の場合、デフォルトの出力ファイルは d.out になります。
–o オプションを使って dtrace を連続して呼び出すと、dtrace は上書きするのではなく、出力ファイルに追加します。
指定されたプロセス ID pid を獲得し、そのシンボルテーブルをキャッシュし、その実行が完了したら終了します。コマンド行に –p オプションを 2 つ以上指定した場合、dtrace は、プロセスが終了するたびに終了ステータスを報告し、すべてのコマンドが終了した時点で終了します。最初のプロセス ID は、マクロ変数 $target により、コマンド行または –s オプションを使って指定された任意の D プログラムに渡されます。マクロ変数の詳細は、Oracle Solaris 11.4 DTrace (Dynamic Tracing) Guideを参照してください。
トレースまたは一覧表示 (–l オプション) の対象となるプロバイダ名を指定します。残りのプローブ記述フィールド (module、function、name) は空になります。したがって、これらのフィールドの値とは関係なく、すべてのプローブが選択されます。–P の引数には、後ろに任意の D プローブ節を 1 つ付加できます。–P オプションは、コマンド行で一度に複数指定できます。
非出力モードを設定します。dtrace は、指定されたオプションや D プログラムの条件に一致するプローブ数などのメッセージを抑制し、列ヘッダーの CPU ID や プローブ ID を出力しなくなるほか、出力に改行を挿入しなくなります。trace() や printf() といった D プログラム文によってトレースおよび書式設定されたデータのみが、stdout に表示されます。
指定された D プログラムのソースファイルをコンパイルします。–e オプションが存在している場合、プログラムのコンパイルは行われますが、計測機能は有効化されません。–l オプションが存在している場合、プログラムのコンパイルと一致するプローブの一覧表示は行われますが、計測機能は有効化されません。–e、–l、–G、–A のいずれも存在しない場合には、D プログラムによって指定された計測機能が有効化され、トレースが開始されます。
D コンパイラの中間コードを表示します。D コンパイラは、個々の D プログラムごとに生成された中間コードに関するレポートを生成し、stderr に出力します。
–C オプションで有効化された cpp(1) を呼び出す際に、指定された name を未定義にします。このオプションは、cpp が呼び出されるたびに、それに –U オプションを渡します。
冗長モードを設定します。–v オプションを指定すると、dtrace はプログラム安定性レポートを生成します。このレポートには、指定された D プログラムについて最低限のインタフェースの安定性レベルと依存性レベルが示されます。DTrace の安定性レベルについては、Oracle Solaris 11.4 DTrace (Dynamic Tracing) Guideに詳しく記載されています。
dtrace がサポートする D プログラミングインタフェースのバージョンのうち、もっとも高いバージョンを報告します。このバージョン情報が stdout に出力されたあと、dtrace コマンドは終了します。DTrace のバージョン管理機能の詳細は、Oracle Solaris 11.4 DTrace (Dynamic Tracing) Guideを参照してください。
–s、–P、–m、–f、–n、–i のいずれかのオプションで指定された D プログラム内で、破壊アクションを使用できるようにします。–w オプションが指定されなかった場合、dtrace は、破壊アクションを含む D プログラムのコンパイルや有効化を許可しません。
DTrace の実行時オプションまたは D コンパイラオプションを有効化または変更します。オプションのリストは、Oracle Solaris 11.4 DTrace (Dynamic Tracing) Guideに記載されています。ブール型のオプションを有効にするときは、その名前を指定します。値を持つオプションを設定するには、オプションの名前と値を等号 (=) で分離します。
オプション –C オプションで有効化された cpp(1) を呼び出すとき、ISO C 標準にどの程度まで準拠させるかを指定します。–X オプションの引数は、__STDC__ マクロの値やその存在有無に影響を与えますが、具体的にどのような影響を与えるかは、この引数の文字の値によります。
–X オプションでサポートされる引数は、次のとおりです。
デフォルト。ISO C ＋ K&R 互換性拡張 (ISO C が要求するセマンティック変更あり)。–X が指定されない場合、これがデフォルトモードです。–Xa オプションが指定されている場合、cpp を呼び出したときの定義済みマクロ __STDC__ の値はゼロになります。
準拠。ISO C に完全準拠。K&R C 互換性拡張機能はありません。cpp 呼び出し時に –Xc オプションが指定された場合、定義済みマクロ __STDC__ の値は 1 になります。
K&R C のみ。cpp 呼び出し時に –Xs オプションが指定された場合、マクロ __STDC__ は未定義になります。
移行。ISO C ＋ K&R C 互換性拡張 (ISO C が要求するセマンティック変更なし)。–Xt オプション付きで cpp が呼び出されると、定義済みマクロ __STDC__ は値ゼロです。
–X オプションは D コンパイラが C プリプロセッサを呼び出す方法にのみ影響を与えるため、–Xa オプションと –Xt オプションは、D から見れば等価です。それでもその両方が提供されているのは、C 構築環境の設定を再利用しやすくするためです。
次の追加 C プリプロセッサ定義は、–X モードの内容にかかわらず、すべてのモードで常に指定され、有効になります。
__sun
__unix
__SVR4
__sparc (SPARC システム上でのみ)
__sparcv9 (SPARC システム上で 64 ビットプログラムをコンパイルする場合のみ)
__i386 (x86 システム上で 32 ビットプログラムをコンパイルする場合のみ)
__amd64 (x86 システム上で 64 ビットプログラムをコンパイルする場合のみ)
__`uname -s`_`uname -r` (例: __SunOS_5_10)
__SUNW_D=1
__SUNW_D_VERSION=0xMMmmmuuu
ここで、MM は 16 進のメジャーリリース値、mmm は 16 進のマイナーリリース値、uuu は 16 進のマイクロリリース値です。DTrace のバージョン管理の詳細は、Oracle Solaris 11.4 DTrace (Dynamic Tracing) Guideを参照してください。
一致するプローブが 1 つも見つからないようなプローブ記述を許可します。–Z オプションが指定されない場合、D プログラムファイル内で指定されたプローブ記述 (–s オプション) またはコマンド行で指定されたプローブ記述 (–P、–m、–f、–n、または –i オプション) の中で、既知のどのプローブにも一致しないような記述を含むプローブ記述が見つかると、dtrace はエラーを報告し、処理を終了します。
dtrace コマンド行に 0 個以上の追加引数を指定し、一連のマクロ変数 ($1 や $2 など) を定義することができます。これらの追加引数は、–s オプションを使って指定された D プログラム内またはコマンド行から指定された D プログラム内で使用できます。マクロ変数の使用法については、Oracle Solaris 11.4 DTrace (Dynamic Tracing) Guideに詳しく記載されています。
次の終了ステータスが返されます。
正常終了。
D プログラム要求の場合、終了ステータス 0 は、プログラムのコンパイル、プローブの有効化、匿名ステータスの取得、のいずれかが成功したことを示します。指定されたトレース要求でエラーや欠落が発生した場合でも、dtrace は 0 を返します。
エラーが発生しました。
D プログラム要求の場合、終了ステータス 1 は、プログラムのコンパイルが失敗したか、指定された要求に応じられなかったことを示します。
コマンド行に無効なオプションまたは引数が指定されました。
属性についての詳細は、マニュアルページの attributes(7) を参照してください。
|
コマンド行の構文は「確実」です。人間が読める形式の出力は「不確実」です。
cpp(1)、isainfo(1)、ssh(1)、libdtrace(3LIB)、dtrace(4D)、driver.conf(5)、attributes(7)
Oracle Solaris 11.4 DTrace (Dynamic Tracing) Guide
–p フラグを使用している場合、ターゲットプロセスを検査し、結果を報告している間、dtrace はターゲットプロセスを停止します。停止中のプロセスは何も実行できません。つまり、たとえば X サーバーが、X サーバーの制御下にあるウィンドウで実行されている dtrace によって検査される場合、proc ツールはリフレッシュできないウィンドウに結果を表示しようとするため、ウィンドウシステム全体がデッドロックになる可能性があります。このような場合は、ssh(1) を使用して別のシステムからログインし、問題のある proc ツールを強制終了すると、デッドロックが解消されます。