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

## 名前

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

## 形式

         collect collect-arguments target target-arguments

## 説明

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

         注: GUI プログラムの実行にはライセンスが必要です。

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

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

         collect コマンドは、次の方法を用いてターゲットを検索します。
          o ターゲット名を持つ、実行可能とマークされたファイルが存 在
          する場合は、ターゲットマシンで実行可能な ELF 実行可能ファイ
          ルかどうかが確認されます。ファイルが有効な ELF 実行可能ファ
          イルでない場合は、collect コマンドは失敗します。
          o ターゲット名を持つファイルが存在するが、実行可能ファイ ル
          で は な い場合、Java(TM) jar ファイルか class ファイルかが
          チェックされます。そのいずれかであれば、必要なフラグとと も
          に java のターゲット名が挿入され、データは JVM(TM) マシンに
          収集されます (「Java 仮想マシン」およ び 「JVM」 の 語 は、
          Java(TM) プラットフォーム用仮想マシンを指します)。
          o ターゲット名を持つファイルが存在しない場合、実行可能 ファ
          イ ルを探してユーザーのパスが検索されます。実行可能ファイル
          が見つかると、上記の確認が行われます
          o 現在の名前のファイルが見つからない場合、その名前に文字 列
          .class の付加された名前を持つファイルが検索されます。これが
          見つかると、上記のように該当するフラグとともに java の ター
          ゲット名が挿入されます。
          o 以上の手順でターゲットが見つからない場合、コマンドは失 敗
          となります。

## 引数

         引数なしで実行された場合は、collect から使用方法を示 す メッ
         セージが出力されます。このメッセージには、デフォルトの実験構
         成と、プロファイルに使用できるハードウェアカウンタの名前も含
         まれています。

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

              値          意味

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

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

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

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

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

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

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

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

              オーバーフロー値は、どの時点でカウンタがオーバーフ ロー
              し て、オーバーフローイベントが記録されるかを示す、カウ
              ントされるイベントの数です。以下のいずれかの値に設定 で
              きます。

              値          意味

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

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

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

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

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

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

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

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

              値          意味

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

              calibrate on と同じ

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

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

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

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

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

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

              値          意味

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

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

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

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

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

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

              値          意味

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

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

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

         -S interval
              指定された間隔 (秒単位) で定期的に標本を収集します。 標
              本 に記録されるデータはプロセスに関するデータで、特に時
              刻表示やカーネルの実行統計などが含まれます。interval に
              は次の値を指定できます。

              値          意味

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

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

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

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

         データ指定引数が指定されない場合は、クロックに基づくプロファ
         イルデータがデフォルトの分解能で収集されます。

         クロックに基づくプロファイルが明示的に使用不可にされ、ハード
         ウェアカウンタのオーバーフローのプロファイルもトレースも有効
         になっていない場合は、関数レベルのデータが収集できませんとい
         う 警 告 が collect コマンドから出力されます。その場合でも、
         ターゲットは実行され、グローバルデータは収集されます。

      実験の制御
         -L size
              記録されるプロファイルデータとトレースデータの量を size
              メ ガバイトに制限します。この制限は、すべてのプロファイ
              ルデータとトレースデータの合計に適用されますが、標本 収
              集 ポ イ ントには適用されません。この制限は近似値にすぎ
              ず、超過してもかまいません。制限値に達すると、プロ ファ
              イ ル デー タとトレースデータは記録されなくなりますが、
              ターゲットプロセスが終了するまで、実験は開かれてい て、
              サンプルを記録できます。size には次の値を指定できます。

              値          意味

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

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

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

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

              値          意味

              on        すべての子孫プロセスに関する実験を記 録 し ま
                        す。

              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 プロファイルデータを記録しません。

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

              ターゲットが JVM マシンの場合、プロファイルデータを取得
              す るには -j を使用する必要があります。JVM ソフトウェア
              のバージョンは 1.4 以降でなければなりません。Java プ ロ
              ファイルデータは、これより前の JVM ソフトウェアでは使用
              できません。ターゲットが class または jar ファイルの 場
              合は、-j オプションは不要です。64 ビット JVM マシンを使
              用している場合は、そのパスをターゲットとして明示的に 指
              定する必要があります。-j オプションが設定されても、ター
              ゲットが 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 に設定されます。

              collect コマンドが MPI ジョブの実行に使用されるコマンド
              の  1 つから起動され、-o が指定されていない場合、名前に
              使用される n の値は、そのプロセスの MPI ランクを定義 す
              る のに使用される環境変数から取られます。それ以外の場合
              は、n は未使用の最小の整数に設定されます。

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

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

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

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

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

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

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

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

              collect コマンドによりターゲットが停止した時点でデ バッ
              ガ を ターゲットに接続させるには、プロセスの 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 が使用される場合、コレクタは各子孫プ
         ロセスの新規実験を親実験内に開きます。これらの新規実験には、
         次のようにその系統名が付けられます。子孫プロセスの実験名は、
         子孫プロセスを作成する実験の名前に下線、コード文字、および数
         字 を 追 加して構成します。fork のコード文字は「f」、exec の
         コード文字は「x」です。数字は fork または exec のインデッ ク
         ス (成功かどうかにかかわらず) です。たとえば、初期プロセスの
         実験名が「test.1.er」である場合、その 3 番目の fork により作
         成される子プロセスの実験名は「test.1.er/_f3.er」になります。
         その子プロセスが新規イメージを実行する場合、対応する実験名は
         「test.1.er/_f3_x1.er」になります。

         アナライザと er_print は、親実験の読み取り時に子孫プロセスの
         実験を自動的に読み取りますが、データ表示の際には子孫プロセス
         の実験は選択されません。

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

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

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

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

## Java プロファイル

         Java プロファイルでは、ユーザーの .class または .jar ファ イ
         ル を実行する JVM マシンでパフォーマンス実験の収集が行われま
         す。また、可能であれば、Java モデル、マシンモデル内で呼び 出
         し スタックの収集が行われます。Java モデルは、各メソッドの名
         前と、解釈され、HotSpot を使用してコンパイルされたメソッドの
         デー タを表示します。マシンモデルは、解釈を行なった JVM マシ
         ンに対して、解釈された Java メソッドのデータを表示し、指定さ
         れ たメソッドに関して、Java HotSpot 仮想マシンを使用してコン
         パイルしたメソッドのデータを報告します。どちらのモデルでも、
         Java  ター ゲットによって呼び出される C、C++、または Fortran
         のコードの通常の方法でデータが報告されます。これらの コー ド
         は、 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 以前 で
         は サ ポー トされません。1.4 以前のバージョンを使用して Java
         コードのプロファイルを試みると、プロファイルは失敗します。こ
         れ らのバージョンの java 実行可能ファイルは ELF 実行可能ファ
         イルではなくシェルスクリプトであり、Java プロファイ ル の サ
         ポー ト に必要な機能が使用できないためです。マシンモデル内の
         Java プロファイルのデータは Java 2 SDK のバージョン 1.4.0 以
         降 で の み、Java モデル内のデータは Java 2 SDK のバージョン
         1.4.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 トレース
         データが含まれます。

## 収集されるデータ

         プロファイルデータ、トレースデータ、標本収集データの 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 の平均数を乗じたものです。

         ハードウェアカウンタのオーバーフローのプロファイル
              ハードウェアカウンタのオーバーフローのプロファイル は、
              オー バーフローシグナルが処理されたときにハードウェアカ
              ウンタによりカウントされたイベントの数を記録します。

              ハードウェアカウンタのオーバーフローのプロファイル は、
              オー バーフロープロファイルをサポートし、ハードウェアカ
              ウンタ共用ライブラリ 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 で完了することもあるため)。

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

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

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

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

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

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

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

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

         MPI トレース
              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 の値を返し
         ます。

         ハードウェアカウンタプロファイルは、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)、およびマニュアル
         『プログラムのパフォーマンス解析』