collect(1)

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

形式
collect collect-arguments target target-arguments
collect
collect -V
collect -R

説明

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

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) で使用される内部名でもかまいません。標準名と内部名を一覧表示するには、コマンド行に collect を入力する必要があります。 名前が内部名で、末尾がスラッシュ (/) と 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++、または 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.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」は、cputrack(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 引数が指定されると、標本は指定された間隔で定期的に収集されます。また、libcollector(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)、 libcollector(3)、 およびマニュアル
『プログラムのパフォーマンス解析』