第 14 章 dtrace(1M) ユーティリティー

dtrace(1M) は、DTrace 機能の汎用フロントエンドとして機能します。このコマンドは、D 言語のコンパイラを呼び出すシンプルなインタフェースを備えています。このコマンドでは、DTrace のカーネル機構からバッファーに格納されたトレースデータを取り出したり、一連の基本的なルーチンを使って、トレースデータに書式を設定して出力できます。この章では、dtrace コマンドの全般的なリファレンス情報を提供します。

説明

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

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

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

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

• 匿名トレースプログラムを生成するオプション (第 36 章匿名トレースを参照)

• プログラムの安定性に関するレポートを生成するオプション (第 39 章安定性を参照)

• DTrace のトレースとバッファリングの動作に変更を加え、新しい D コンパイラ機能を利用できるようにするオプション (第 16 章オプションとチューニング可能パラメータを参照)

インタプリタファイルを作成するために #! で始まる宣言内で dtrace を使用すると、D スクリプトを作成できます (第 15 章スクリプトの作成を参照)。dtrace を使って、D プログラムのコンパイルを試行し、そのプロパティを特定することもできます。この処理は、以下で説明する -e オプションを指定してトレースを有効にすることなしにできます。

オプション

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

dtrace [-32 | -64] [-aACeFGHlqSvVwZ] [-b bufsz] [-c cmd] [-D name [=def]] [-I path] [-L path] [-o output] [-p pid] [-s script] [-U name] [-x arg [=val]] [-Xa | c | s | t] [-P provider [ [述語]アクション]] [-m [ [provider:]module [ [述語]アクション]]] [-f [ [provider:]module:]func [ [述語]アクション]] [-n [ [ [provider:]module:]func:]name [ [述語]アクション]] [-i probe-id [ [述語]アクション]]

すでに説明した D 言語の構文に従って、predicate は任意の D 述語をスラッシュ (//) で囲んだ形式、action は任意の D 文のリストを中括弧 ({ }) で囲んだ形式で指定します。オプション -P、-m、-f、-n、または -i の引数として D プログラムコードを指定する場合、シェルによる解釈処理を防ぐため、このプログラムコードのテキストを適切な引用記号で囲む必要があります。指定できるオプションは、次のとおりです。

-32、-64

D コンパイラは、オペレーティングシステムカーネルのネイティブデータモデルを使ってプログラムを生成します。現在のオペレーティングシステムのデータモデルを特定するには、isainfo(1) -b コマンドを実行します。-32 を指定すると、D コンパイラは、32 ビットデータモデルに従って、D プログラムをコンパイルするようになります。-64 を指定すると、D コンパイラは、64 ビットデータモデルに従って、D プログラムをコンパイルするようになります。通常、これらのオプションを指定する必要はありません。オプションを省略しても、dtrace は、自動的にネイティブデータモデルを選択します。データモデルは、整数型のサイズとその他の言語プロパティに影響を及ぼします。D プログラムがどのデータモデル用にコンパイルされたものであっても、32 ビットと 64 ビットの両方のカーネルで実行できます。オプション -32 と -64 では、-G オプションを指定したとき生成される ELF ファイルの形式 (ELF32 または ELF64) も指定できます。

-a

匿名トレースの状態を要求し、トレースデータを表示します。-a オプションと -e オプションを併用した場合、dtrace は、匿名トレース状態の終了後、新しいデータを待たずにただちに終了します。匿名トレースの詳細については、第 36 章匿名トレースを参照してください。

-A

匿名トレース用として、driver.conf(4) 指令を生成します。-A オプションを指定した場合、dtrace は、すべての D プログラム (-s オプションで指定されたものとコマンド行で指定されたものを含む) をコンパイルし、dtrace(7D) 構成ファイル指令のセットを作成して、指定された匿名トレース (第 36 章匿名トレースを参照) 用のプローブを有効にしてから、終了します。デフォルトでは、dtrace は、指令を /kernel/drv/dtrace.conf ファイルに格納します。これ以外の出力ファイルは、-o オプションで指定できます。

-b

主トレースバッファーのサイズ bufsz を設定します。トレースバッファーサイズを指定するときは、サイズ接尾辞として、k、m、g、t のいずれかを追加できます。詳細については、第 36 章匿名トレースを参照してください。バッファー容量を割り当てることができない場合、dtrace は、bufresize プロパティの設定内容に従って、バッファーサイズを小さくするか終了するかします。

-c

指定されたコマンド cmd を実行し、コマンドの実行が完了したら終了します。コマンド行に -c オプションを 2 つ以上指定した場合、dtrace は、子プロセスが終了するたびに終了状態を報告し、すべてのコマンドが終了した時点で終了します。最初のコマンドのプロセス ID は、マクロ変数 $target により、コマンド行または -s オプションを使って指定された任意のプログラムに渡されます。マクロ変数の詳細については、第 15 章スクリプトの作成を参照してください。

-C

D プログラムをコンパイルする前に、C プリプロセッサ cpp(1) を適用します。C プリプロセッサのオプションは、-D、-U、-I、および -H で指定します。どの程度まで C 標準に準拠させるかは、-X オプションで指定します。C プリプロセッサの呼び出し時に D コンパイラによって定義されるトークンセットについては、-X オプションの説明を参照してください。

-D

-C オプションで有効化された cpp(1) を呼び出すとき、指定された名前 name を定義します。等号 (=) と追加の値 value が指定されている場合、対応する値が名前として割り当てられます。このオプションは、cpp の呼び出しのたびに -D オプションを渡します。

-e

要求に応じてコンパイルを行い、匿名トレース状態 (-a オプションで指定) が終了したあと、プローブの有効化を行う前に終了します。匿名トレースデータの出力後に終了したい場合は、このオプションと -a オプションを併用します。プログラムを実際に実行せず、対応する計測機能を有効にしないでプログラムがコンパイルされたことを検証したい場合は、このオプションと D コンパイラオプションを併用します。

-f

トレースする関数名を指定します。関数名を一覧表示するときは -l オプションを使用します。引数は、provider:module:function、module:function、function のいずれかのプローブ記述形式で指定します。指定しなかったプローブ記述フィールドは空になります。この場合、これらのフィールドの値とは関係なくすべてのプローブが選択されます。function 以外の修飾子を指定しなかった場合、対応する function を持つすべてのプローブが選択されます。-f の引数には、後ろに任意の D プローブ節を 1 つ付加できます。コマンド行には、複数の -f オプションを同時に指定できます。

-F

関数の開始 (entry) と終了 (return) を識別することにより、トレース出力をひとつにまとめます。関数の entry プローブの報告はインデントされ、 -> の後ろに出力されます。関数の return プローブの報告はインデント解除され、<- の後ろに出力されます。

-G

組み込み DTrace プログラムが格納された ELF ファイルを生成します。プログラム内に指定された DTrace プローブは、ELF オブジェクト内に格納されます。この ELF オブジェクトは再配置可能で、別のプログラムにリンクできます。-o オプションが指定されている場合、ELF ファイルは、このオペランドの引数として指定されたパス名で保存されます。-o オプションが指定されておらず、DTrace プログラムが filename.s という名前のファイルに含まれている場合、ELF ファイルは file.o という名前で保存されます。これ以外の場合は、d.out という名前で保存されます。

-H

-C オプションで有効化された cpp(1) を呼び出すとき、インクルードファイルのパス名を出力します。このオプションは、cpp 呼び出しのたびに -H オプションを渡します。このため、1 行に 1 つずつパス名が stderr に表示されます。

-i

トレースするプローブ ID を指定します。プローブ ID を一覧表示するときは -l オプションを使用します。プローブ ID は、dtrace -l の場合と同じく、10 進整数で指定します。-i の引数には、後ろに任意の D プローブ節を 1 つ付加できます。コマンド行には、複数の -i オプションを同時に指定できます。

-I

-C オプションで有効化された cpp(1) を呼び出すときに、#include ファイルの検索パスに指定のディレクトリパス path を追加します。このオプションは、cpp の呼び出しのたびに -I オプションを渡します。このオプションで指定されたディレクトリは、デフォルトのディレクトリリストの前の検索パスに追加されます。

-l

プローブを有効化しないで、一覧表示します。-l オプションを指定した場合、dtrace は、オプション -P、-m、-f、-n、-i、および -s で指定された内容に一致するプローブのレポートを生成します。これらのオプションが省略されている場合は、すべてのプローブを一覧表示します。

-L

DTrace ライブラリの検索パスに、指定のディレクトリパス path を追加します。DTrace ライブラリには、D プログラムを作成する際に使用できる一般的な定義が収められています。このオプションで指定された path は、デフォルトのライブラリ検索パスの後ろに追加されます。

-m

トレースするモジュール名を指定します。モジュール名を一覧表示するときは -l オプションを使用します。引数は、provider:module または module のプローブ記述形式で指定します。指定しなかったプローブ記述フィールドは空になります。この場合、これらのフィールドの値とは関係なくすべてのプローブが選択されます。module 以外の修飾子を指定しなかった場合、対応する module を持つすべてのプローブが選択されます。-m の引数には、後ろに任意の D プローブ節を 1 つ付加できます。コマンド行には、複数の -m オプションを同時に指定できます。

-n

トレースするプローブ名を指定します。プローブ名を一覧表示するときは -l オプションを使用します。引数は、provider:module:function:name、module:function:name、function:name、name のいずれかのプローブ記述形式で指定します。指定しなかったプローブ記述フィールドは空になります。この場合、これらのフィールドの値とは関係なくすべてのプローブが選択されます。name 以外の修飾子を指定しなかった場合、対応する name を持つすべてのプローブが選択されます。-n の引数には、後ろに任意の D プローブ節を 1 つ付加できます。コマンド行には、複数の -n オプションを同時に指定できます。

-o

A、-G、-l オプションの出力ファイル、またはトレースデータの出力ファイルを、-output で指定します。-A オプションが指定されていて -o オプションが指定されていない場合、デフォルトの出力ファイルは /kernel/drv/dtrace.conf になります。-G オプションが指定されていて、-s オプションに filename.d の形式で引数が指定されていて、かつ -o オプションが指定されていない場合、デフォルトの出力ファイルは filename.o になります。これ以外の場合、デフォルトの出力ファイルは d.out になります。

-p

指定のプロセス ID pid を取り込み、シンボルテーブルをキャッシュに格納します。その後、このプロセスが完了した時点で終了します。コマンド行に -p オプションを 2 つ以上指定した場合、dtrace は、プロセスが終了するたびに終了状態を報告し、すべてのコマンドが終了した時点で終了します。最初のプロセス ID は、マクロ変数 $target により、コマンド行または -s オプションを使って指定された任意の D プログラムに渡されます。マクロ変数の詳細については、第 15 章スクリプトの作成を参照してください。

-P

トレースするプロバイダ名を指定します。プロバイダ名を一覧表示するときは -l オプションを使用します。残りのプローブ記述フィールド (module、function、name) は空になります。したがって、これらのフィールドの値とは関係なく、すべてのプローブが選択されます。-P の引数には、後ろに任意の D プローブ節を 1 つ付加できます。コマンド行には、複数の -P オプションを同時に指定できます。

-q

非出力モードに設定します。この場合、dtrace はメッセージを抑制し、指定されたオプションや D プログラムと一致するプローブ数などを出力しなくなります。このほか、列ヘッダー、CPU ID、プローブ ID も出力対象から除外され、改行文字が挿入されるだけになります。trace()、printf() などの D プログラム文でトレースされ、書式設定されたデータだけが、stdout に出力されます。

-s

指定された D プログラムソースファイルをコンパイルします。-e オプションが指定されている場合、プログラムのコンパイルは行われますが、計測機能は有効化されません。-l オプションが指定されている場合、プログラムのコンパイルが行われ、一致するプローブのセットが一覧表示されます。しかし、計測機能は有効化されません。-e オプションも -l オプションも指定されていない場合、D プログラムで指定された計測機能が有効化され、トレースが開始されます。

-S

D コンパイラの中間コードを表示します。D コンパイラは、D プログラムごとに中間コードのレポートを生成し、stderr に渡します。

-U

-C オプションで有効化された cpp(1) を呼び出すとき、指定された名前 name を未定義にします。このオプションは、cpp の呼び出しのたびに -U オプションを渡します。

-v

冗長モードに設定します。-v オプションを指定すると、dtrace はプログラム安定性レポートを生成します。このレポートには、指定された D プログラムについて最低限のインタフェースの安定性レベルと依存性レベルが示されます。DTrace の安定性レベルについては、第 39 章安定性で詳しく説明します。

-V

dtrace でサポートされる最新バージョンの D プログラミングインタフェースを報告します。バージョン情報が stdout に出力されると、dtrace コマンドは終了します。DTrace のバージョン管理機能の詳細については、第 41 章バージョン管理を参照してください。

-w

-s、-P、-m、-f、-n、-i のいずれかのオプションで指定された D プログラム内で、破壊アクションを使用できるようにします。-w オプションが指定されていない場合、破壊アクションを含む D プログラムをコンパイルすることはできません。また、このプログラムを有効化することもできません。破壊アクションの詳細については、第 10 章アクションとサブルーチンを参照してください。

-x

DTrace 実行時オプションや D コンパイラオプションを有効化したり、変更したりします。それらのオプションについては、第 16 章オプションとチューニング可能パラメータを参照してください。ブール型のオプションを有効にするときは、その名前を指定します。値を持つオプションを設定するときは、オプション名と値 val を等号 (=) で結びます。

-X

-C オプションで有効化された cpp(1) を呼び出すとき、ISO C 標準にどの程度まで準拠させるかを指定します。-X オプションの引数は、次のいずれかの文字になります。どの文字が指定されたかによって、__STDC__ マクロの値や、このマクロが使用されるかどうかが決定されます。

a (デフォルト)

ISO C と K&R の互換性拡張機能。ISO C により、セマンティクスの変更が要求されます。-X オプションが指定されていない場合は、このモードがデフォルトになります。-Xa オプションが指定されている場合、cpp を呼び出したときの定義済みマクロ __STDC__ の値はゼロになります。

c (準拠)

ISO C に完全準拠。K&R C 互換性拡張機能はありません。-Xc オプションが指定されている場合、cpp を呼び出したときの定義済みマクロ __STDC__ の値は 1 になります。

s (K&R C)

K&R C のみ。-Xs オプションが指定されている場合、cpp を呼び出したときのマクロ __STDC__ の値は未定義になります。

t (移行)

ISO C と K&R C の互換性拡張機能。ISO C によるセマンティクスの変更要求はありません。-Xt オプションが指定されている場合、cpp を呼び出したときの定義済みマクロ __STDC__ の値はゼロになります。

-X オプションは、D コンパイラがどのようにして C プリプロセッサを呼び出すかという点にのみ影響を及ぼします。このため、-Xa オプションと -Xt オプションは、D から見ると等価です。どちらのオプションを指定しても、C のビルド環境の設定を簡単に再利用できます。

-X のモードとは関係なく、すべてのモードで次の C プリプロセッサ定義が追加指定され、有効になります。

• __sun

• __unix

• __SVR4

• __sparc (SPARC® システムのみ)

• __sparcv9 (SPARC® システムでの 64 ビットプログラムのコンパイル時のみ)

• __i386 (x86 システムでの 32 ビットプログラムのコンパイル時のみ)

• __amd64 (x86 システムでの 64 ビットプログラムのコンパイル時のみ)

• __'uname -s' _'uname -r'。__SunOS_5_10 のように、uname の出力の小数点を下線 (_) で置き換える

• __SUNW_D=1

• __SUNW_D_VERSION=0xMMmmmuuu (MM はメジャーリリース番号を表す 16 進数、mmm はマイナーリリース番号を表す 16 進数、uuu はマイクロリリース番号を表す 16 進数。DTrace のバージョン管理機能の詳細については、第 41 章バージョン管理を参照)

-Z

一致するプローブがないプローブ記述を許可します。-Z オプションを指定しなければ、D プログラムファイル内 (-s オプション) やコマンド行 (-P、-m、-f、-n、-i のいずれかのオプション) で指定されたプローブ記述に、一致する既知のプローブがひとつもない場合、dtrace はエラーを出して終了します。

オペランド

s オプションで指定された任意の D プログラム、またはコマンド行で指定された任意の D プログラムで使用可能なマクロ変数のセット ($1、$2 など) を定義するときは、-dtrace のコマンド行に 0 個以上の引数を追加できます。マクロ変数の詳しい使用法については、第 15 章スクリプトの作成で説明します。

終了状態

dtrace ユーティリティは、以下の終了値を返します。

0

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

1

致命的なエラーが発生しました。D プログラム要求の場合、終了値 1 は、プログラムのコンパイルに失敗したか、指定された要求に応じられなかったことを表します。

2

指定されたコマンド行オプションまたは引数が無効です。