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