test

Oracle Solaris Studio 12.2: パフォーマンスアナライザ

collect コマンドによるデータの収集

collect コマンドを使用してコマンド行からコレクタを実行するには、次のコマンドを使用します。


% collect collect-options program program-arguments

ここで、collect-options は collect コマンドのオプションで、program はデータ収集対象のプログラム名、program-arguments はプログラムの引数です。ターゲットプログラムは通常、バイナリ実行可能ファイルです。ただし、環境変数 SP_COLLECTOR_SKIP_CHECKEXEC を設定する場合は、ターゲットとしてスクリプトを指定できます。

collect-options を指定しなかった場合は、デフォルトで時間ベースのプロファイルが有効になり、プロファイル間隔は約 10 ミリ秒になります。

プロファイルに使用可能なオプションとハードウェアカウンタの名前の一覧を表示するには、引数を指定せずに collect コマンドを入力します。


% collect

ハードウェアカウンタの一覧については、「ハードウェアカウンタオーバーフローのプロファイルデータ」を参照してください。「ハードウェアカウンタオーバーフローのプロファイルに関する制限事項」も参照してください。

データ収集オプション

これらのオプションは、収集されるデータの種類を制御します。データの種類については、「コレクタが収集するデータの内容」を参照してください。

データ収集オプションを指定しなかった場合、デフォルトは -p on で、デフォルトのプロファイル間隔 (約 10 ミリ秒) で時間ベースのプロファイルが行われます。このデフォルト設定は、-h オプションを使用することによってのみ無効にできます。

時間ベースのプロファイルを明示的に無効とし、すべてのトレースとハードウェアカウンタオーバーフロープロファイルを有効にしなかった場合、collect コマンドは警告メッセージを出力し、大域データだけを収集します。

-p option

時間ベースのプロファイルデータを収集します。option に使用できる値は次のとおりです。

collect コマンドは、デフォルトで時間ベースのプロファイルデータを収集します。

-h counter_definition_1...[, counter_definition_n]

ハードウェアカウンタオーバーフローのプロファイルデータを収集します。カウンタ定義の数はプロセッサによって異なります。

このオプションは、Linux オペレーティングシステムを実行しているシステムでも、perfctr パッチをインストールすれば使用できるようになります。このパッチは、http://user.it.uu.se/~mikpe/linux/perfctr/2.6/ からダウンロードできます。インストール方法の指示は、tar ファイルに含まれています。ユーザーレベルの libperfctr.so ライブラリは、LD_LIBRARY_PATH 環境変数の値を使用して検索されたあとで、32 ビットバージョンでは /usr/local/lib、/usr/lib、および /lib で、64 ビットバージョンでは /usr/local/lib64、/usr/lib64、および /lib64 で検索されます。

使用可能なカウンタの一覧を表示するには、引数なしで collect コマンドを端末ウィンドウに入力します。カウンタの一覧については、「ハードウェアカウンタのリスト」を参照してください。ほとんどのシステムでは、カウンタが一覧に記載されていない場合でも、16 進数または 10 進数の数値で指定できます。

カウンタ定義には、プロセッサがハードウェアカウンタの属性をサポートしているかどうかに応じて、次のいずれかの形式を使用できます。

[+]counter_name[/ register_number][,interval ]

[+]counter_name[~ attribute_1=value_1]...[~attribute_n =value_n][/ register_number][,interval ]

プロセッサ固有の counter_name には、次のいずれかを指定できます。

複数のカウンタを指定する場合、それらのカウンタは異なるレジスタを使用する必要があります。同じレジスタが指定された場合、collect コマンドはエラーメッセージを出力して終了します。

ハードウェアカウンタがメモリーアクセスに関連するイベントをカウントする場合、カウンタ名の前に + 記号を付けて、カウンタのオーバーフローを発生させた命令の実際のプログラムカウンタアドレス (PC) の検索をオンにすることができます。バックトラッキングは SPARC プロセッサ上で、load、store、load-store のいずれかのタイプのカウンタでのみ機能します。検索が成功すると、仮想 PC、物理 PC、および参照された有効アドレスがイベントデータパケットに格納されます。

一部のプロセッサでは、属性オプションをハードウェアカウンタと関連付けることができます。プロセッサが属性オプションをサポートしている場合は、collect コマンドを引数リストなしで実行すると、属性名を含むカウンタ定義が一覧表示されます。属性値は、10 進数または 16 進数形式で指定できます。

間隔 (オーバーフロー値) は、ハードウェアカウンタがオーバーフローしてオーバーフローイベントが記録されたときにカウントされたイベントまたはサイクルの数です。間隔は、次のいずれかに設定できます。

デフォルトでは、各カウンタに定義済みの通常のしきい値が使用されます。これらの値はカウンタの一覧に表示されます。「ハードウェアカウンタオーバーフローのプロファイルに関する制限事項」も参照してください。

-p オプションを明示的に指定せずに -h オプションを使用すると、時間ベースのプロファイルが無効となります。ハードウェアカウンタデータと時間ベースデータの両方を収集するには、-h オプションと -p オプションの両方を指定する必要があります。

-s option

同期待ちトレースデータを収集します。option に使用できる値は次のとおりです。

Java プログラムでは同期待ちトレースデータは記録されず、指定するとエラーとして処理されます。

Solaris では、次の関数がトレースされます。

mutex_lock()

rw_rdlock()

rw_wrlock()

cond_wait()

cond_timedwait()

cond_reltimedwait()

thr_join()

sema_wait()

pthread_mutex_lock()

pthread_rwlock_rdlock()

pthread_rwlock_wrlock()

pthread_cond_wait()

pthread_cond_timedwait()

pthread_cond_reltimedwait_np()

pthread_join()

sem_wait()

Linux では、次の関数がトレースされます。

pthread_mutex_lock()

pthread_cond_wait()

pthread_cond_timedwait()

pthread_join()

sem_wait()

-H option

ヒープトレースデータを収集します。option に使用できる値は次のとおりです。

デフォルトでは、ヒープのトレースは無効です。ヒープトレースは Java プログラムについてはサポートされず、指定するとエラーとして処理されます。

-M option

MPI 実験の収集を指定します。collect コマンドのタ−ゲットは mpirun コマンドである必要があります。また、mpirun コマンドのオプションは、‐‐ オプションを使って mpirun コマンドによって実行されるターゲットプログラムと分けて指定されることが必要です。(mpirun コマンドでは常に ‐‐ オプションを使用することで、collect コマンドとそのオプションを mpirun コマンド行の先頭に追加し、実験を収集できます。)この実験には通常の名前が付けられ、親の実験と呼ばれます。ディレクトリには MPI プロセスのそれぞれについて、ランクにより命名されたサブ実験が含まれます。

option に使用できる値は次のとおりです。

デフォルトでは、MPI 実験の収集は無効になっています。MPI 実験の収集が有効な場合、-m オプションのデフォルト設定は on に変更されます。

collect コマンドをオプションなしで入力するか、-M オプションで認識されないバージョンを指定すると、MPI のサポートされているバージョンが表示されます。

-m option

MPI トレースデータを収集します。option に使用できる値は次のとおりです。

MPI トレースは、デフォルトで無効です。ただし -M オプションが有効な場合は、デフォルトで有効になります。通常、MPI 実験は -M オプションで収集され、MPI トレースのユーザー制御は不要です。MPI 実験の収集を行うが、MPI トレースデータは収集しない場合、明示的なオプションの -M MPI-version -m off を使用します。

呼び出しがトレースされる MPI 関数とトレースデータをもとに計算されるメトリックスの詳細については、「MPI トレースデータ」を参照してください。

-S option

標本パケットを定期的に記録します。option に使用できる値は次のとおりです。

デフォルトでは、1 秒間隔による定期的標本収集が有効になります。

-c option

カウントデータを記録します (Solaris システムのみ)。

注 –

この機能を使用するには、Add-on Cool Tools for OpenSPARC に含まれているバイナリインタフェースツール (Binary Interface Tool、BIT) をインストールする必要があります。このツールは、http://cooltools.sunsource.net/ からダウンロードできます。BIT は、Solaris バイナリのパフォーマンスやテストスイートカバレージの測定用ツールです。

option には次のいずれかの値を指定できます。

デフォルトでは、カウントデータの収集を無効にします。ほかの種類のデータについて、カウントデータを収集することはできません。

-I directory

bit 計測のディレクトリを指定します。このオプションは Solaris システムでのみ使用可能で、-c オプションも同時に指定されている場合のみ意味を持ちます。

-N library_name

bit() 計測から除外するライブラリを指定します。ここで指定したものは、ライブラリが実行可能ファイルにリンクされているか、dlopen() によって読み込まれるかにかかわらず、除外されます。このオプションは Solaris システムでのみ使用可能で、-c オプションも同時に指定されている場合のみ意味を持ちます。-N オプションは複数指定できます。

-r option

スレッドアナライザ用に、データ競合検出またはデッドロック検出のデータを収集します。次のいずれかの値を指定できます。

collect -r コマンドとスレッドアナライザについての詳細は、『Oracle Solaris Studio 12.2: スレッドアナライザユーザーズガイド』および tha (1) のマニュアルページを参照してください。

実験制御オプション

これらのオプションは、実験データの収集方法を制御します。

-F option

派生プロセスのデータを記録するかどうかを制御します。option に使用できる値は次のとおりです。

デフォルトでは、-F on オプションが設定されるので、コレクタは、fork(2)、fork1(2)、fork(3F)、vfork(2)、および exec(2) 関数とそのバリアントの呼び出しによって作成されたプロセスを追跡します。vfork への呼び出しは、内部で fork1 への呼び出しに置換されます。

MPI 実験では、デフォルトで派生も追跡されます。

-F all オプションを指定すると、コレクタは、system(3C)、system(3F)、sh(3F)、posix_spawn(3p)、posix_spawnp(3p)、および popen(3C)、および同様の関数の呼び出しによって作成されたものを含むすべての派生プロセス、そして関係する派生プロセスを追跡します。

-F '= regexp ' オプションを指定すると、コレクタはすべての派生プロセスを追跡します。派生名またはサブ実験名が指定の正規表現と一致する場合、コレクタはサブ実験を作成します。正規表現については、regexp(5) のマニュアルページを参照してください。

派生プロセスのデータを収集するとき、コレクタは、派生プロセスごとに新しい実験を親の実験内に 1 つ開きます。これらの新しい実験は、次のように、下線、文字、および数字を実験接尾辞に追加することで命名されます。

たとえば初期プロセスの実験名が test.1.er の場合、3 回目の fork の呼び出しで作成された子プロセスの実験は test.1.er/_f3.er となります。この子プロセスが新しいイメージを実行した場合、対応する実験名は test.1.er/_f3_x1.er となります。この子プロセスが popen 呼び出しを使用して別のプロセスを作成した場合、実験名は test.1.er/_f3_x1_c1.er となります。

アナライザと er_print ユーティリティーは、親実験が読み込まれると、自動的に派生プロセスの実験を読み込み、データ画面に派生を表示します。

表示するデータをコマンド行から選択するには、er_print か analyzer にパス名を明示的に指定します。指定するパスには、親の実験名と、親ディレクトリ内の派生実験名を含める必要があります。

たとえば、test.1.er 実験の 3 回目の fork のデータを表示する場合は、次のように指定します。

er_print test.1.er/_f3.er

analyzer test.1.er/_f3.er

もう一つの方法として、関心のある派生の実験の明示的な名前を入れた実験グループファイルを用意する方法もあります。

アナライザで派生プロセスを調べるには、親の実験を読み込んで、「表示」メニューから「データをフィルタ」を選択します。実験のリストは、親の実験のみが選択されて表示されます。これを選択解除し、対象とする派生実験を選択します。

注 –

派生プロセスが追跡されている間に親プロセスが終了した場合、まだ実行している派生のデータ収集は継続されます。それに従って親の実験ディレクトリは拡大を続けます。

また、スクリプトのデータを収集して、スクリプトの派生プロセスを追跡することもできます。詳細は、「スクリプトからのデータの収集」を参照してください。

-j option

ターゲットプログラムが JVM の場合に Java プロファイルを有効にします。option に使用できる値は次のとおりです。

-j オプションは、.class ファイルまたは .jar ファイルについてのデータを収集する場合は必要ありません。ただし、java 実行可能ファイルへのパスが JDK_HOME 環境変数または JAVA_PATH 環境変数に入っている必要があります。それから collect コマンド行でターゲットの program を .class ファイルまたは .jar ファイルとして指定します。拡張子は付けても付けなくてもかまいません。

JDK_HOME または JAVA_PATH 環境変数で java 実行可能ファイルのパスを定義できない場合や、Java HotSpot 仮想マシンによってコンパイルされたメソッドの認識を無効にしたい場合は、-j オプションを使用できます。このオプションを使用する場合、collect コマンド行で指定する program は Java 仮想マシンで、JDK 6、Update 18 またはそれ以降の必要があります。collect コマンドは、program が JVM で、かつ ELF 実行可能ファイルであることを検証し、そうでない場合は collect コマンドがエラーメッセージを出力します。

64 ビット JVM を使用してデータを収集する場合、32 ビット JVM 用の java コマンドに -d64 オプションを使用しないでください。これを使用すると、データは収集されません。その代わりに、collect コマンドの program 引数、あるいは JDK_HOME または JAVA_PATH 環境変数に、64 ビット JVM へのパスを指定する必要があります。

-J java_argument

プロファイルで使用するために JVM へ渡される追加引数を指定します。-J オプションを指定し、Java プロファイルを指定しない場合、エラーが生成され、実験は実行されません。java_argument に複数の引数が含まれる場合、全体を引用符でくくる必要があります。この引数は、空白またはタブで区切られた一連のトークンで構成される必要があります。各トークンは、別々の引数として JVM へ渡されます。JVM へのほとんどの引数は、「-」文字で始まる必要があります。

-l signal

signal という名前のシグナルがプロセスへ送信されたときに、標本パケットを記録します。

シグナルは、完全なシグナル名、先頭文字 SIG を省いたシグナル名、またはシグナル番号のいずれの形式でも指定できます。ただし、プログラムが使用するシグナル、または実行を終了するシグナルは指定しないでください。推奨するシグナルは SIGUSR1 および SIGUSR2 です。 SIGPROF は、時間プロファイリングが指定されている場合でも使用できます。シグナルは、kill コマンドを使用してプロセスに送信できます。

-l および -y の両方のオプションを使用する場合は、それぞれのオプションに異なるシグナルを使用する必要があります。

プログラムに独自のシグナルハンドラがあるときにこのオプションを使用する場合は、-l で指定するシグナルが、阻止されたり無視されたりすることなく、確実にコレクタのシグナルハンドラに渡されるようにする必要があります。

シグナルについては、signal(3HEAD) のマニュアルページを参照してください。

-t duration

データ収集の時間範囲を指定します。

duration は単独の数値として指定でき、オプションとして m または s 接尾辞を付け、実験終了までの時間が分単位か秒単位かを示すこともできます。 デフォルトでは、所要時間は秒です。所要時間はハイフンで区切られた 2 つの数で指定することもできます。これは、1 つ目の時間が経過するまでデータ収集を停止し、そして、データ収集を始める時間を示しています。2 つ目の時間が経過すると、データ収集が終了されます。2 つ目の時間がゼロの場合、初めてプログラムが停止したあと、そのプログラムの実行の終わりまで、データの収集が実行されます。実験が終了しても、ターゲットプロセスは最後まで実行できます。

-x

デバッガがプロセスに接続できるよう、exec システムコールの終了時にターゲットプロセスを停止したままにします。dbx をプロセスに接続した場合は、dbx コマンドの ignore PROF と ignore EMT を使用して、収集シグナルが確実に collect コマンドに渡されるようにします。

-y signal[ ,r]

signal という名前のシグナルで、データの記録を制御します。このシグナルがプロセスに送信されると、一時停止状態 (データは記録されない) と記録状態 (データは記録される) が切り替わります。ただし、このスイッチの状態に関係なく、標本ポイントは常に記録されます。

シグナルは、完全なシグナル名、先頭文字 SIG を省いたシグナル名、またはシグナル番号のいずれの形式でも指定できます。ただし、プログラムが使用するシグナル、または実行を終了するシグナルは指定しないでください。推奨するシグナルは SIGUSR1 および SIGUSR2 です。 SIGPROF は、時間プロファイリングが指定されている場合でも使用できます。シグナルは、kill コマンドを使用してプロセスに送信できます。

-l および -y の両方のオプションを使用する場合は、それぞれのオプションに異なるシグナルを使用する必要があります。

-y オプションに r 引数 (省略可能) を指定した場合、コレクタは記録状態で起動します。-y オプションが使用されていない場合、コレクタは記録状態で起動します。

プログラムに独自のシグナルハンドラがあるときにこのオプションを使用する場合は、-y で指定するシグナルが、阻止されたり、無視されたりすることなく、確実にコレクタのシグナルハンドラに渡されるようにする必要があります。

シグナルについては、signal(3HEAD) のマニュアルページを参照してください。

出力オプション

これらのオプションは、コレクタによって生成される実験を制御します。

-o experiment_name

記録する実験の名前として experiment_name を使用します。experiment_name 文字列は文字列「.er」で終わる必要があり、そうでない場合、collect ユーティリティーはエラーメッセージを出力して終了します。

-o オプションを指定しない場合、実験名を「stem.n.er」(stem は文字列、n は数値) の形式で指定します。-g オプションでグループ名を指定した場合、stem を「.erg」接尾辞なしのグループ名に設定します。グループ名を指定していない場合、stem を文字列「test」に設定します。

collect コマンドを、MPI ジョブの実行に使用されるコマンドの 1 つ、たとえば mpirun から起動し、-M MPI-version オプションおよび -o オプションを指定しない場合、そのプロセスの MPI ランクを定義するために使用された環境変数から、名前に使用されている n の値を使用します。それ以外の場合、現在使用されている最も大きい整数値に 1 を加えた値を n に設定します。

名前が「stem.n.er」の形式で指定されておらず、与えられた名前がすでに使用されている場合、エラーメッセージが表示され、実験は実行されません。名前が「stem.n .er」の形式で、与えられた名前がすでに使用されている場合、現在使用されている最も大きい数値より 1 大きい n の値に対応する名前で、実験が記録されます。名前が変更された場合、警告が表示されます。

-d directory-name

directory-name というディレクトリに実験を格納します。このオプションは個別の実験にのみ適用され、実験グループには適用されません。ディレクトリが存在しない場合、collect ユーティリティーはエラーメッセージを出力して終了します。-g オプションでグループが指定されている場合、グループファイルも directory-name へ書き込まれます。

データ収集をできるだけ軽くするには、レコードデータをローカルファイルに記録し、-d オプションを使用してデータ格納ディレクトリを指定するのが最適です。ただし、クラスタ上の MPI 実験では、すべてのプロセスから、記録されたすべてのデータが親の実験に書き込まれるため、親の実験がどのプロセスからでも同じパスに存在する必要があります。

待ち時間の長いファイルシステムに書き込まれる実験は特に問題が発生しやすく、標本データが収集される場合 (デフォルトの -S on オプション) には特に、非常に低速になることがあります。待ち時間の長い接続を経由して記録を行う必要がある場合には、標本データを無効にしてください。

-g group-name

実験を group-name という実験グループに含めます。group-name の末尾が .erg でない場合、collect ユーティリティーはエラーメッセージを出力して終了します。グループが存在する場合は、そのグループに実験が追加されます。group-name が絶対パスでない場合、-d でディレクトリを指定されていれば、実験グループがディレクトリ directory-name に、それ以外の場合は現在のディレクトリに格納されます。

-A option

ターゲットプロセスで使用されるロードオブジェクトを、記録済み実験に保管またはコピーするかどうかを管理します。option に使用できる値は次のとおりです。

実験データが記録されたマシンとは異なるマシンに実験データをコピーするか、異なるマシンから実験データを読み取る場合は、 - A copy を指定します。このオプションを使用しても、ソースファイルまたはオブジェクトファイル (.o) は実験にコピーされません。これらのファイルが、実験の検査に使用するマシンからアクセス可能で、変更されていないことを確認してください。

-L size

記録するプロファイルデータの量を sizeM バイトに制限します。この制限は、時間ベースのプロファイルデータ、ハードウェアカウンタオーバーフローのプロファイルデータ、および同期待ちのトレースデータの合計に適用されますが、標本ポイントには適用されません。この制限値は概数にすぎないので、この値を超えることは可能です。

制限に達すると、それ以上のプロファイルデータは記録されませんが、ターゲットプロセスが終了するまで実験はオープン状態となります。定期的な標本収集が有効である場合、標本ポイントの書き込みが継続されます。

約 2G バイトの制限を付けるには、たとえば、-L 2000 を指定します。指定するサイズは、ゼロより大きい必要があります。

デフォルトでは、記録されるデータサイズに制限はありません。

-O file

collect 自体の全出力を指定された file に付加しますが、生成されたターゲットからの出力はリダイレクトしません。ファイルが /dev/null に設定されている場合は、エラーメッセージを含む collect の全出力が抑制されます。

その他のオプション

これらの collect コマンドオプションはさまざまな目的で使用されます。

-P process_id

dbx が指定された process_id のプロセスに接続し、データを収集してから、スクリプト上で dbx を起動するためのスクリプトを作成します。プロファイルデータのみを指定でき、トレースデータは指定できません。時間指定の実行 (-t オプション) はサポートされません。

-C コメント

実験の notes ファイルにコメントを追加します。最大 10 個の -C オプションを指定できます。notes ファイルの内容は、実験のヘッダーの先頭に付加されます。

-n

ターゲットを実行しませんが、ターゲットが実行されれば生成されたはずの実験の詳細を出力します。このオプションは「ドライラン」オプションです。

-R

パフォーマンスアナライザの Readme のテキストバージョンを端末ウィンドウに表示します。readme が見つからない場合は、警告が出力されます。これ以降に指定した引数は検査されず、これ以外の処理は行われません。

-V

collect コマンドの現在のバージョンを表示します。これ以降に指定した引数は検査されず、これ以外の処理は行われません。

-v

collect コマンドの現在のバージョンと、実行中の実験に関する詳細情報を表示します。

collect ユーティリティーによる動作中のプロセスからのデータの収集

Solaris OS の場合のみ、collect ユーティリティーで -P pid オプションを使用して、指定された PID のプロセスに接続し、そのプロセスのデータを収集できます。collect コマンドのそのほかのオプションは dbx 用のスクリプトに変換され、そのスクリプトを起動してデータが収集されます。時間ベースのプロファイルデータ (-p オプション) とハードウェアカウンタオーバーフローのプロファイルデータ (-h オプション) だけを収集できます。トレースデータはサポートされていません。

-p オプションを明示的に指定せずに -h オプションを使用すると、時間ベースのプロファイルが無効となります。ハードウェアカウンタデータと時間ベースデータの両方を収集するには、-h オプションと -p オプションの両方を指定する必要があります。

Procedurecollect ユーティリティーを使用して動作中のプロセスからデータを収集する

  1. プログラムのプロセス ID (PID) の判定

    コマンド行からプログラムを起動していて、バックグラウンドで実行している場合は、シェルによってその PID が標準出力に出力されます。それ以外の場合、次のコマンドを入力してプログラムの PID を判定できます。


    % ps -ef | grep program-name

  2. collect コマンドを使用してプロセスのデータの収集を有効にし、オプションのパラメータを適宜設定します。


    % collect -P pid collect-options

    コレクタのオプションについては、「データ収集オプション」を参照してください。時間ベースのプロファイルについては、「-p option」 を参照してください。ハードウェアカウンタオーバーフローのプロファイルについては、-h optionを参照してください。