# マニュアルページ 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 sam-
                       ple 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)、libcollec-
         tor(3)、およびマニュアル
         『プログラムのパフォーマンス解析』