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 が指定された場合は、警告を出してコマンドを無視します。

    プロセスが実行中で、収集されている実験がある状態で disable コマンドが指定された場合は、 実験を終了します。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
    使用可能なカウンタの名前のリストを、通常間隔、高分解能間隔、および低分解能間隔を表す 3 つの数字設定とともに返します。

collector hwprofile counter <name> <value> [<name2> <value2>]
    <name> で指定されるイベントに対して、<value> で指定されるオーバーフロー間隔でハードウェアカウンタのプロファイルを設定します。 <value> には、以下の値のいずれかを指定することができます。

    値   意味

    on  デフォルトのオーバーフロー値を使用します

    hi[gh]
        高分解能オーバーフロー値を使用します。 また、互換性を維持するため、高分解能を表す値 h も サポートしています。

    lo[w]
        低分解能オーバーフロー値を使用します

    n   n (正の値を指定する必要があります) をオーバーフロー値として使用します

    デフォルトでは、name の値として「cycles」が指定され、標準のプロファイル間隔が設定されます。 2 番目のイベントとオーバーフロー間隔が指定されると、デュアルカウンタプロファイルが実行されます。この場合、2 つのカウンタはそれぞれ異なるイベントレジスタを使用する必要があります。 実験が行われている場合は、警告が出力され、コマンドは無視されます。

    実験には、ハードウェアカウンタプロファイルと クロックに基づくプロファイルの両方を指定できます。 ハードウェアカウンタプロファイルを指定し、クロックに基づくプロファイルを 明示的に指定しなかった場合は、クロックに基づくプロファイルはオフになります。

    ロードやストアを参照するカウンタのために、 カウンタ名が + (プラス) で始まっている場合は、 コレクタは、オーバーフローを引き起こす命令の真の PC を決定しようと 試み、同時に仮想アドレスが参照されます。

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 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> に設定します。 実験が行われている場合は、警告が出力され、コマンドは無視されます。 名前が指定されていない場合は、デフォルト名が使用されます。 デフォルト名については、collect(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 を使用する アプリケーションのデータを収集するには、 実行可能ファイルを起動する前に libcollector.so ライブラリを事前読み込みしておきます。 そうすることによって、ルーチンそのものではなく、 実際のルーチンに対するコレクタのラッパーが参照される ようになります。 ライブラリを事前読み込みするには、環境変数 LD_PRELOAD に値 libcollector.so、環境変数 LD_LIBRARY_PATH に 値 /opt/SUNWspro/lib を設定します。 SPARC[tm] V9 の 64 ビットアーキテクチャを使用する場合は、 さらに環境変数 LD_LIBRARY_PATH_64 に値 /opt/SUNWspro/lib/v9 を設定します。 パフォーマンスツールが /opt/SUNWspro/lib にインストールされていない場合は、システム管理者に正しいパスを問い合わせてください。 クロックに基づくデータまたはハードウェアカウンタのオーバーフローデータのみを収集する場合には、コレクタライブラリを事前ロードする必要はありませんが、コレクタライブラリを事前ロードすると、データ収集がさまざまな問題から保護されます。

データ収集実行後は LD_PRELOAD 設定を取り消してください。このままにしておくと、同一のシェルから起動される他のすべてのプログラムに LD_PRELOAD 設定が影響を与えてしまいます。

実行可能ファイルの起動後、その 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)、libcollector(3)、およびマニュアル 『プログラムのパフォーマンス解析』