4 DTraceの実行時およびコンパイル時のオプション・リファレンス

DTraceは、実行時構成に妥当なデフォルト値と柔軟なデフォルト・ポリシーを使用します。DTraceコンパイラまたは実行時オプションの形式でメカニズムを調整すると、dtraceユーティリティのデフォルト動作を変更できます。dtraceユーティリティと各種コマンドライン・オプションの詳細は、dtrace(8)マニュアル・ページを参照してください。

dtraceユーティリティの実行時に指定できるオプションは、次の3つのタイプに分類できます:

• コンパイル時オプション: コンパイル・プロセスに影響しますが、実行時の動作にも影響する可能性があります。

• 実行時オプション: DTraceの実行時の動作に影響しますが、多くの場合、コンパイル時に設定します。

• 動的実行時オプション: DTraceの実行時の動作に影響しますが、トレース中にsetopt関数を使用して変更できます。

DTraceコンパイル時および実行時のオプションの設定

DTraceは、実行時オプションまたはコンパイラ・オプションの選択を設定または有効化することで調整できます。オプションを設定するには、dtraceコマンドの実行時に-xコマンドライン・スイッチを使用するか、Dプログラムでpragma行を指定します。値を受け取るオプションの場合は、オプション名の後ろに等号(=)とオプションの値を続けます。

値の接尾辞

サイズや時間を示す値には、次のオプションの接尾辞を使用します:

• kまたはK: キロバイト
• mまたはM: メガバイト
• gまたはG: ギガバイト
• tまたはT: テラバイト
• nsまたはnsec: ナノ秒
• usまたはusec: マイクロ秒
• msまたはmsec: ミリ秒
• sまたはsec: 秒
• mまたはmin: 分
• hまたはhour: 時間
• dまたはday: 日数
• hz: 毎秒数

例4-1 DTraceユーティリティを使用したオプションの有効化

dtraceコマンドは、-xスイッチを使用すると、コマンドラインでオプション設定を受け入れます。次に例を示します:

sudo dtrace -x nspec=4 -x bufsize=2g \
-x switchrate=10hz -x aggrate=100us -x bufresize=manual

例4-2 Dプログラムでオプションを有効にするDTraceプラグマ行

Dプログラムでオプションを設定するときには、#pragma D、文字列optionおよびオプション名と値の順に指定します。次に、有効なオプション設定の例を示します。

#pragma D option nspec=4

#pragma D option bufsize=2g

#pragma D option switchrate=10hz

#pragma D option aggrate=100us

#pragma D option bufresize=manual

コンパイル時オプション

コンパイル時オプションは、DTraceプログラムをカーネル空間にロードされるeBPFコードにコンパイルする方法を制御できます。

aggpercpu

コンパイル時オプション。コンパイラがCPUごとに集積を実行するように強制します。

amin=<string>

コンパイル時オプション。安定性属性の最小値を設定します。

argref

コンパイル時オプション。すべてのマクロ引数を使用する要件を無効にします。

core

コンパイル時オプション。dtraceによるコア・ダンプを有効にします。

cpp

コンパイル時オプション。cppが入力ファイルを前処理できるようにします。

cppargs

コンパイル時オプション。cppに渡す追加の引数を指定します(-Cを使用する場合)。

cpphdrs

コンパイル時オプション。cppに-Hオプションを指定して、使用される各ヘッダー・ファイルの名前を出力します。

cpppath=<string>

コンパイル時オプション。cppのパス名を指定します。

ctfpath

コンパイル時オプション。vmlinux.ctfaのパスを指定できます。

ctypes=<string>

コンパイル時オプション。Dコンパイル実行の最後にプログラムで使用される、すべてのC型の圧縮型フォーマット(CTF)定義を指定します。

debug

コンパイル時オプション。DTraceデバッグ・モードを有効にします。このオプションは、環境変数DTRACE_DEBUGを設定するのと同じです。

debugassert

コンパイル時オプション。特定のデバッグモード[UNTESTED]を有効にできます。

defaultargs

コンパイル時オプション。未指定のマクロ引数への参照を許可します。未指定の引数の値として0を使用します。

define=<string>

コンパイル時オプション。name[=value]の形式でマクロ名とオプション値を指定します。このオプションは、dtrace -Dを実行するのと同じです。

disasm

コンパイル時オプション。リクエストされた逆アセンブラのリストを指定します(-Sを使用する場合)。

droptags

コンパイル時オプション。ドロップ・タグの使用を指定します。

dtypes=<string>

コンパイル時オプション。Dコンパイル実行の最後にプログラムで使用される、すべてのD型のCTF定義を指定します。

empty

コンパイル時オプション。空のDソース・ファイルのコンパイルを許可します。

errtags

コンパイル時オプション。デフォルトのエラー・メッセージの接頭辞としてエラー・タグを付けます。

evaltime=[exec|main|postinit|preinit]

コンパイル時オプション。DTraceが新しいプロセスのトレースを開始するタイミングを制御します。動的にリンクされたバイナリについては、次のようにトレースが開始されます。

• exec: exec()の後。
• preinit: バイナリをロードするための動的リンカーの初期化後。
• postinit: コンストラクタ実行の後。デフォルト値。
• main: main()の開始前。postinitと同じ。

静的にリンクされたバイナリについては、preinitはexecと同等です。

削除された静的にリンクされたバイナリについては、postinitおよびmainはpreinitと同等です。

incdir=<string>

コンパイル時オプション。#includeディレクトリをプリプロセッサ検索パスに追加します。このオプションは、dtrace -Iを実行するのと同じです。

iregs=<scalar>

コンパイル時オプション。DTrace中間フォーマット(DIF)の整数レジスタ・セットのサイズを設定します。デフォルト値は8です。

kdefs

コンパイル時オプション。未解決のカーネル・シンボルを回避します。

knodefs

コンパイル時オプション。未解決のカーネル・シンボルを許可します。

late=[dynamic|static]

コンパイル時オプション。動的トランスレータへの参照を許可するかどうかを指定します。

• dynamic: 動的トランスレータへの参照を許可します。
• static: トランスレータを静的に定義する必要があります。

lazyload=<true|false>

コンパイル時オプション。アクティブなロードではなく、DTraceオブジェクト・フォーマット(DOF)のレイジー・ロードを指定します。

ldpath=<string>

コンパイル時オプション。動的リンカー・ローダー(ld)のパスを指定します。

libdir=<string>

コンパイル時オプション。ライブラリ・ディレクトリをライブラリ検索パスに追加します。

linkmode=[dynamic|kernel|static]

コンパイル時オプション。外部シンボル参照の処理時にアセンブラにより使用されるシンボル・リンク・モードを指定します。

• dynamic: すべてのシンボルは動的として扱われます。
• kernel: カーネル・シンボルは静的、ユーザー・シンボルは動的として扱われます。
• static: すべてのシンボルは静的として扱われます。

linknommap

コンパイル時オプション。USDTオブジェクトのリンク中に、MMAPベースのlibelfサポートの使用を無効にします。

linktype=[dof|elf]

出力ファイル・タイプを指定するコンパイル時オプション:

• dof: スタンドアロンDOFファイルを生成します。
• elf: DOFを含むELFファイルを生成します。

modpath=<string>

コンパイル時オプション。モジュール・パスを指定します。デフォルト・パスは/lib/modules/ versionです。

nolibs

コンパイル時オプション。Dシステム・ライブラリの処理を回避します。

pgmax=<scalar>

コンパイル時オプション。DTraceがトレース用に捕捉できるスレッド数の制限を設定します。デフォルト値は8です。

preallocate=<scalar>

コンパイル時オプション。事前割当てするメモリーの量を設定します。

procfspath=<string>

コンパイル時オプション。procfsファイル・システムへのパスを設定します。デフォルト・パスは/procです。

pspec

コンパイル時オプション。あいまいな指定子をプローブ名として解釈できるようにします。

stdc=[a|c|s|t]

コンパイル時オプション。-Cオプションを使用してcppを呼び出すときに、プリプロセッサのISO C準拠設定を指定します。

a、cおよびt設定は、-std=gnu99オプション(1999 C標準に準拠し、GNU拡張を含む)を含みます。

s設定は-traditional-cppオプション(K&R Cに準拠)を含みます。

strip

コンパイル時オプション。ロード不可能なセクションをプログラムから削除します。

syslibdir=<string>

コンパイル時オプション。システム・ライブラリのパス名を設定します。

tree=<scalar>

コンパイル時オプション。DTraceツリー・ダンプ・ビットマップの値を設定します。

tregs=<scalar>

コンパイル時オプション。DIFタプル・レジスタ・セットのサイズを設定します。デフォルト値は8です。

udefs

コンパイル時オプション。未解決のユーザー・シンボルを回避します。

undef=<string>

コンパイル時オプション。プリプロセッサを呼び出すときにシンボルの定義を取り消します。このオプションは、dtrace -Uを実行するのと同じです。

unodefs

コンパイル時オプション。未解決のユーザー・シンボルを許可します。

useruid

システム範囲にない最初のUIDを使用する、コンパイル時オプション。

verbose

コンパイル時オプション。コンパイルされた各DIFオブジェクト(DIFO)を表示するDIF冗長モードを有効にします。

version=<string>

コンパイル時オプション。DTraceライブラリの特定のバージョンをリクエストします。

zdefs

コンパイル時オプション。一致するプローブが1つも見つからないプローブ定義を許可します。

実行時オプション

実行時オプションでは、DTraceユーティリティの動作を制御できます。

aggsize=<size>

実行時オプション。集積体のバッファ・サイズを設定します。

bpflog=<size>

実行時オプション。BPF検証ログのレポートを強制します(検証が成功した場合でも)。

bpflogsize

実行時オプション。BPF検証ログの最大サイズを設定します。

bufsize=<size>

実行時オプション。主バッファのサイズを設定します。デフォルトのバッファ・サイズは4MBに設定されています。このオプションは、dtrace -bを実行するのと同じです。

cleanrate=<time>

実行時オプション。クリーニング率を設定します。

cpu=<scalar>

実行時オプション。トレースを特定のCPUに制限します。

destructive

実行時オプション。破壊的関数の実行を許可します。このオプションは、dtrace -wを実行するのと同じです。

dynvarsize=<size>

実行時オプション。動的変数のスペース・サイズを設定します。

lockmem

実行時オプション。ロックされたページの制限を設定します。

maxframes=<scalar>

実行時オプション。カーネルによって報告されるスタック・フレームの最大数を設定します。

noresolve

実行時オプション。ユーザー空間のシンボルの自動解決を無効にします。

nspec=<scalar>

実行時オプション。投機の数を設定します。

pcapsize=<size>

実行時オプション。パケット・データ・キャプチャの最大サイズを設定します。

scratchsize=<size>

実行時オプション。DTraceスクラッチ・メモリーの最大サイズを設定します。DTraceの関数には、使用可能なスクラッチ・メモリーが必要になるものがあります。たとえば、alloca()関数を使用してプログラムでメモリーを割り当てるときには、そのためにスクラッチ・メモリーが使用されます。スクラッチ・メモリーは、節の処理中にのみ有効で、節の処理が終了すると解放されます。十分なスクラッチ・メモリーがないと、DTraceスクリプト内の関数はエラーを返して、節の残りの処理が失敗する可能性があります。デフォルト値は256バイトです。

specsize=<size>

実行時オプション。投機バッファのサイズを設定します。

stackframes=<scalar>

実行時オプション。スタック・フレームの数を設定します。デフォルト値は20です。

statusrate=<time>

実行時オプション。ステータス・チェックのレートを設定します。

strsize=<size>

実行時オプション。文字列のサイズを設定します。デフォルト値は256です。

ustackframes=<scalar>

実行時オプション。ユーザーランド・スタック・フレームの数を設定します。デフォルト値は100です。

動的実行時オプション

動的実行時オプションは、Dプログラム自体に固有であり、プログラムの機能と要件に応じて変更することになります。

aggrate=<time>

動的実行時オプション。集積体読取り間の時間を設定します。

aggsortkey=<true|false>

動的実行時オプション。キー別に集積体をソートします。

aggsortkeypos=<scalar>

動的実行時オプション。ソートする集積体のキーの位置または数値を設定します。

aggsortpos=<scalar>

動的実行時オプション。ソートする集積体の変数の位置または数値を設定します。

aggsortrev=<true|false>

動的実行時オプション。逆順に集積体をソートします。

flowindent

動的実行時オプション。インデントを制御します。

関数の開始位置をインデントし、その前に->を付けます。

関数の終了位置のインデントを解除し、その前に<-を付けます。

システム・コールの開始位置をインデントし、その前に=>を付けます。

システム・コールの終了位置のインデントを解除し、その前に<=を付けます。

このオプションは、dtrace -Fを実行するのと同じです。

quiet

動的実行時オプション。出力を明示的にトレースされたデータに制限します。このオプションは、dtrace -qを実行するのと同じです。

quietresize

動的実行時オプション。バッファ・サイズ変更メッセージを抑制します。

rawbytes

動的実行時オプション。trace出力を16進数で出力します。

stackindent=<scalar>

動的実行時オプション。stackおよびustack出力をインデントするときに使用する、空白文字の数を設定します。デフォルト値は「14」です。

switchrate=<time>

動的実行時オプション。バッファの読取り速度を設定します。データの取りこぼしを防止するために速度を上げることができます。また、bufsizeオプションを使用して主バッファのサイズを増やすことも検討してください。