マニュアルページ collector.1
名前
collector - パフォーマンスデータ収集に使用する dbx のサブ コ
マンド
形式
dbx
機能説明
collector (コレクタ) とは、dbx 内の デー タ 収 集 機 能 と、
libcollector.so を使用した実行時のデータ収集機能のサポートを
表します。
dbx collector は、プログラミング言語 Java(TM) で記述されたア
プリケーションでは使用できません。dbx collector は JVM (Java
Virtual Machine) のデータを収集できますが、dbx から Java 固
有 の 機 能 を 使 用 することはできません (JVM (Java Virtual
Machine) は、Java(TM) プラットフォーム用の仮想マシンです)。
収集されるデータについては collect(1) のマニュアルページを参
照 してください。collect コマンドは dbx を使用せずにデータを
収集できます。
dbx コマンド
パフォーマンスデータ収集をサポートするために dbx が受け付 け
るコマンドは、次のとおりです。
collector { enable | disable }
データ収集を有効または無効にします。
アクティブなプロセスがない場合に、プロセスが起動した と
き 実験を収集するかどうかを制御します。モードが disable
の場合は、パフォーマンスデータを収集しません。enable の
場合は、以降のすべての実行でデータを収集します。
プロセスが実行中で、収集されている実験が な い 状 態 で
enable コマンドが指定された場合は、実行中のプロセスに対
する実験を開始します。disable が指定されたが、収集中 の
実 験 が ない場合は、警告が表示されコマンドは無視されま
す。
プロセスが実行中で、収集されている実験がある状態で dis-
able コ マ ン ドが指定された場合は、実験を終了します。
enable が指定された場合は、警告を出してコマンドを無視し
ます。
実験が終了され、プロセスが実行されたままの状態で enable
コマンドが指定された場合、新しい実験を開始します。
collector pause
実験中のデータの収集を一時的に中止します。データの記 録
が すでに一時停止されている場合は、警告なしでコマンドを
無視します。実験が動作中でない場合は、警告を出してコ マ
ンドを無視します。
collector resume
実験中のデータの収集を再開します。データの記録がすで に
一 時停止されている場合は、警告なしでコマンドを無視しま
す。実験が動作中でない場合は、警告を出してコマンドを 無
視します。
collector profile { on | off }
クロックに基づくプロファイルデータの収集を有効または 無
効 にします。実験が行われている場合は、警告が出力され、
コマンドは無視されます。デフォルトでは有効になってい ま
す。
collector profile timer value
value に指定した値をプロファイルタイマー間隔として設 定
します。値は、マイクロ秒単位の値の場合は接頭辞 u 、ミリ
秒単位の値の場合は接頭辞 m が付けられた、整数か浮動小数
点 数です。接尾辞を省略すると、ミリ秒を指定したと見なさ
れます。デフォルトの間隔は 10 ミリ秒です。
value には、「hi」、「lo」、「on」という文字列を指定 す
る こともできます。hi (high の略) を指定すると 1 ミリ秒
間隔で、lo (low の略) を指定すると 100 ミリ秒間隔で、on
を 指定すると 10 ミリ秒間隔でプロファイルが行われます。
これらの間隔値は近似値です。
プロファイル間隔の下限値よりも小さな値を指定すると、 下
限 値がプロファイル間隔として設定されます。プロファイル
間隔の分解能の倍数でない値を指定すると、切り捨てが行 わ
れ、 もっとも近い倍数値に設定されます。プロファイル間隔
の上限値を超える値を指定すると、エラーが報告されま す。
負の値や 0 (ゼロ ) を指定した場合も、エラーが報告されま
す。
実験が行われている場合は、警告が出力され、コマンドは 無
視されます。
collector hwprofile { on | off }
ハードウェアカウンタのオーバーフロープロファイルを有 効
ま たは無効にします。ハードウェアまたはオペレーティング
システムが、ハードウェアカウンタのオーバーフ ロー プ ロ
ファ イルをサポートしていないシステムで、このプロファイ
リングを有効にしようとすると、エラーが返されます。実 験
が 行われている場合は、警告が出力されコマンドは無視され
ます。デフォルトでは、無効になっています。
collector hwprofile list
実験のデフォルト設定を含めて簡単な使用法を出力しま す。
プ ロセッサがハードウェアカウンタプロファイルをサポート
している場合は、ハードウェアカウンタに関する情報を含 む
2 つ の リ ス トが出力されます。1 つ目のリストは「既知
(well known)」のハードウェアカウンタ、2 つ目のリスト は
raw ハードウェアカウンタの情報です。
たとえば Sun OS SPARC 系システムで collector hwprofile
list コマンドを実行すると、次のような出力が生成されま
す。
プロファイリングに使用可能な既知の H/W カウンタ:
cycles[/{0|1}],9999991 (`CPU サイクル', Cycle_cnt の別名; CPU サイクル )
insts[/{0|1}],9999991 (`命令の実行', Instr_cnt の別名; イベント )
icm[/1],100003 (`I$ 失敗', IC_miss の別名; イベント )
...
プロファイリングに使用可能な Raw H/W カウンタ:
Cycle_cnt[/{0|1}],1000003 (CPU サイクル)
Instr_cnt[/{0|1}],1000003 (イベント)
Dispatch0_IC_miss[/0],1000003 (CPU サイクル)
...
collector hwprofile counter ctr_def...[,ctr_n_def]
ハードウェアカウンタオーバーフローのプロファイルを収 集
し ま す。 カ ウンタの定義数、 (ctr_def から ctr_n_def)
は、プロセッサによって異なります。たとえ ば UltraSPARC
III システムの場合は、カウンタを 2つまでプログラミング
できます。ハイパースレッディング機能を持つ Intel Pen-
tium 4 の場合は、最高 18 個のカウンタを使用できます。
ターゲットシステムでのプロファイリングに指定できる最 大
ハー ドウェアカウンタ定義数と使用可能なハードウェアカウ
ンタの全一覧は、引数なしで collect コマンドを実行するこ
と によって得ることができます。Lunux システムの場合、こ
のオプションは使用できません。
各カウンタの定義は、ハードウェアカウンタの属性 が プ ロ
セッ サでサポートされているかどうかに従って次の形式のい
ずれかを取ります。
1. [+]ctr[/reg#],interval
[+]ctr[/reg#] interval
使用例:
collector hwprofile counter cycles,on,insts
collector hwprofile counter cycles on insts
注:互換性の関係上、これまで通り、空白文字 1つで ハー
ドウェアカウンタを区切ることができます。
2. [+]ctr[~attr=val]...[~attrN=valN][/reg#],interval
使用例:
collector hwprofile counter FP_dispatched_fpu_ops~umask=0x3/2,10007
浮動小数点の加算および乗算演算の追跡を有効にします。(有
効 な属性値の詳細は、プロセッサのマニュアルを参照してく
ださい。) 値「/2」は、ハードウェアの 2 つ目のレジスタを
使 用して命令を実行するようにする指定です。CPU サイクル
のプロファイルは、10007 個のイベントごとに行われます。
カウンタ定義オプションの意味は、次のとおりです。
値 意味
+ メモリー関係のカウンタに適用可能なオプショ ン
のパラメータ。この場合、 collect は、オーバー
フローを発生させた命令を検出し、メモリー参 照
の 仮想および物理アドレスを検出する際にバック
トラックを行います。バックトラックは、コマ ン
ド 行 引数を付けずに collect を実行することに
よって得られるカウンタリストに表示されるよ う
な ロード、ストア、ロード-ストア タイプのカ
ウンタでのみ機能します。
ctr プロセッサ固有のカウンタ名。カウンタ名の一 覧
は、コマンド行引数を付けずに collect コマンド
を実行することによって得ることができます。
attr=val 一部プロセッサでは、ハードウェアに属 性 オ プ
ショ ンを関連付けることができます。プロセッサ
が属性オプションをサポートしている場合、コ マ
ンド行引数を付けずに collect を実行すると、上
記の 2 つ目の形式のカウント定義、 ctr_defの指
定 になり、 attr に使用する属性名の一覧が提供
されます。値 val は 10 進または 16 進表記のど
ちらでもかまいません。16 進表記は、C プログラ
ムの形式、すなわち、数値の前にゼロと小文字 の
x (0xhex_number) の形式にします。
reg# カウンタに使用するハードウェアレジスタ。指 定
されなかった場合、 collect は最初に使用可能な
レジスタにカウンタを書き込もうとします。こ の
た め、レジスタの衝突のために以降のカウンタを
書き込めないことがあります。複数のカウンタ を
指 定する場合は、それぞれに異なるレジスタを使
用する必要があります。使用可能なレジスタ番 号
の一覧は、コマンド行引数を付けずに collect コ
マンドを実行することによって得ることができ ま
す。
interval
カウンタオーバーフロー値を定義することに よっ
て 設定される標本周波数。有効な値は次のとおり
です。
値 意味
on デフォルトのレートを選択します。 こ
れは、コマンド行引数を付けずに col-
lect コマンドを実行することによって
確 認できます。raw カウンタのデフォ
ルト値はどれも同じで、特定のカウ ン
タ に最適な値ではない可能性があるこ
とに注意してください。
hi onの約10分の1の間隔に設定します。
lo onの約10倍長い間隔に設定します。
value 特定の値を間隔に設定します。10 進ま
たは 16 進表記で指定します。
実験には、ハードウェアカウンタプロファイルとクロック に
基 づくプロファイルの両方を指定できます。ハードウェアカ
ウンタプロファイルを指定し、クロックに基づくプロファ イ
ル を明示的に指定しなかった場合は、クロックに基づくプロ
ファイルはオフになります。
collector synctrace { on | off }
sync トレースデータの収集を有効または無効 に し ま
す。 デフォルトは off です。実験が行われている場合
は、警告が出力され、コマンドは無視されます。
collector synctrace threshold value
同期遅延トレースのしきい値を、指定され た <value>
に従って設定します。<value> には、次の値のいずれか
を指定することができます。
値 意味
calibrate or on
実行時に決定された測定済みのしきい値を使
用します
off 同期遅延トレースをオフにします
n しきい値として n マイクロ秒を使 用 し ま
す。 0 (ゼロ) を指定すると、すべてのイベ
ントをトレースすることができます
デフォルトの設定は、calibrate です。実験が行われて
い る 場合は、警告が出力され、コマンドは無視されま
す。
collector mpitrace { on | off }
MPI トレースデータの収集を有効または無効にします。
デ フォルトは off です。実験が行われている場合、警
告が出力され、コマンドは無視されます。
collector heaptrace { on | off }
ヒープトレースデータの収集を有効または無効に し ま
す。 デ フォ ルトは off です。実験が行われている場
合、警告が出力され、コマンドは無視されます。
collector tha { on | all | <option> | off }
スレッドアナライザデータの収集を制御します。デフォ
ル トは off です。実験がアクティブな場合は、警告が
表示されコマンドは無視されます。ターゲットの実行可
能ファイルには、データ競合検出用の計測機構が必要で
す。詳細は、tha(1) のマニュアルページを参照して く
ださい。
<option> は、スレッドアナライザのデータオプショ ン
をコンマで区切ったリストです。collect() のマニュア
ルページのスレッドアナライザのオプション一覧を参照
してください。
collector archive { on | off | copy }
実験の保管のモードを設定します。デフォル ト は on
で、標準の保管が行われます。off を指定すると、保管
は行われません。copy を指定すると、使用されるす べ
てのロードオブジェクトが実験にコピーされます。別の
マシンに実験を移動するか、別のマシンから実験を読み
取るユーザーは、すべてのロードオブジェクトのコピー
を有効にすることを推奨します。実験が行われている場
合は、警告が出力され、コマンドは無視されます。
collector limit value
記録されるプロファイルのデータ量を <value> メガ バ
イトに制限します。この制限は、すべてのプロファイル
データとトレースデータの合計に適用されますが、標本
採取ポイントには適用されません。この制限は近似値に
すぎず、超過する可能性があります。この制限に達する
と、それ以上プロファイルやトレースデータは記録され
ませんが、ターゲットプロセスが終了するまで実験は開
いたままになり、標本が記録されます。実験が行われて
いる場合、警告が出力され、コマンドは無視されます。
記録されるデータ量のデフォルトの制限値は、2000M バ
イトです。制限を解除するには、value を "none" また
は "unlimited" に設定します。
collector status
すべての開かれている実験ファイルの状態を報告 し ま
す。
collector show
すべてのコレクタ制御変数の現在の設定を表示します。
collector sample { periodic | manual }
標本採取モードを定期的に、または手動で設定します。
periodic を指定すると、標本は現在の標本採取頻度で
記録されます。manual が指定された場合、定期的に 標
本を収集します。collector sample record を使用する
と、どのモードが指定されているかに関わらず、標本を
手動で記録できます。実験が行われている場合は、警告
が出力され、コマンドは無視されます。
collector sample record [<name>]
任意のラベル <name> で標本を記録します。実験が行わ
れていない場合、警告が出力され、コマンドは無視され
ます。
collector sample period <value>
標本採取頻度を、指定の <value> に秒単位で設定し ま
す。実験が行われている場合は、警告が出力され、コマ
ンドは無視されます。
collector dbxsample { on | off }
dbx がターゲットプロセスを停止するときに、標本の採
取を制御します。 on の場合は、dbx がターゲットプロ
セスを停止するたびに標本を 1 つ収集します。 off の
場合は標本を収集しません。デフォルトは on です。
collector store directory <name>
コレクタのディレクトリを <name> に設定します。実験
が行われている場合は、警告が出力され、コマンドは無
視されます。
collector store experiment <name>
出力する実験ファイル名を <name> に設定します。実験
が行われている場合は、警告が出力され、コマンドは無
視されます。名前が指定されていない場合は、デフォル
ト 名 が使用されます。デフォルト名については、col-
lect(1) のマニュアルページを参照してください。
collector store group <name>
実験グループ名を <name> に設定します。実験が行われ
ている場合は、警告が出力され、コマンドは無視されま
す。
collector version
データの収集に使用される libcollector.so の バー
ジョンを報告します。
help collector
使用可能なさまざまなコレクタコマンドに関する情報を
出力します。
廃止された dbx コマンド
dbx で使用できたいくつかのコマンドが使用できなくなりました。
以下がそのコマンドです。
collector enable_once
警告が出力され、無視されます。このコマンドは、一度だ け
データ収集することができました。
collector close
実験が行われている場合、collector disable として取り 扱
わ れ ま す。実験が行われていない場合は、警告が出力され
て、無視されます。
collector quit
実験が行われている場合は、collector disable として取 り
扱 われます。実験が行われていない場合は、警告が出力され
て、無視されます。
collector address_space { on | off }
アドレス空間データはサポートされなくなりました。警告 が
出力され、コマンドは無視されます。
collector store filename <name>
互換のために collector store experiment を受け 付 け ま
す。出力実験名を <name> に設定します。
派生プロセスのフォロー
パフォーマンスデータを収集するプロセスが派生プロセスを作成す
る場合、コレクタは親プロセスでデータの収集を続行しますが、次
の例外があります。プロセスが exec の派生関数を呼び出す場合、
exec が成功すると実験は異常終了し、exec が失敗すると実験は続
行されます。いずれの場合も、実験はパフォーマンス解析ツールに
よって読み取ることができます。
派生プロセスに関するデータを記録するには、dbx を新規に作成さ
れ たプロセスに接続してから、collector enable を使用して派生
プロセスで実験を開始する必要があります。すべての派生プロセス
に 関するデータを自動的に収集するには、collect(1) コマンドを
使用します。
プロセスへの接続
dbx をプロセスに接続し、コレクタコマンドを使用して、そこから
パフォーマンスデータを収集することができます。
シグナルハンドラのインストールを行う、または libcpc.so を 使
用するアプリケーションに対する接続によるデータ収集は正しく機
能しない場合があります。これは、本来のルーチンそのものではな
く て、ルーチンに近い部分で collector のラッパーが参照され呼
び出されるいう、この機能のしくみによって生じます。同様に、ト
レースデータ (同期トレース、ヒープトレース、MPI トレース) の
収集や派生プロセスの追尾も機能しないことがあります。時計およ
びハードウェアカウンタプロファイル実験は、dbx によって接続さ
れたプロセスには機能します。こうした問題のすべてに対する回避
策としては、collect に -y sig フラグを使用してプロセスを開始
してから、指定のシグナル sig をターゲットに送信する こ と に
よってデータ収集を有効にする方法があります。
実行可能ファイルの起動後、その PID を決定し、dbx をその PID
に接続してください。この時点で、データ収集を有効にすることが
できます。
データ収集を有効にしないで dbx から実行可能ファイルを起動 し
て し まった場合は、dbx から、いつでもそのプロセスを一時停止
し、データ収集を有効にできます。ただし、この場合も、接続時と
同じ制限を受けます。
関連項目
analyzer(1)、collect(1)、dbx(1)、 er_archive(1)、 er_cp(1)、
er_export(1)、er_mv(1)、er_print(1)、er_rm(1)、 tha(1)、lib-
collector(3)、およびマニュアル 『プログラムのパフォーマン ス
解析』