7 DTrace関数のリファレンス
D関数コールを使用すると、DTraceが提供する各種のサービスを起動できます。
関数は、それらの一般的なユースケースに応じてグループ化でき、複数のグループに分けられるものもあります:
- データ記録関数
-
データ記録関数では、DTraceバッファにデータを記録します。これらは最も一般的な関数であり、デフォルトのDTrace関数はこのカテゴリに属します。デフォルトでは、データ記録関数は主バッファにデータを記録しますが、投機バッファにデータを記録するように指示することもできます。
次に、データ記録関数を示します:-
デフォルト・アクション: デフォルト・アクションは、DTraceがプローブの空の節を検出したときに適用されます。デフォルト・アクションでは、有効なプローブID (EPID)をトレースします。
-
printa: 集積体のフォーマットを表示および制御します -
printf: 文字列のフォーマットを表示および制御します。 -
trace: 式の結果を指定バッファにトレースします。 -
tracemem: 指定したバイト数のデータをメモリー内のアドレスから現在のバッファにコピーします。
-
- 集積関数
-
集積関数は、集積体に格納されているDTraceデータのセットに関して計算された情報を提供します。
次に示す関数は、集積関数です:
-
avg: 指定した式の算術平均を集積体に格納します。 -
count: 増分されたカウント値を集積体に格納します。 -
max: 指定した式のうちの最大値を集積体に格納します。 -
min: 指定した式のうちの最小値を集積体に格納します。 -
sum: 指定した式の合計値を集積体に格納します。 -
stddev: 指定した式の標準偏差を集積体に格納します。 -
quantize: 指定した式の値の二乗度数分布を集積体に格納します。オプションの増分を指定できます。 -
lquantize: 指定した範囲のサイズで、指定した式の値の線形度数分布を集積体に格納します。 -
llquantize: 対数線形度数分布を集積体に格納します。
次に示す関数は集積しない関数ですが、集積体を操作します:
-
clear: 集積体から値をクリアしますが、集積体のキーは保持します。 -
denormalize: 指定した集積体に適用されている正規化を削除します。 -
normalize: 指定した正規化係数で集積値を除算します。 -
printa: 集積体のフォーマットを表示および制御します
-
- 投機関数
-
投機関数では、投機バッファを作成または操作します。投機は、投機バッファに定量をトレースするために使用します。このバッファは、主バッファにコミットすることも、重要な情報が別にあることが判明した時点で破棄することもできます。
次に示す関数は、投機関数です:
-
speculation: 投機トレース・バッファを作成して、そのIDを返します。 -
speculate: これ以降の節の部分については、指定したIDで識別される投機バッファをDTraceが使用するように切り替える特殊な関数。 -
commit: IDで指定された投機バッファを主バッファにコミットします。 -
discard: 指定された投機IDで特定される投機バッファを破棄します。
-
- 文字列操作関数
-
文字列操作関数は、ほとんどのプログラミング言語で標準的なもので、文字列に対して一般的な関数操作を実行するために使用します。多くの関数は、Oracle Linuxのマニュアル・ページのセクション3で説明されているシステム・ライブラリ・コールに類似したものがあります。多くの場合、これらの関数の詳細は、それに対応するマニュアル・ページを調べることで確認できます。次に例を示します:
man 3 strchr次のいくつかの関数には、節の間にのみ存続する一時バッファが必要になります。このようなバッファには、事前に割り当てられているスクラッチ・メモリーが使用されます。
次に示す文字列操作関数を使用できます:
-
index: 文字列内で最初に現れる部分文字列を検索します。 -
rindex: 文字列内で最後に現れる特定の部分文字列を検索します。 -
lltostr: 符号なし64ビットの整数を文字列に変換します。 -
strchr: 指定した文字が文字列内で最初に一致する位置から始まる部分文字列を返します。 -
strjoin: 指定した2つの文字列を連結して、その結果の文字列を返します。 -
strlen: 文字列の長さをバイト数で返します。 -
strrchr: 指定した文字が文字列内で最後に一致する位置から始まる部分文字列を返します。 -
strstr: 指定した部分文字列が文字列内で最初に現れた位置から始まる部分文字列を返します。 -
strtok: 指定したデリミタを使用して、文字列を一連のトークンに解析します。 -
substr: 指定した索引位置の文字列からの部分文字列を返します。
-
- ファイル・パス操作関数
-
文字列操作関数と同様に、ファイル・パス操作関数はファイル・パスを操作します。また、指定したポインタのパス名を提供できます。これらの関数のいくつかは、Oracle Linuxのマニュアル・ページのセクション3で説明されているシステム・ライブラリ・コールに類似したものがあります。
- 整数変換関数
-
文字列操作関数と同様に、DTraceには、ホストのバイト順序とネットワークのバイト順序の間で整数を変換できる複数の整数変換関数が含まれていますこれらの関数は、Oracle Linuxのマニュアル・ページのセクション3で説明されているシステム・ライブラリ・コールに類似したものがあります。
次に示す整数変換関数を使用できます:
-
htonl: 32ビットのunsigned long integerをホストのバイト・オーダーからネットワークのバイト・オーダーに変換します。 -
htonll: 64ビットのunsigned long integerをホストのバイト・オーダーからネットワークのバイト・オーダーに変換します。 -
htons: 16ビットのunsigned short integerをホストのバイト・オーダーからネットワークのバイト・オーダーに変換します。 -
ntohl: 32ビットのlong integerをネットワークのバイト・オーダーからホストのバイト・オーダーに変換します。 -
ntohll: 64ビットのlong integerをネットワークのバイト・オーダーからホストのバイト・オーダーに変換します。 -
ntohs: 16ビットのshort integerをネットワークのバイト・オーダーからホストのバイト・オーダーに変換します。
-
- コピー関数
-
コピー関数は、メモリー・アドレスとDTraceバッファの間で情報をコピーする操作に関連する関数です。これらの関数には、実行中プロセスのメモリー内のデータを変更するものがあります。それらは、プロセス破壊的関数とみなされることもあります。DTraceでは、破壊的関数は明示的に有効にする必要があります。
-
alloca: メモリーを割り当てて、ポインタを返します。 -
bcopy: 指定したスクラッチ・メモリー外部のコピー元アドレスからスクラッチ・メモリー内部のコピー先アドレスに、バイト数で指定サイズをコピーします。 -
copyin: 指定したサイズをユーザー・アドレスからDTraceバッファにコピーして、バッファのアドレスを返します。 -
copyinstr: 指定したユーザー・アドレスからDTraceバッファにNULL終端のC文字列をコピーして、バッファのアドレスを返します。 -
copyinto: 指定したユーザー・アドレスからDTraceスクラッチ・バッファにバイト単位で指定したサイズをコピーして、バッファ・アドレスを返します。 -
copyout: 指定したDTraceバッファから指定したユーザー空間アドレスに、指定したサイズをコピーします。 -
copyoutstr: 指定した文字列を指定したユーザー空間アドレスにコピーします。
-
- ロック分析関数
-
ロック分析関数は、相互排他ロックとファイル・ロックをチェックするために使用されます。
次に示すロック解析関数を使用できます:
-
mutex_owned: 指定したカーネル相互排他ロックをスレッドが保持しているかどうかを確認します。 -
mutex_owner: 指定したカーネル相互排他ロックの現在の所有者にスレッド・ポインタを返します。 -
mutex_type_adaptive: 指定したカーネル相互排他ロックが適応型の場合に、ゼロ以外の値を返します。 -
mutex_type_spin: 指定したカーネル相互排他ロックがスピン相互排他ロックの場合に、ゼロ以外の値を返します。 -
rw_iswriter: 指定した読取り/書込みロックを書込み側が保持中または待機中かどうかを確認します。 -
rw_read_held: 指定した読取り/書込みロックを読取り側が保持しているかどうかを確認します。 -
rw_write_held: 指定した読取り/書込みロックを書込み側が保持しているかどうかを確認します。
-
- シンボリック名とスタック分析関数
-
DTraceには、バッファにスタック・トレースを記録する関数や、ユーザー空間またはカーネル空間のアドレスへのポインタのシンボルやモジュール名を出力できる関数が含まれていて、プロセスのデバッグに利用できます。
次に示す関数は、スタックとアドレスに関する情報を返します:
-
stack: バッファにスタック・トレースを記録します。 -
func: 指定したカーネル空間アドレスのシンボルを出力します。symの別名です。 -
mod: 指定したカーネル空間アドレスに対応するモジュール名を出力します。 -
sym: 指定したカーネル空間アドレスのシンボルを出力します。funcの別名です。 -
ustack: ユーザー・スタック・トレースを指定バッファに記録します。 -
uaddr: 指定したアドレスのシンボルを出力します。 -
ufunc: 指定したユーザー空間アドレスのシンボルを出力します。usymの別名です。 -
umod: 指定したユーザー空間アドレスに対応するモジュール名を出力します。 -
usym: 指定したアドレスのシンボルを出力します。ufuncの別名です。
-
- 一般的なシステム関数
-
DTraceには、システムから情報を取得するための関数や、各種のユースケースに向けて一般化された関数が含まれています。このカテゴリの関数は次のとおりです:
- 破壊的関数
-
DTraceは、安全にコードを実行するように設計されています。破壊的関数を使用する場合は、該当する関数を明示的に有効にすることで、DTraceによって実行されるアクションからシステムを保護する制約を緩和する必要があります。
破壊的関数は、なんらかの定義された方法でプロセスまたはシステム全体を変更できます。これには、現在のプロセスの停止、現在のプロセスでの特定の信号の発信、別のシステム・プロセスの生成などの関数が含まれます。こうした関数は、破壊的関数を使用する機能が明示的に有効になっている場合にのみ使用できます。dtraceユーティリティを使用している場合は、
-wコマンドライン・オプションを使用すると破壊的関数を有効にできます。明示的な有効化なしに破壊的関数を使用しようとすると、dtraceは次のようなメッセージで失敗します:
dtrace: failed to enable 'syscall': destructive functions not allowedこのような関数は、システム上のすべてのプロセスに影響を及ぼすだけでなく、影響を受けるシステムのネットワーク・サービスによっては暗黙的または明示的に別のシステムにも影響を及ぼすため、慎重に使用する必要があります。
- 特殊関数
-
DTraceには、トレースを完全に終了するものや、DTraceの実行時オプションを変更するものなど、DTraceの動作を変更する関数も含まれています。