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 に指定した値をプロファイルタイマー間隔として設定します。value には、整数または浮動小数点数を指定し、接尾辞「u」を使用してマイクロ秒、接尾辞「m」を使用してミリ秒を指定することができます。接尾辞を省略すると、ミリ秒を指定したと見なされます。

    value には、「hi」、「lo」、「on」という文字列を指定することもできます。hi (high の略) を指定すると 1 ミリ秒間隔で、lo (low の略) を指定すると 100 ミリ秒間隔で、on を指定すると 10 ミリ秒間隔でプロファイルが行われます。デフォルト値は 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 つのカウンタはそれぞれ異なるイベントレジスタを使用する必要があります。実験が行われている場合は、警告が出力され、コマンドは無視されます。

collector synctrace { on | off }
    sync トレースデータの収集を有効または無効にします。デフォルトは off です。実験が行われている場合は、警告が出力され、コマンドは無視されます。

collector synctrace threshold value
    同期遅延トレースのしきい値を、指定された <value> に従って設定します。<value> には、以下の値のいずれかを指定することができます。

    値   意味

    calibrate または 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 を指定すると、ターゲットプロセスが停止されるたびに標本を採取します。off に設定すると、標本は採取されません。デフォルトは on です。

collector store directory <name>
    コレクタのディレクトリを <name> に設定します。実験が行われている場合は、警告が出力され、コマンドは無視されます。

collector store experiment <name>
    出力する実験ファイル名を <name> に設定します。実験が行われている場合は、警告が出力され、コマンドは無視されます。名前が指定されていない場合は、デフォルト名が使用されます。デフォルト名については、collect(1) のマニュアルページを参照してください。

collector store group <name>
    実験グループ名を <name> に設定します。実験が行われている場合は、警告が出力され、コマンドは無視されます。

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)、およびマニュアル
『プログラムのパフォーマンス解析』