# マニュアルページ 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
              使用可能なカウンタの名前のリストを、通常間隔、高分解 能
              間隔、および低分解能間隔を表す 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> に設定します。実験
                   が行われている場合は、警告が出力され、コマンドは無
                   視されます。名前が指定されていない場合は、デフォル
                   ト 名 が使用されます。デフォルト名については、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 を使用するアプリケー
         ションのデータを収集するには、実行可能ファイルを起動する前に
         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)、libcollec-
         tor(3)、およびマニュアル 『プログラムのパフォーマンス解析』