マニュアルページ 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)、およびマニュアル