# マニュアルページ collect.1

## 名前

         collect - プログラムのパフォーマンスデータの収集に使用するコ
         マンド

## 形式

         collect collect-arguments target target-arguments
         collect
         collect -V
         collect -R

## 説明

         collect コマンドはターゲットプロセスを実行して、そのプロセス
         に関するパフォーマンスおよびグローバルデータを記録します。パ
         フォーマンスデータは、プロファイリングまたはトレース技 術 を
         使っ て収集されます。このデータは、GUI プログラム (analyzer)
         かコマンド行プログラム (er_print) を使って表示できます。col-
         lect  コマンドによって実行されるデータ収集ソフトウェアをここ
         ではコレクタと呼びます。

         collect コマンドを 1 回実行して収集されるデータを実験と呼 び
         ます。実験は、ファイルシステムにディレクトリとして表示されま
         す。このディレクトリにはさまざまな種類のファイルが含ま れ ま
         す。

         target は、パフォーマンスデータを収集したい実行可能ファイ ル
         あるいは Java(TM) .jar ファイルまたは Java .class ファイルの
         パス名です (Java プロファイルの詳細については、以下の 「Java
         プ ロ ファ イル」の項を参照してください)。collect コマンドの
         ターゲットとなる実行可能ファイルは、どの最適化レベルでコンパ
         イルされたものでもかまいませんが、動的リンクを使用したもので
         なければなりません。プログラムが静的にリンクされている 場 合
         は、collect コマンドはエラーメッセージを出力します。analyzer
         または er_print を使用して注釈付きソースを表示するには、ター
         ゲットを -g フラグ付きでコンパイルし、ストリップしないでくだ
         さい。

         データ空間のプロファイリングを有効に す る に は、 -xhwcprof
         -xdebugformat=dwarf  -g フラグを付けて、実行可能ファイをコン
         パイルする必要があります。これらのフラグは、C コンパイラでの
         み、 ま た  SPARC 上でのみ有効です。下記の「データ空間のプロ
         ファイリング」参照してください。

         collect コマンドは、次の方法を用いてターゲットを検索します。

         - ターゲット名を持つ、実行可能とマークされたファイルが存在す
           る 場合は、ターゲットマシンで実行可能な ELF 実行可能ファイ
           ルかどうかが確認されます。ファイルが有効な ELF 実 行 可 能
           ファイルでない場合は、collect コマンドは失敗します。

         - ターゲット名のファイルが存在していて、実行可能ファイルでな
           い場合、collect は、Java(TM) jar または class ファイルのど
           ちらであるか確認します。そのいずれかであれば、必要なフラグ
           と と もに java のターゲット名が挿入され、データは JVM(TM)
           マシンに収集されます (「Java 仮想マシン」および「JVM」の語
           は、Java(TM) プラットフォーム用仮想マシンを指します)。

         - ターゲット名を持つファイルが存在しない場合、実行可能ファイ
           ルを探してユーザーのパスが検索されます。実行可能ファイルが
           見つかると、上記の確認が行われます。

         - 現在の名前のファイルが見つからない場合、その名前に文 字 列
           .class  の付加された名前を持つファイルが検索されます。これ
           が見つかると、上記のように該当するフラグとともに  java  の
           ターゲット名が挿入されます。

         - 以上の手順でターゲットが見つからない場合、コマンドは失敗と
           なります。

         注:     Linux システムでは、Java プロファイリングおよび デー
               タ空間プロファイリングは行えません。

## オプション

         引数なしで起動された場合は、実験のデフォルト名とプロファイリ
         ン グ に使用できるハードウェアカウンタ名などの、使用法のメッ
         セージが表示されます。

      データ指定
         -p option
              クロックに基づいたプロファイルデータ収集を行 い ま す。
              option には次の値を指定できます。

              値          意味

              off       クロックに基づくプロファイルは行われません。

              on        デフォルトの約 10 ミリ秒のプロファイル間隔 で
                        クロックに基づくプロファイルが行われます。

              lo[w]     約 100 ミリ秒の低分解能プロファイル間隔 で ク
                        ロックに基づくプロファイルが行われます。

              hi[gh]    約 1 ミリ秒の高分解能プロファイル間隔でクロッ
                        クに基づくプロファイルが行われます。

              n         n のプロファイル間隔でクロックに基づ く プ ロ
                        ファ イルが行われます。n のプロファイル間隔で
                        クロックに基づくプロファイルが行われま す。 n
                        に は、整数または浮動小数点数を指定し、接尾辞
                        u を使用してマイクロ秒、接尾辞 m を使用してミ
                        リ 秒を指定することができます。接尾辞を省略す
                        ると、ミリ秒を指定したと見なされます。

                        プロファイル間隔の下限値よりも小さな値を指 定
                        す ると、下限値がプロファイル間隔として設定さ
                        れます。プロファイル間隔の分解能の倍数でな い
                        値 を指定すると、切り捨てが行われ、もっとも近
                        い倍数値に設定されます。プロファイル間隔の 上
                        限 値を超える値を指定すると、エラーが報告され
                        ます。負の値や 0 (ゼロ) を指定した場合も、 エ
                        ラー が報告されます。引数なしで起動された場合
                        は、時間プロファイル間隔が報告されます。

              -p off 引数が明示的に指定されず、ハードウェアカウンタプ
              ロ ファ イ ルも指定されない場合は、クロックに基づくプロ
              ファイルが行われます。

         -h counter[,value[,counter2[,value2]]]
              ハードウェアカウンタのオーバーフローのプロファイル デー
              タ を収集します。Linux システムでは、このオプションは使
              用できません。

              ハードウェアカウンタのオーバーフローのプロファイル デー
              タ を収集します。counter に指定する名前は、標準のカウン
              タ名でも、cputrack(1) で使用される内部名でもかまいま せ
              ん。標準名と内部名を一覧表示するには、コマンド行に col-
              lect を入力する必要があります。名前が内部名で、末尾がス
              ラッシュ(/) と 1 桁の数字 (0 または 1) である場合は、そ
              の数字によって特定されるイベントレジスタが使用 さ れ ま
              す。 そうでない場合は、その名前のカウンタをサポートする
              任意のイベントレジスタが使用されます。

              オーバーフロー値は、カウンタオーバーフロー に なっ て、
              オー バーフローイベントを記録すのに必要なイベントの発生
              回数です。以下のいずれかの値に設定できます。

              値          意味

              on または NULL 文字列
                        デフォルトのオーバーフロー値が使用されます。

              hi[gh]    高分解能オーバーフロー値が使用されます。高 分
                        解能を表す値 h も、互換性のためにサポートされ
                        ています。

              lo[w]     低分解能オーバーフロー値が使用されます。

              n         n のオーバーフロー値が使用されます。n には 正
                        の値を指定する必要があります。

              任意の 2 番目のカウンタおよび 2 番目のオーバーフロー 値
              を 指定する場合は、最初のカウンタのオーバーフロー値を上
              記のいずれかの値に指定する必要があります。指定された  2
              つ の名前付きカウンタは、異なるイベントレジスタに置かれ
              る必要があります。

              実験には、ハードウェアカウンタプロファイルとクロック に
              基 づくプロファイルを両方指定できます。ハードウェアカウ
              ンタプロファイルが指定され、クロックに基づくプロファ イ
              ル が明示的に指定されない場合、クロックに基づくプロファ
              イルは行われません。

              ロードまたはストアを参照するカウンタの場合、カウンタ の
              名 前 がプラス (+) 記号で始まる場合には、コレクタはオー
              バーフローの原因となった命令の真の PC と参照された仮 想
              ア ドレスを確認します。下記の「データ空間のプロファイリ
              ング」参照してください。

         -s option
              同期トレースデータを収集します。Linux システムでは、 こ
              のオプションは使用できません。

              トレースイベントの最小遅延しきい値は、option を使用して
              設定します。option には次の値を指定できます。

              値          意味

              on        同期遅延トレースが行われ、実行時に決定され る
                        測定されたしきい値が設定されます。

              calibrate on と同じ

              off       同期遅延トレースは行われません。

              n         n マイクロ秒のしきい値で同期遅延トレースが 行
                        わ れます。n がゼロの場合、すべてのイベントが
                        トレースされます。

              all       同期遅延トレースが行われ、すべての同期イベ ン
                        トがトレースされます。

              デフォルトでは、同期遅延トレースは行われません。

              同期イベントは Java モニター用に記録されますが、JVM  マ
              シン内でのネイティブの同期用には記録されません。

         -H option
              ヒープトレースデータを収集します。option には以下の値を
              指定できます。

              値          意味

              on        記憶域割り当て要求がトレースされます。

              off       記憶域割り当て要求のトレースは行われません。

              デフォルトでは、ヒープトレースは行われません。

              ヒープトレースイベントは Java の記憶域割り当て と ネ イ
              ティ ブ呼び出しのために記録されます。 mmap への呼び出し
              は、メモリー割り当てとして扱われます。

              特に Java で記述されたアプリケーションの場合、ヒープ ト
              レー スを行うと非常に大きな実験が生成される可能性がある
              ことに注意してください。このような実験の読み込みとブ ラ
              ウズは非常に時間がかかります。

         -m option
              MPI トレースデータを収集します。Linux システムでは、 こ
              のオプションは使用できません。

              option には以下の値を指定できます。

              値          意味

              on        MPI コールのトレースを行います。

              off       MPI コールのトレースは行われません。

              デフォルトでは、MPI トレースは行われません。

         -S interval
              指定された間隔 (秒単位) で定期的に標本を収集します。 プ
              ロ セスからデータ標本を記録します。カーネルからのタイム
              スタンプと実行統計などの情報も含まれます。interval には
              次の値を指定できます。

              値          意味

              off       定期的な標本収集を行いません

              on        デフォルトの間隔 (1 秒) で定期的な標本収集 を
                        行います

              n         n (秒) の間隔で定期的な標本収集を行います。 n
                        には正の値を指定する必要があります。

              デフォルトでは、定期的な標本収集が行われます。

         データを指定する引数がない場合は、デフォルトの分解能で時間プ
         ロファイルデータを収集します。

         時間ベースのプロファイリングが明示的に無効にされていて、ハー
         ドウェアオーバーフロープロファイリングまたはどの種類のトレー
         スも有効にされていない場合は、関数レベルのデータが収集されな
         いことを示す警告が表示されて、ターゲットが実行され、グローバ
         ルデータが記録されます。

         注:     この early-access リリースの場合、Linux システムでこ
               の オ プ ションを付けて collect を実行すると、矛盾する
               データが多くなります。

      実験の制御
         -L size
              記録されるプロファイルデータとトレースデータの量を size
              メ ガバイトに制限します。この制限は、すべてのプロファイ
              ルデータとトレースデータの合計に適用されますが、標本 収
              集 ポイントには適用されません。制限に達すると、データの
              プロファイリングおよびトレースが停止されま す が、 ター
              ゲッ トプロセスが終了するまで実験は開いたままになり、標
              本が記録されます。size には次の値を指定できます。

              値          意味

              unlimited または none
                        記録されるデータ量を制限しません

              n         記録されるデータ量を n メガバイトに制限 し ま
                        す。 n には 0 (ゼロ) 以外の正の値を指定する必
                        要があります。

              記録されるデータ量のデフォルトの制限値は、2,000 メガ バ
              イトです。

         -F option
              派生プロセスのデータが記録されるか否かを制御 し ま す。
              option には以下の値を指定できます。

              値          意味

              on        fork および exec からの派生プロセスに関する実
                        験を記録します

              all       すべての派生プロセスに関する実験を記録します

              off       派生プロセスに関する実験を記録しません。

              デフォルトでは、派生プロセスは記録されません。詳細 は、
              下記の「派生プロセスのフォロー」を参照してください。

         -A option
              ターゲットプロセスによって使用されるロードオブジェク ト
              を、 記 録 された実験に保管またはコピーするかを制御しま
              す。option には次の値を指定できます。

              値          意味

              on        ロードオブジェクトを実験に保管します。

              off       ロードオブジェクトを実験に保管しません。

              copy      ロードオブジェクトを実験にコピーし、保管し ま
                        す。

              実験を別のマシンにコピーしたり、別のマシンから読み取 り
              た い場合には、-A copy と指定する必要があります。この場
              合、ソースおよびオブジェクトファイルはコピーさ れ ま せ
              ん。 そのため、ユーザー自身が、実験を実行するマシン上か
              らそれらのファイルにアクセスできるようにしておく必要 が
              あります。

              -A のデフォルトの設定は on です。

         -j option
              ターゲットが JVM マシンの場合、Java プロファイルを制 御
              します。option には以下の値を指定できます。

              値          意味

              on        JVM マシンのプロファイルデータを記録し、 Java
                        HotSpot(TM)  仮想マシンによるコンパイル方式を
                        認識します。JVM マシンが 1.4.1 以降の 場 合、
                        Java の呼び出しスタックも記録します。

              off       Java プロファイルデータを記録しません。
         注: Linux システムでは、Java プロファイリングは行えません。

              以下の「Java プロファイル」の項を参照してください。

              ターゲットが JVM マシンの場合、プロファイルデータを取得
              す る には -j on を使用する必要があります。ターゲットが
              class または jar ファイルの場合は、-j on オプションは不
              要 です。64 ビット JVM マシンのユーザーは、ターゲットと
              してそのパスを明示的に指定する必要があります。32 ビット
              JVM マシンには、-d64 オプションは使いません。-j on オプ
              ションを指定しても、ターゲットが JVM マシンではない場合
              は、 無効な引数がターゲットに渡され、データは記録されま
              せん。collect コマンドにより、Java プロファイルに指定さ
              れた JVM マシンのバージョンの妥当性検査が行われます。

         -l signal
              指定されたシグナルがプロセスに送られるたびに、標本収 集
              ポイントを記録します。

         -y signal[,r]
              signal を使用して、データの記録を制御します。指定された
              シ グナルがプロセスに配信されるときはいつでも、一時停止
              (データ記録なし) と再開 (データを記録) の間でステータス
              を 切り替えます。任意の ,r フラグが指定された場合、コレ
              クタはステータスを再開にして起動されます。それ以外の 場
              合 は、ステータスは一時停止で起動されます。このオプショ
              ンは、標本収集ポイントの記録には影響しません。

      出力の制御
         -o experiment_name
              記録される実験の名前として experiment_name を使用 し ま
              す。experiment_name 文字列の末尾は .er でなければなりま
              せん。そうでない場合はエラーが報告され、実験は実行さ れ
              ません。

              -o が指定されなかった場合は、実験に stem.n.er の形式 の
              名 前が付けられます。stem は文字列で、n は番号です。 -g
              を使ってグループ名が指定された場合、stem には、.erg  な
              し のグループ名が設定されます。グループ名が指定されない
              場合は、stem は文字列 "test" に設定されます。

              MPI ジョブを実行するためのコマンドの 1 つから呼び出され
              て、 -o が指定されていない場合は、そのプロセスの MPI ラ
              ンクを定義するための環境変数から、名前で使用されてい る
              n  値が取られます。それ以外の場合は、n は使用されている
              最大の整数よりも 1 つ大きい値に設定されます。

              stem.n.er 型で名前が指定されておらず、指定の名前が使 用
              さ れている場合は、エラーメッセージが出力され、実験は実
              行されません。名前が stem.n.er 型であり、指定されている
              名前が使用されている場合、実験は、使用されている n の値
              よりも 1 つ大きい値に対応する名前で記録されます。名前が
              変更された場合、警告が出力されます。

         -d directory_name
              実験をディレクトリ directory_name に保存します。ディ レ
              ク トリが指定されなかった場合は、実験は現在の作業ディレ
              クトリに保存されます。

         -g group_name
              実験を実験グループ group_name に追加します。 group_name
              文 字列の末尾は .erg でなければなりません。そうでない場
              合はエラーが報告され、実験は実行されません。

         -O file
              collect からのすべての出力を指定された名前のファイル の
              最 後に追加しますが、生成されたターゲットからの出力はリ
              ダイレクトされません。file に /dev/null が設定されて い
              る 場合は、エラーメッセージを含めて、collect からのすべ
              ての出力が抑止されます。

      その他の引数
         -C comment
              notes ファイルに実験に関するコメントを書き込みます。 最
              大 10 個の -C 引数を指定できます。

         -n   dry run。ターゲットは実行されませんが、実行予定の実験の
              すべての詳細が出力されます。-v 引数がオンになります。

         -R   パフォーマンスツール README のテキスト版が端末ウィン ド
              ウに表示されます。README が見つからない場合は、警告が出
              力されます。その他の引数の検査は行われず、その他の処 理
              も行われません。

         -V   現在のバージョンを出力します。その他の引数のチェック は
              行われず、その他の処理も行われません。

         -v   現在のバージョンと、実行中のエクスペリメントに関する 追
              加の詳細情報を出力します。

         -x   デバッガをターゲットプロセスにアタッチさせるため、 exec
              シ ステムコールからの終了時にターゲットプロセスを停止さ
              せます。

              collect によって停止されたターゲットにデバッガを接続 す
              る には、下記の手順に従う必要があります。Linux システム
              では、このオプションは使用できません。

              - プロセスの PID を決定します。

              - デバッガを起動します。

              - SIGPROF を (ハードウェアカウンタデータを収集する場 合
                は SIGEMET も) 無視するようにデバッガを構成します。

              - PID を使用してプロセスに接続します。

              プロセスはデバッガの制御の下で実行され、実験はコレク タ
              により記録されます。

## 派生プロセスのフォロー

         プロセスは、システムライブラリ関数を呼び出して派生プロセスを
         作 成 で き ま す。コレクタは、fork(2)、fork1(2)、fork(3F)、
         vfork(2)、および exec(2) ならびにその派生関数の呼び出しに よ
         り起動される派生プロセスのデータを収集できます。vfork の呼び
         出しは内部で fork1 の呼び 出 し に 置 き 換 え ら れ ま す。
         system(3C)、 system(3F)、 sh(3F)、 popen(3C)、および類似の関
         数、ならびに関連する派生プロセスの呼び出しはコレクタにより無
         視されます。-F on 引数が使用されている場合、コレクタは親の実
         験内で 1 つの派生プロセスに 1 つの新しい実験を開きます。これ
         らの新しい実験には、次のような名前が付けられます。

         - 作成者の実験名の最後に下線が付けられます。

         - コード文字が追加されます。fork の場合 "f"、exec の場合 "x"
           です。

         - コード文字の後に番号 (fork または exec のインデックス)  が
           付けられます。この番号の割り当ては、プロセスの起動に成功し
           たかどうかに関係なく行われます。

         たとえば、初期プロセスの実験名が "test.1.er" の場合、その  3
         番目の fork によって生成された派生プロセスの実験名は
          "test.1.er/_f3.er" になります。派生プロセスが新しいイメージ
         を  exec した場合、対応する実験名は "test.1.er/_f3_x1.er" に
         なります。

         -F all 引数が指定されている場合は、system(3C)、 system(3F)、
         sh(3F)、popen(3C) や類似の関数のものを含めて、すべての派生プ
         ロセスが処理されます。-F on ではなく、-F all で処理された 派
         生プロセスには、コード文字 "c" を使った名前が付けられます。

         アナライザおよび er_print は、親の実験を読み取るとき、派生プ
         ロ セ スの実験を自動的に読み取りますが、派生プロセスの実験は
         データ表示の対象としては選択されません。

         表示するデータをコマンド行から選択するには、er_print また は
         ア ナ ライザにそのパス名を明示的に指定します。指定するパスに
         は、親の実験名と親の実験ディレクトリ内の派生プロセスの実験名
         が含まれている必要があります。

         たとえば、実験 test.1.er の 3 番目のフォーク用のデータを見る
         場合は、以下のように入力します。
                   er_print test.1.er/_f3.er
                   analyzer test.1.er/_f3.er

         派生の実験の明示的な名前を使って、実験グループファイルを作成
         することができます。

         アナライザで派生プロセスを確認するには、親の実験を読み込み、
         「表示」メニューから「データをフィルタ」を選択します。アナラ
         イザが、親の実験だけ選択した状態で実験のリストを表示します。
         親の実験を選択解除して、確認したい派生の実験を選択します。

## マルチスレッドアプリケーションのプロファイル

         collect は、すべてのマルチスレッドアプリケーションで使用する
         ことができますが、Solaris 8 のデフォルトのスレッド (T1) はプ
         ロファイルの際にさまざまな問題の原因となります。LWP でスレッ
         ド がスケジュールされていない場合、T1 はプロファイル割り込み
         を破棄する可能性があります。この場合、全 LWP 時間が 本 当 の
         LWP 時間よりも非常に短く報告される可能性があります。また、場
         合によっては、内部ライブラリ mutex へのセグメント違反アク セ
         スを行い、アプリケーションがクラッシュする可能性があります。

         Solaris 8 では、LD_LIBRARY_PATH の設定の先頭に  /usr/lib/lwp
         を付加し、代替のスレッドライブラリ (T2) を使用することによっ
         て問題を回避することができます。Solaris 9 以降では、T2 が デ
         フォルトのライブラリになっています。

         コレクタは T1 の使用を検出し、実験に警告を挿入します。

         マルチスレッドのプロファイリングは Linux でも使用すること が
         可 能 です。しかし、この early-access リリースの場合、RedHat
         Linux システムで矛盾するデータが大量に発生します。

## Java プロファイル

         Java プロファイルでは、ユーザーの .class または .jar ファ イ
         ル を実行する JVM マシンでパフォーマンス実験の収集が行われま
         す。また、可能であれば、Java モデル、マシンモデル内で呼び 出
         し スタックの収集が行われます。Linux システムでは、Java プロ
         ファイリングは行えません。

         データは Java モデル、上級 Java モデル、マシンモデルのいずれ
         か で表示されます。Java モデルは、各メソッドの名前と、解釈さ
         れ、HotSpot を使用してコンパイルされたメソッドのデータを表示
         し ます。また、非ユーザーJava スレッドのデータを抑止します。
         上級 Java モデルは、解釈されたメソッドからHotSpot を使用して
         コ ンパイルされたメソッドを分離し、非ユーザーJava スレッドの
         データを抑止しません。マシンモデルは、解釈を行なった JVM  マ
         シンに対して、解釈された Java メソッドのデータを表示し、指定
         されたメソッドに関して、Java HotSpot 仮想マシンを使用して コ
         ン パ イルしたメソッドのデータを報告します。いずれのモデルで
         も、Java ターゲットによって呼び出される C、C++、または  For-
         tran  の コー ドの通常の方法でデータが報告されます。これらの
         コードは、Java のネイティブメソッドに対応するものです。ア ナ
         ラ イザと er_print では、Java モデルとマシンモデルを切り替え
         ることができます。デフォルトは Java モデルです。

         クロックに基づくプロファイルとハードウェアカウンタプロファイ
         ル がサポートされています。同期トレースでは、Java モニター呼
         び出しとネイティブコードからの同期呼び出しのデータのみを収集
         します。JVM マシン内での内部同期呼び出しに関するデータは収集
         しません。ヒープトレースでは、Java 割り当て、ガーベジコレ ク
         ショ ン、 ユー ザーコードまたは JVM マシンから記憶域割り当て
         ルーチンへのネイティブ呼び出しのデータを収集します。

         collect コマンドによって java のターゲット名が引数リストに挿
         入 さ れ る と、 java  ター ゲッ ト へ の パ ス の環境変数が
         JDK_1_4_HOME、JDK_HOME、次に JAVA_PATH、最後 に ユー ザー の
         PATH  の 順 序でチェックされます。設定される最初のパスについ
         て、結果のターゲットが ELF 実行可能ファイルかどうかが確認 さ
         れます。ELF 実行可能ファイルでなければ、collect コマンドは失
         敗となり、使用された環境変数と試行されたフルパス名を示 す エ
         ラーを出力します。

         これらの環境変数が設定されない場合、collect は、ユー ザー の
         PATH  を 使 用して解決したターゲット名として java を使用しま
         す。

         Java プロファイルは、Java[tm] 2 SDK のバージョン 1.4.2_02 以
         降が必要です。これより以前のバージョンの 1.4.2、1.4.1、1.4.0
         を使用して Java コードのプロファイルを試みると、プロファイル
         は 失 敗します。マシンモデル内の Java プロファイルのデータは
         Java 2 SDK のバージョン 1.4.0 以降でのみ、Java モデ ル 内 の
         デー タは Java 2 SDK のバージョン 1.4.1 以降でのみ使用できま
         す。

## データ空間のプロファイリング

         データ空間のプロファイルとは、単にキャッシュミスなどの メ モ
         リー関連イベントが発生する命令ではなく、そのイベントの原因に
         なっているデータオブジェクト参照を基準にメモリー関連のイベン
         ト を 記録したデータの集まりのことです。Linux システムでは、
         データ空間のプロファイリングは行えません。

         データ空間プロファイリングが可能であるためには、すでに説明し
         ているように、ターゲットが、-xhwcprof -xdebugformat=dwarf -g
         を付けて SPARC 用にコンパイルされた C プログラムである必要が
         あります。また、収集データとして、H/W カウンタプロファイルが
         存在し、カウンタ名の前にオプションの + を付けておく必要が あ
         ります。

         収集されたデータがあることにより、er_print でさらに次の 3 つ
         コ マ ン ド を 使 用 で き る ようになります。data_objects、
         data_osingle、data_olayout。詳細は、er_print(1) のマニュアル
         ページを参照してください。

         また、アナライザには、データ空間プロファイリングに関係する、
         「デー タオブジェクト」と「データレイアウト」という 2 つのタ
         ブが追加されています。詳細は、analyzer(1) のマニュアルページ
         を参照してください。

## MPI を指定した collect の使用

         collect は、MPI ジョブを開始するコマンド行に collect とそ の
         引数の前にターゲットとその引数を指定するだけで、MPI を指定し
         て使用できます。以下に例を示します。
              % mprun -np 16 a.out 3 5
         を
              % mprun -np 16 collect -m  on  -d  /tmp/mydirectory  -g
              run1.erg a.out 3 5
         に置き換えると、16 個の各 MPI プロセスについて MPI トレー ス
         実験を実行し、すべての実験を指定のディレクトリにグループとし
         て収集することができます。上記のように、各実験は、MPI ランク
         で指定されます。上記のように指定される実験には、デフォルトで
         実行されるクロックに基づくプロファイルデータと、MPI トレース
         データが含まれます。

         Linux システムでは、このオプションは使用できません。

## PPGSZ を指定した collect の使用

         ppgsz コマンドで、collect コマンドを使用できます。このために
         は 、 -F  on を付けて、ppgsz コマンド上で collect を実行しま
         す。親の実験は ppgsz 実行可能ファイル上にあり、無関係で す。
         32  ビット版の ppgsz がパス上に見つかり、64 ビットプロセスを
         サポートするシステムで実験が実行されている場合は、ま ず、 64
         ビッ ト版で実験がおこなわれ、_x1.er を作成します。その実行可
         能ファイルはフォークし、_x1_f1.er を作成します。派生プロセス
         は、パスの最初のディレクトリ、その次のディレクトリというよう
         にして、exec が成功するまで、指定されたターゲットの exec  を
         試 みます。たとえば、3 番目で成功した場合、それまでの 2 つの
         派生実験は、_x1_f1_x1.er および _x1_f1_x2.er と名付けら れ、
         それらは両方とも完全に空となります。ターゲット上の実験は成功
         した exec からのもので (上記の例では 3 番目 )、 _x1_f1_x3.er
         と名付けられて親実験の下に保存されます。このプロセスは、アナ
         ライザまたは test.1.er/_x1_f1_x3.er 上で er_print を起動する
         ことで直接行うことができます。

         実行された初期プロセスが 64 ビット ppgsz の場合、あるいは 32
         ビットカーネルで 32 ビットppgsz が呼び出された場合、上記の例
         と同じパスであると仮定すると、本来のターゲットを exec  す る
         fork  の 派 生プロセスのデータは _f1.er に置かれ、本来のター
         ゲットの実験は、_f1_x3.er に置かれます。
         上記の「派生プロセスのフォロー」の項を参照してください。

## SETUID/SETGID ターゲットを指定した collect の使用

         collect コマンドは、共有ライブラリ  libcollector.so  を ター
         ゲットのアドレス空間 (LD_PRELOAD) に挿入することで操作可能に
         なります。また、2 つ目の共有ライブラリ collaudit.so を使用す
         ることで、実行時リンカーの監査インタフェース (LD_AUDIT) と共
         に使用する共有オブジェクトを記録できます。これらの共有ライブ
         ラリにより、実験を構成するファイルを作成します。

         collect を setuid または setgid である実行ファイル上で起動し
         た 場合、または、setuid または setgid となる派生プロセスを作
         成する実行ファイル上で起動した場合、問題が発生することがあり
         ます。実験を実行するユーザーが root ではない場合、共有ライブ
         ラリが信頼できるディレクトリにインストールされていないため、
         収 集 は失敗します。この問題を回避するには、実験を root ユー
         ザーで実行します。

         さらに、collect を実行するユーザーの umask は、そのユー ザー
         が書き込みできるようにアクセス権を設定する必要があります。ま
         た、exec が行われるプログラム上で setuid/setgid 属性が設定さ
         れる他のユーザーおよびグループ、および、そのようなプログラム
         が自身を設定する他のユーザーおよびグループに対しても書き込み
         権 を 設定する必要があります。マスクが正しく設定されていない
         と、一部ファイルが実験に書き込まれないことがあり、その場合、
         実 験 の処理は不可能になります。ログファイルが書き込める場合
         は、ユーザーが実験を行おうとした際のエラーを見ることができま
         す。

         また、ターゲット自身が UID や GID を設定するシステムコールを
         作成した場合、または、umask を変更して fork や exec の他のプ
         ロセス、または crle が実行時リンカーがどのように共有オブジェ
         クトを検索するかの構成を設定するために使用された場合、問題が
         発生することがあります。

## 収集されるデータ

         プロファイルデータ、トレースデータ、標本収集データの 3 種 類
         の デー タが収集されます。プロファイルとトレースで記録される
         データパケットには、各 LWP の呼び出しスタック、LWP、 ス レッ
         ド、CPU ID、およびイベント固有のデータが含まれます。標本収集
         で記録されるデータパケットは、実行統計などのグローバルデータ
         で、プログラム固有のデータやイベント固有のデータは含まれませ
         ん。すべてのデータパケットには時刻表示が含まれます。

         クロックに基づいたプロファイル
              クロックに基づいたプロファイルで記録されるイベント固 有
              の データは、各アカウンティングマイクロステートのカウン
              ト配列です。このマイクロステート配列は、指定された周 波
              数 で自動的に増分し、プロファイルシグナルが処理されると
              コレクタにより記録されます。

              クロックに基づくプロファイルは一定の範囲の頻度  ( プ ロ
              ファ イルタイマー用に使用されるクロック分解能の倍数であ
              る必要があります) で行うことができます。Solaris 7 環 境
              と Solaris 8 のアップデートの一部では、システムクロック
              が使用されます。これらのシステムで高分解能間隔 で プ ロ
              ファ イルを行うには、マシン上のオペレーティングシステム
              が高分解能クロックルーチンで動作している必要が あ り ま
              す。 こ の ルーチンを実行するには、次の行を /etc/system
              ファイルに設定してリブートしてください。

                   set hires_tick=1

              高分解能プロファイルをサポートしない OS を持つマシン で
              高 分 解 能プロファイルを設定しようとした場合には、警告
              メッセージが返され、サポート可能な最も高い分解能値が 使
              用 されます。同様に、カスタム設定がそのシステムでサポー
              トされる分解能値の倍数でない場合には、その値に最も近 い
              0 以外の倍数に丸められ、警告メッセージが出力されます。

              クロックに基づくプロファイルデータは、以下のメトリッ ク
              に変換されます。

                   ユーザー CPU 時間
                   時計時間
                   LWP 合計時間
                   システム CPU 時間
                   CPU 待ち時間
                   ユーザーロック時間
                   テキストページフォルト時間
                   データページフォルト時間
                   そのほかの待ち時間

              マルチスレッドアプリケーションの実験では、時計時間を 除
              くすべての時間は、プロセス内のすべての LWP にわたって合
              計されます。時計時間は、LWP 1 のすべての状態において 消
              費 された時間です。LWP 合計時間は、実際の経過時間にプロ
              セス内の LWP の平均数を乗じたものです。

         ハードウェアカウンタのオーバーフローのプロファイル
              ハードウェアカウンタのオーバーフローのプロファイル は、
              オー バーフローシグナルが処理されたときにハードウェアカ
              ウンタによりカウントされたイベントの数を記録 し ま す。
              Linux  システムでは、この種のプロファイリングは行えませ
              ん。

              ハードウェアカウンタのオーバーフローのプロファイル は、
              オー バーフロープロファイルをサポートし、ハードウェアカ
              ウンタ共用ライブラリ libcpc.so(3) を含むシステムで実 行
              可能です。Solaris 8 以降の Solaris[tm] オペレーティング
              環境バージョンを使用してください。UltraSPARC[tm]  コ ン
              ピュータでは、UltraSPARC III 以降のハードウェアバージョ
              ンを使用してください。オーバーフローのプロファイルを サ
              ポー ト し ていないコンピュータでハードウェアカウンタの
              オーバーフローのプロファイルを選択しようとす る と、 エ
              ラーになります。

              使用可能なカウンタは、CPU チップおよびオペレーティン グ
              環境によって異なります。引数なしで collect コマンドを実
              行すると、カウンタ名を含む使用法のメッセージが表示さ れ
              ま す。最初に別名を持つカウンタが、それに続いてすべての
              カウンタが一覧表示されます。

              別名を持つカウンタの出力行の書式は以下のとおりです。

                CPU サイクル (cycles = Cycle_cnt/*) 9999991 hi=1000003, lo=100000007 (CPU-cycles)
                命令の実行 (insts = Instr_cnt/*) 9999991  hi=1000003, lo=100000007 (Events)
                D$ 読み込み失敗 (dcrm = DC_rd_miss/1) 100003  hi=10007, lo=1000003 load (Events)

              最初の行で、最初のフィールド「CPU サイクル」はメト リッ
              ク 名 を 示 し ま す。2 番目のフィールド「cycles」は -h
              counter... の引数として使用できる別名を示します。3 番目
              のフィールド「Cycle_cnt/*」は、cputrack(1) で使用される
              内部名と、カウンタを使用できるレジスタの番号を 示 し ま
              す。レジスタの番号は 0、1、* のいずれかです。* は、どち
              らのレジスタでもカウンタを使用できることを示します。 そ
              の 次のフィールドはデフォルトのオーバーフロー間隔で、そ
              の次のフィールドはデフォルトの高分解能オーバーフロー 間
              隔、 最 後 のフィールドはデフォルトの低分解能オーバーフ
              ロー間隔です。(CPU-cycles) は、カウンタは CPU-cycles の
              単 位でカウントし、時間に変換することができることを示し
              ています。2 行目の終わりにある (Events) は、カウンタ は
              イ ベントをカウントし、時間に変換することができないこと
              を示しています。3 行目のように、低分解能オーバーフ ロー
              間 隔とカウンタの単位の間に、カウンタがロード、ストア、
              ロードまたはストアによって起動するか、プログラムに関 係
              な く動作するかを示すフィールドが表示される場合がありま
              す。

              別名を持たないカウンタの出力行の書式は以下のと お り で
              す。
                Cycle_cnt Events (reg. 0) 1000003 hi=100003, lo=9999991 (CPU-cycles)
                Instr_cnt Events (reg. 0) 1000003 hi=100003, lo=9999991 (Events)
                DC_rd Events (reg. 0) 1000003 hi=100003, lo=9999991 load (Events)

              この行で、最初の フィー ル ド 「Cycle_cnt/0」 は、 cpu-
              track(1) で使用される内部名と、カウンタを使用できるレジ
              スタの番号を示します。文字列「Cycle_cnt/0 events」 は、
              こ のカウンタに対するメトリック名です。次のフィールドで
              は、レジスタ番号が括弧内に表示されます。その次の フィー
              ル ドはデフォルトのオーバーフロー間隔で、その次のフィー
              ルドはデフォルトの高分解能オーバーフロー間隔、その次 の
              フィー ル ド はデフォルトの低分解能オーバーフロー間隔で
              す。最後のフィールドでは、カウンタの単位 と し て  CPU-
              cycles または Events が括弧内に表示されます。2 行目は、
              時間に変換することができないカウンタを示していま す。 3
              行 目のように、低分解能オーバーフロー間隔とカウンタの単
              位の間に、カウンタがロード、ストア、ロードまたはスト ア
              に よって起動するか、プログラムに関係なく動作するかを示
              すフィールドが表示される場合があります。

              行の最後に「(CPU-cycles)」で示す、サイクルでカウント す
              る カウンタの場合、報告されるメトリックはデフォルトで包
              括的メトリック時間と排他的メトリック時間に変換されま す
              が、 任 意 でイベントカウントとして表示することもできま
              す。行の最後に「(Events)」で示す、イベントでカウント す
              る カ ウ ンタの場合、報告されるメトリックは、包括的メト
              リックのイベントカウントと排他的メトリックのイベント カ
              ウントです。

              名前の後ろに「ロード」、「ストア」、「ロード-ストア」と
              表 示されるメモリーオペレーションに関係するハードウェア
              カウンタのうち、名前の先頭に「+」記号が付くカウンタは、
              オー バーフローの原因となった命令や仮想アドレスを正確に
              特定するためのデータ収集を要求します。

              プログラムに関係なく動作するカウンタを使用してプロ ファ
              イ ルを行うと警告が発生し、呼び出しスタックを記録するか
              わりに、疑似関数「collector_not_program_related」を使用
              して消費時間が表示されます。スレッドと LWP の ID は記録
              されますが、意味がありません。

         同期遅延トレース
              同期遅延トレースは、呼び出しの実時間遅延が指定された し
              き い値を超える、さまざまなスレッド同期ルーチンへの呼び
              出しをすべて記録します。データパケットには、同期ルー チ
              ン へのエントリと終了の時刻表示、リクエストが発行された
              時点でのスレッド ID と LWP ID が含まれます (同じス レッ
              ドからの同期リクエストでも、ある LWP 上で実行されるもの
              が別の LWP で完了することもあるため)。Linux システム で
              は、同期遅延のトレースは行えません。
              同期遅延トレースデータは、以下のメトリックに変換され ま
              す。

                   同期遅延イベント
                   同期待ち時間

         ヒープトレース
              ヒープトレー ス は、 malloc、 free、 realloc、 お よ び
              memalign への呼び出しを、要求されたブロックのサイズ、そ
              のアドレス、および realloc については以前のアドレスとと
              もにすべて記録します。

              ヒープトレースデータは、以下のメトリックに変換 さ れ ま
              す。

                   リーク
                   リークされたバイト
                   割り当て
                   割り当てられたバイト

              リークは、解放されない割り当てとして定義されます。長 さ
              ゼ ロのブロックが割り当てられると、ゼロバイトを割り当て
              られた割り当てとしてカウントされます。長さゼロのブ ロッ
              ク が解放されない場合、ゼロバイトがリークされたリークと
              してカウントされます。

              Java で記述されたアプリケーションでは、リークはガベージ
              コレクトされていない割り当てとして定義されます。

              ヒープトレースを行うと実験が非常に大きくなり、処理に 時
              間がかかる可能性があります。

         MPI Tracing
              MPI トレースは、完了までにかなりの時間を要する関数に 対
              する MPI ライブラリの呼び出しを記録します。Linux システ
              ムでは、MPI のトレースは行えません。

              MPI ライブラリの次の関数がトレースされます。

                   MPI_Allgather
                   MPI_Allgatherv
                   MPI_Allreduce
                   MPI_Alltoall
                   MPI_Alltoallv
                   MPI_Barrier
                   MPI_Bcast
                   MPI_Bsend
                   MPI_Gather
                   MPI_Gatherv
                   MPI_Irecv
                   MPI_Isend
                   MPI_Recv
                   MPI_Reduce
                   MPI_Reduce_scatter
                   MPI_Rsend
                   MPI_Scan
                   MPI_Scatter
                   MPI_Scatterv
                   MPI_Send
                   MPI_Sendrecv
                   MPI_Sendrecv_replace
                   MPI_Ssend
                   MPI_Wait
                   MPI_Waitall
                   MPI_Waitany
                   MPI_Waitsome
                   MPI_Win_fence
                   MPI_Win_lock

              MPI トレースデータは、以下のメトリックに変換されます。

                   MPI 時間
                   MPI 送信
                   MPI 送信バイト
                   MPI 受信
                   MPI 受信バイト
                   その他の MPI 呼び出し

              MPI 時間とは、MPI 関数で消費される LWP 合計時間のことで
              す。

              MPI 受信バイトメトリックは、ブロック化呼び出しには実 際
              の バイト数を使用しますが、非ブロック化呼び出しにはバッ
              ファサイズを使用します。gather、scatter、reduce など の
              集 合操作について計算されるメトリックには、これらの操作
              の最大可能値が設定されています。集合操作の最適 化 の た
              め、値の削減は行われません。

              非ブロック受信用のバッファが実際の送信サイズよりもか な
              り 大きい場合、MPI 受信バイトは実際よりもかなり大きく報
              告される可能性があることに注意してください。

         標本収集とグローバルデータ
              標本収集とは、実行の時間軸に沿ってマーカーを生成する プ
              ロ セスです。各標本収集ポイントでは、実行統計が記録され
              ます。標本収集ポイントで記録されたデータはすべて、プ ロ
              グ ラムに対してグローバルなものとなり、関数レベルのメト
              リックにはマップされません。

              標本は常に、プロセスの開始時と終了時に収集されます。 デ
              フォ ルトで、またはゼロでない -S 引数が指定されると、標
              本は指定された間隔で定期的に収集されます。また、libcol-
              lector(3) の API を使用しても収集できます。
              各標本収集ポイントで記録されたデータは、カーネルから 送
              ら れるマイクロステートアカウンティング情報とそのカーネ
              ル内で保持されるさまざまな統計情報です。

## 制約事項

         コレクタは、一部のシグナル処理ルーチンに割り込み処理をして、
         ターゲットプログラムによって妨げられることなく、クロックに基
         づくプロファイルには SIGPROF シグナルを、ハードウェアカウ ン
         タのオーバーフロープロファイルには SIGEMT を使用します。ター
         ゲットプログラムがシグナルハンドラをインストールすると、コレ
         ク タ ライブラリは独自のシグナルハンドラを再インストールしま
         す。コレクタのシグナルハンドラは、フラグを設定して、システム
         コールが妨げられることなくシグナルを送信できるようにします。
         この設定により、ターゲットプログラムの動作が異なる可能性があ
         ります。

         クロックに基づくプロファイルが有効な場合には、コレク タ は、
         setitimer(2)  に 割 り込み処理をして、プロファイルタイマーを
         ターゲットプログラムに対して使用不可にします。

         コレクタは、ハードウェアカウンタライブラリ libcpc.so 内の 関
         数に割り込み処理をして、コレクタがパフォーマンスデータを収集
         しているときは、ハードウェアカウンタをアプリケーションに対し
         て 使用不可にします。割り込み処理された関数は、-1 の値を返し
         ます。

         Linux システムでは、ハードウェアカウンタプロファイリ ン グ、
         Java  プロファイリング、MPI プロファイリング、データ空間プロ
         ファイリング、および同期トレースは行えません。

         Linux システムでは、終了時にターゲットを停止したままに す る
         -x は使用できません。

         この early-access リリースの場合、Linux システムでは、信頼で
         きる定期標本の収集データは得られません。

         この early-access リリースの場合、RedHat Linux シス テ ム で
         は、 マ ルチスレッドアプリケーションをプロファイリングしたと
         き、広範囲のデータ矛盾が観察されています。

         ハードウェアカウンタプロファイルは、cpustat を実行中のシステ
         ムでは実行できません。これは、cpustat がカウンタを制御してお
         り、ユーザープロセスがカウンタを使用できないためです。

         Java プロファイルは、Java 2 SDK の 1.4 より以前のバージョ ン
         で はサポートされていません。Java モードプロファイルは、Java
         2 SDK の 1.4.1 より以前のバージョンではサポートされていま せ
         ん。

         setuid 属性を使用するように作成された派生プロセスや、動的 に
         リンクされていない実行可能ファイルの exec を使用して作成され
         た派生プロセスのデータは収集されません。さらに、それ以降の派
         生プロセスは実験の破損や読み取れない実験の生成の原因となる可
         能性があります。問題を回避するには、すべての派生プロセスが動
         的 にリンクされ、setuid 属性を持たないようにする必要がありま
         す。

         vfork(2) を呼び出すアプリケーションは、これらの呼び 出 し が
         fork1(2) の呼び出しに置き換えられます。

## 関連項目

         collector(1)、    dbx(1)、    er_archive(1)、     er_cp(1)、
         er_export(1)、  er_mv(1)、  er_print(1)、 er_rm(1)、 libcol-
         lector(3)、およびマニュアル
         『プログラムのパフォーマンス解析』