7.5.3　ユーザ拡張性能解析トレースのトレース対象メソッドの設定

ユーザ拡張性能解析トレースのトレース対象メソッドの設定は，ユーザ拡張性能解析トレース設定ファイルを使って設定します。ユーザ拡張性能解析トレース設定ファイルの内容は次のどれかに記述できます。

簡易構築定義ファイル
運用管理ポータルの［起動パラメタの設定］画面（論理J2EEサーバの定義）
デフォルトのファイル，またはユーザが指定した任意のファイル（jvm.userprf.Fileプロパティで指定したファイル）

〈この項の構成〉

(1)　記述形式
(2)　記述項目
(3)　記述規則
(4)　ユーザ拡張性能解析トレース設定ファイルの記述例
(5)　ユーザ拡張性能解析トレース設定ファイル作成の注意事項

(1)　記述形式

ユーザ拡張性能解析トレース設定ファイルの記述形式を次に示します。

<指定形式>^※,<識別ID>,<サブクラスフラグ>［,［<イベントID>］［,［<トレース取得レベル>］］］［#コメント］

注1

［］で囲んだ項目は省略できます。

注2

クラス名およびパッケージ名が一致するすべてのメソッドを対象とする場合，jvm.userprf.ExtendedSettingプロパティの値をtrueに設定してください。

注※

<指定形式>は次のどれかの形式で指定します。

メソッド名と引数の型が一致するメソッドをトレースの対象とする場合

<パッケージ名>.<クラス名>.<メソッド名>(メソッドの引数の型名)
メソッド名が一致するメソッドをトレースの対象とする場合

<パッケージ名>.<クラス名>.<メソッド名>(*)
クラス名が一致するすべてのメソッドをトレースの対象とする場合

<パッケージ名>.<クラス名>
パッケージ名が一致するすべてのメソッドをトレースの対象とする場合

<パッケージ名>.*

記述形式の例

com.sample.Test.method(),TEST1,false,0xae02,A
com.sample.Test.method(),TEST1,false,0xae02
com.sample.Test.method(),TEST1,false,0xae02,
com.sample.Test.method(),TEST1,false,,A
com.sample.Test.method(),TEST1,false
com.sample.Test.method(),TEST1,false,
com.sample.Test.method(),TEST1,false,,

ページの先頭へ

(2)　記述項目

ユーザ拡張性能解析トレース設定ファイルの記述項目を次に示します。

指定形式

トレース対象メソッドを指定します。

パッケージ名: トレース対象メソッドのクラスまたはインタフェースのパッケージ名を指定します。
クラス名: トレース対象メソッドのクラス名またはインタフェース名を指定します。クラス名の代わりにインタフェース名を指定し，かつ，サブクラスフラグにtrueを指定した場合，そのインタフェースを実装しているメソッドがトレース対象となります。
メソッド名: トレース対象メソッドの名前を指定します。
メソッドの引数の型名: トレース対象メソッドの引数の型を完全修飾名で指定します。

識別ID

トレース対象メソッドを識別するための文字列を指定します。

使用できる文字はASCII文字で0x21（!）から0x7e（~）までです。ただし，0x22（"），0x23（#），および0x2c（,）は指定できません。

識別IDはPRFトレースファイルに出力されます。なお，PRFトレースファイルに出力される文字数は32文字までです。33文字目以降は省略されて，33文字目に*が出力されます。

注意事項: トレース対象メソッドが定義されているクラスにサブクラスが存在し，そのサブクラスでトレース対象メソッドがオーバーライドされていない場合，スーパークラスのトレース対象メソッドに対して指定された識別IDが出力されます。

サブクラスフラグ

指定したメソッドのクラスまたはインタフェースと継承関係にあるクラスのメソッドをトレース対象に含めるかどうかをtrueまたはfalseで指定します。

trueを指定した場合，指定したメソッドと，それをオーバーライドしているメソッドがトレース対象となります。
falseを指定した場合，指定したメソッドだけがトレース対象となり，指定したメソッドをオーバーライドしているメソッドはトレース対象となりません。

イベントID

トレース情報を取得するポイント（トレース取得ポイント）を16進数（0xae02〜0xae7eおよび0xc000〜0xcffe）の値で指定します。デフォルト値は0xae00です。

メソッドの入口で出力されるトレース情報にはこの値が出力され，メソッドの出口で出力されるトレース情報にはこの値＋1が出力されます。

トレース取得レベル

トレース対象メソッドのトレース取得レベルに，A，B，C，またはそれぞれの小文字のどれかを指定します。デフォルト値はAです。

A：標準レベル
B：詳細レベル
C：保守レベル

参考: トレース取得レベルはcprflevelコマンドのPRFトレース取得レベルと同じです。トレース対象メソッドはすべてJava VMレイヤのレベルを参照します。PRF取得レベルとレイヤについては，マニュアル「アプリケーションサーバリファレンスコマンド編」の「cprflevel（PRFトレース取得レベルの表示と変更）」を参照してください。

コメント

コメントは「#」で始まり，「#」から行末までの間の文字すべてをコメントとします。

ページの先頭へ

(3)　記述規則

ユーザ拡張性能解析トレース設定ファイルの記述規則を次に示します。

記述にはシングルバイト文字だけが使用できます。
空白文字は，半角スペース文字（「0x20」）またはタブ文字（「\t」もしくは「0x09」）となります。なお，ユーザ拡張性能解析トレース設定ファイルの読み込みでは空白文字は無視されます。
トレース対象メソッドは1行に一つずつ記述します。
1行に指定できる文字数は2,048文字までです。この文字数には空白やコメントを含みます。
行末は改行文字（「\n」もしくは「0x0A」）または復帰文字（「\r」もしくは「0x0D」）が1文字以上続いたものとなります。
ユーザ拡張性能解析トレース設定ファイルの記述に誤りがある場合，誤りの内容を示すメッセージが出力されます。また，各項目に無効な値を記述した場合，誤りの内容を示すメッセージが出力され，その行の設定は無効になります。

メッセージについては，「7.6　ユーザ拡張性能解析トレース実行時に出力されるログ情報」を参照してください。
ユーザ拡張性能解析トレースでは，JavaVM内のクラスやCosminexus内のクラスはトレース対象のメソッドに指定できません。次のパッケージが該当します。
- java以下
- javax以下
- com.hitachi以下
- JP.co.Hitachi以下
そのため，jvm.userprf.ExtendedSettingプロパティを指定して，パッケージ名指定をする場合は，アプリケーションのクラスだけが含まれるようにパッケージ名を記述してください。
次のメソッドはトレース対象のメソッドに指定できません。
- 存在しないパッケージ名，クラス名，およびメソッド名
- nativeメソッド
- abstractメソッド
- JavaVM内のクラス，およびそのクラスのメソッド
  
  （例）javaおよびjavaxで始まるパッケージのクラス
- -Xbootclasspathで指定したクラス，およびそのクラスのメソッド
- 製品内のクラス
次のメソッドは次の記述でトレース対象のメソッドに指定できます。
- コンストラクタは，クラス名と同じメソッド名，または<init>で指定できます。
  
  （例）MyMainクラスのコンストラクタの場合，次のように指定します。
  
  MyMain.MyMain()またはMyMain.<init>()
- コンストラクタではないクラス名と同じ名前のメソッドを指定した場合は，コンストラクタを指定しているのか，メソッドを指定しているのか判別できないためコンストラクタとメソッドがトレースの対象となります。
- 引数が可変長であるメソッドを指定する場合は，可変長の引数を配列として記述してください。
  
  （例）引数が可変長であるメソッドの指定
  
  正しい指定例：com.sample.Test.method(java.lang.String[])
  
  誤った指定例：com.sample.Test.method(java.lang.String...)
- ネストクラスは，「.」ではなく「$」で区切った名前を指定してください。
  
  （例）ネストクラスの指定
  
  正しい指定例：com.sample.Test$NestClass
  
  誤った指定例：com.sample.Test.NestClass
- ジェネリクスではなく，パラメタ化されていないクラス名（raw型）であれば指定できます。
  
  （例）ジェネリクスではないクラスの指定
  
  正しい指定例：com.sample.Test.method()
  
  誤った指定例：com.sample.Test<java.lang.String,java.lang.Object>.method()

<指定形式>の<クラス名>にクラス名を指定した場合とインタフェース名を指定した場合ではトレース対象メソッドが異なります。

クラスまたはインタフェースの指定によるトレース対象メソッドを次の表に示します。

表7‒8　クラスまたはインタフェースの指定によるトレース対象メソッド
クラスまたはインタフェース	トレース対象メソッド
クラスまたはインタフェース	サブクラスフラグにfalseを指定した場合	サブクラスフラグにtrueを指定した場合
クラス	指定したクラスのメソッド	指定したクラスのメソッドと，そのメソッドをオーバーライドしているメソッド
インタフェース	なし	指定したインタフェースを直接実装しているクラス^※1と間接実装しているクラス^※2のメソッド，およびそのメソッドをオーバーライドしているメソッド

注※1　クラスの宣言時にimplementsを使用して指定したインタフェースを実装しているクラスです。

注※2　指定したインタフェースを直接実装しているクラスのサブクラス，または指定したインタフェースを継承しているインタフェースを直接実装しているクラスです。

ページの先頭へ

(4)　ユーザ拡張性能解析トレース設定ファイルの記述例

ここでは，トレース対象メソッドごとに，ユーザ拡張性能解析トレース設定ファイルの記述例について説明します。

なお，ここで説明する記述例は，パッケージ名が「com.sample」で，次の図に示すクラス構造を持っているアプリケーションとします。

図7‒8　アプリケーションのクラス構造の例

(a)　メソッド名と引数の型が一致するメソッドをトレースの対象とする場合

メソッド名と引数の型が一致するメソッドをトレースの対象とする場合のユーザ拡張性能解析トレース設定ファイルの記述例を次に示します。

サブクラスフラグがfalseの場合
```
com.sample.ClassA.methodA1(java.lang.String,java.lang.Object),1000,false
```
サブクラスフラグがfalseの場合，記述したメソッド名と引数の型が一致するメソッドがトレース対象となります。

トレース対象のメソッド

・ClassAクラスのmethodA1(String,Object)

トレース対象メソッドに対してイベントIDの設定を省略しているため，トレース対象となったメソッドが呼び出されると，イベントIDとしてメソッドの入口で0xae00，メソッドの出口で0xae01のデフォルト値が出力されます。また，識別IDに「1000」を設定しているため，識別IDとして「1000」が出力されます。
サブクラスフラグがtrueの場合
```
com.sample.ClassA.methodA2(),2000,true
```
サブクラスフラグがtureの場合，メソッド名と引数の型が記述と一致するメソッドに加えて，記述したメソッドをオーバーライドしているメソッドもトレース対象となります。

トレース対象のメソッド

・ClassAクラスのmethodA2()

・ClassAクラスのmethodA2()をオーバーライドしているClassBクラスのmethodA2()

トレース対象メソッドに対してイベントIDの設定を省略しているため，トレース対象となったメソッドが呼び出されると，イベントIDとしてメソッドの入口で0xae00，メソッドの出口で0xae01のデフォルト値が出力されます。また，識別IDに「2000」を設定しているため，トレース対象のすべてのメソッドに識別IDとして「2000」が出力されます。

(b)　メソッド名が一致するメソッドをトレースの対象とする場合

メソッド名が一致するメソッドをトレースの対象とする場合のユーザ拡張性能解析トレース設定ファイルの記述例を次に示します。

サブクラスフラグがfalseの場合
```
com.sample.ClassA.methodA1(*),methodA1,false,0xae30
```
サブクラスフラグがfalseの場合，記述したメソッド名と一致するメソッドのすべてがトレース対象となります。

トレース対象のメソッド

・ClassAクラスのmethodA1(String,Object)

・ClassAクラスのmethodA1(int)

トレース対象となったメソッドが呼び出されると，イベントIDとしてメソッドの入口で0xae30，メソッドの出口で0xae31が出力されます。また，トレース対象のすべてのメソッドに識別IDとして「methodA1」が出力されます。
サブクラスフラグがtrueの場合
```
com.sample.ClassA.methodA1(*),methodA1,true,0xae30
```
サブクラスフラグがtrueの場合，記述したメソッド名と一致するメソッドのすべてがトレース対象となります。また，記述したメソッドに加えて，記述したメソッドをオーバーライドしているメソッドもトレース対象となります。

トレース対象のメソッド

・ClassAクラスのmethodA1(String,Object)とmethodA1(int)

・ClassAクラスのmethodA1(String,Object)をオーバーライドしているClassBクラスのmethodA1(String,Object)

・ClassBクラスのmethodA1(String,Object)をオーバーライドしているClassCクラスのmethodA1(String,Object)

トレース対象となったメソッドが呼び出されると，イベントIDとしてメソッドの入口で0xae30，メソッドの出口で0xae31が出力されます。また，トレース対象のすべてのメソッドに識別IDとして「methodA1」が出力されます。

(c)　クラス名が一致するすべてのメソッドをトレースの対象とする場合

メソッドと引数を省略して，クラス名が一致するすべてのメソッドをトレースの対象とする場合のユーザ拡張性能解析トレース設定ファイルの記述例を次に示します。

サブクラスフラグがfalseの場合
```
com.sample.ClassA,TEST01,false
```
サブクラスフラグがfalseの場合，記述したクラス名（ClassAクラス）のすべてのメソッドがトレース対象となります。

トレース対象のメソッド

ClassAクラスのmethodA1(String,Object)，methodA1(int)，およびmethodA2()

トレース対象となったメソッドが呼び出されると，イベントIDが省略されているため，メソッド入口で0xae00，メソッド出口で0xae01が出力されます。また，これらすべてのメソッドに識別IDとして「TEST01」が出力されます。
サブクラスフラグがtrueの場合
```
com.sample.ClassB,TEST02,true
```
サブクラスフラグがtrueの場合，記述したクラス名（ClassBクラス）のすべてのメソッドと，そのメソッドをオーバーライドしているメソッドのすべてがトレース対象となります。

トレース対象のメソッド

・ClassBクラスのmethodA1(String,Object)

・ClassBクラスのmethodA2()

・ClassBクラスのmethodB1()

・ClassBクラスのmethodA1(String,Object)をオーバーライドしているClassCクラスのmethodA1(String,Object)

トレース対象となったメソッドが呼び出されると，イベントIDが省略されているため，メソッド入口で0xae00，メソッド出口で0xae01が出力されます。また，これらすべてのメソッドに識別IDとして「TEST02」が出力されます。

(d)　パッケージ名が一致するすべてのメソッドをトレースの対象とする場合

クラス名とメソッド名と引数を省略して，パッケージ名が一致するすべてのクラスのすべてのメソッドをトレースの対象とする場合のユーザ拡張性能解析トレース設定ファイルの記述例を次に示します。

注意事項

この指定ではサブパッケージも対象に含まれます。トレース対象となった場合，対象となったメソッドが呼び出されるとトレースが出力されます。

com.sampleパッケージにサブパッケージがある場合，そのサブパッケージのすべてのクラスのすべてのメソッドもトレース対象となります。

サブクラスフラグがfalseの場合
```
com.sample.*,6000,false
```
サブクラスフラグがfalseの場合，記述したパッケージ（com.sample）にあるすべてのクラスのすべてのメソッドがトレース対象となります。

トレース対象のメソッド

ClassA，ClassB，ClassC，ClassDのすべてのメソッドがトレース対象となります。

トレース対象となったメソッドが呼び出されると，イベントIDが省略されているため，メソッド入口で0xae00，メソッド出口で0xae01が出力されます。また，これらすべてのメソッドに識別IDとして「6000」が出力されます。
サブクラスフラグがtrueの場合
```
com.sample.*,6000,false
```
サブクラスフラグがtrueの場合，記述したパッケージ（com.sample）にあるすべてのクラスのすべてのメソッドと，そのメソッドをオーバーライドしているメソッドのすべてがトレース対象となります。

トレース対象のメソッド

ClassA，ClassB，ClassC，ClassDのすべてのメソッドと，そのメソッドをオーバーライドしているすべてのメソッドもトレース対象となります。

トレース対象となったメソッドが呼び出されると，イベントIDが省略されているため，メソッド入口で0xae00，メソッド出口で0xae01が出力されます。また，これらすべてのメソッドに識別IDとして「6001」が出力されます。

ページの先頭へ

(5)　ユーザ拡張性能解析トレース設定ファイル作成の注意事項

ユーザ拡張性能解析トレース設定ファイルを作成するときの注意事項を次に示します。

ユーザ拡張性能解析トレース設定ファイルで，同じメソッドに対して複数行で異なるイベントIDまたは識別IDを指定した場合，ユーザ拡張性能解析トレース設定ファイルの前方に記述された設定が優先されます。
ユーザ拡張性能解析トレース設定ファイルで，複数のメソッドを対象とする記述をした場合，対象となるすべてのメソッドが同一イベントIDまたは識別IDで出力されます。その場合，出力されるメソッド名が出力できる文字数を超えるとメソッドを特定できないことがあります。メソッドを一つに特定できるように記述してください。
トレース対象にインタフェースを指定した場合，サブクラスフラグにtrueを指定してください。インタフェースにはトレース対象となるメソッドが存在しないため，サブクラスフラグにfalseを指定するとトレース情報は出力されません。
複数のメソッドをユーザ拡張解析トレースの対象とする指定形式は，アプリケーションの動作を把握したい場合などに限り指定してください。

ユーザ拡張性能解析トレース設定ファイルの記述で，サブクラスフラグにtrueを指定した場合や，メソッド名が一致するメソッドをトレースの対象とする指定形式で指定した場合，ユーザが意図しない多くのメソッドがユーザ拡張性能解析トレースの対象となり，性能劣化要因の特定が困難になることがあります。性能劣化要因の特定のためには，ユーザ拡張性能解析トレース設定ファイルのサブクラスフラグにfalseを指定する，またはメソッド名と引数の型が一致するメソッドをトレースの対象とする指定形式で指定するなどで，ユーザ拡張性能解析トレースの対象を限定することを推奨します。

ページの先頭へ

7.5.3 ユーザ拡張性能解析トレースのトレース対象メソッドの設定

(1) 記述形式

(2) 記述項目

(3) 記述規則

(4) ユーザ拡張性能解析トレース設定ファイルの記述例

(a) メソッド名と引数の型が一致するメソッドをトレースの対象とする場合

(b) メソッド名が一致するメソッドをトレースの対象とする場合

(c) クラス名が一致するすべてのメソッドをトレースの対象とする場合

(d) パッケージ名が一致するすべてのメソッドをトレースの対象とする場合

(5) ユーザ拡張性能解析トレース設定ファイル作成の注意事項

7.5.3　ユーザ拡張性能解析トレースのトレース対象メソッドの設定

(1)　記述形式

(2)　記述項目

(3)　記述規則

(4)　ユーザ拡張性能解析トレース設定ファイルの記述例

(a)　メソッド名と引数の型が一致するメソッドをトレースの対象とする場合

(b)　メソッド名が一致するメソッドをトレースの対象とする場合

(c)　クラス名が一致するすべてのメソッドをトレースの対象とする場合

(d)　パッケージ名が一致するすべてのメソッドをトレースの対象とする場合

(5)　ユーザ拡張性能解析トレース設定ファイル作成の注意事項