8.4　userprf.cfg

ユーザー拡張性能解析トレースで使用するユーザー拡張性能解析トレース設定ファイルのことです。

説明

ユーザー拡張性能解析トレースのトレース対象メソッドの情報は、ユーザー拡張性能解析トレース設定ファイルを使って設定します。

書式

指定形式,識別ID,サブクラスフラグ[,[イベントID][,[トレース取得レベル]]]
[#コメント]

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

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

記述項目	内容
`指定形式`	トレース対象メソッドを指定します。 `指定形式`は次のどれかの形式で指定します。メソッド名と引数の型が一致するメソッドをトレースの対象とする場合 `パッケージ名.クラス名.メソッド名(メソッドの引数の型名)` メソッド名が一致するメソッドをトレースの対象とする場合 `パッケージ名.クラス名.メソッド名()` クラス名が一致するすべてのメソッドをトレースの対象とする場合 `パッケージ名.クラス名` パッケージ名が一致するすべてのメソッドをトレースの対象とする場合 `パッケージ名.` 指定形式の項目について説明します。 `パッケージ名` トレース対象メソッドのクラスまたはインターフェースのパッケージ名を指定します。 `クラス名` トレース対象メソッドのクラス名またはインターフェース名を指定します。クラス名の代わりにインターフェース名を指定し、かつ、サブクラスフラグに`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が出力されます。
`コメント`	コメントは「`#`」で始まり、「`#`」から行末までの間の文字すべてをコメントとします。

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

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

ユーザー拡張性能解析トレース設定ファイルの記述に誤りがある場合、誤りの内容を示すメッセージが出力されます。また、各項目に無効な値を記述した場合、誤りの内容を示すメッセージが出力され、その行の設定は無効になります。

ユーザー拡張性能解析トレースでユーザー拡張性能解析トレース設定ファイルの読み込み時に出力されるログ情報を次の表に示します。

出力形式	出力内容	説明
`[UPR^※1]<DATE>Setting file not found.<file=FILEPATH>`	`DATE`^※2 ユーザー拡張性能解析トレース設定ファイルの読み込みに失敗した日時。 `FILEPATH` 読み込みに失敗したユーザー拡張性能解析トレース設定ファイルの絶対パス。	デフォルト、または`jvm.userprf.File`プロパティーで指定したユーザー拡張性能解析トレース設定ファイルが存在しません。
`[UPR^※1]<DATE>Failed to open setting file.<file=FILEPATH>`	`DATE`^※2 ユーザー拡張性能解析トレース設定ファイルの読み込みに失敗した日時。 `FILEPATH` 読み込みに失敗したユーザー拡張性能解析トレース設定ファイルの絶対パス。	ユーザー拡張性能解析トレース設定ファイルのオープンまたは読み込みができません。
`[UPR^※1]<DATE>Failed to parse setting file.<file=FILEPATH><line=LINE>`	`DATE`^※2 ユーザー拡張性能解析トレース設定ファイルの誤りを検出した日時。 `FILEPATH` ユーザー拡張性能解析トレース設定ファイルの絶対パス。 `LINE` ユーザー拡張性能解析トレース設定ファイルの行番号。	ユーザー拡張性能解析トレース設定ファイルの内容に記述フォーマット上の誤りがあります。
`[UPR^※1]<DATE>Event ID is invalid value.<file=FILEPATH><eventID=EventID>`	`DATE`^※2 ユーザー拡張性能解析トレース設定ファイルの誤りを検出した日時。 `FILEPATH` ユーザー拡張性能解析トレース設定ファイルの絶対パス。 `EventID` ユーザー拡張性能解析トレース設定ファイルに指定したイベントID。	ユーザー拡張性能解析トレース設定ファイルのイベントIDが有効な値の範囲外です。
`[UPR^※1]<DATE>No valid settings in setting file.<file=FILEPATH>`	`DATE`^※2 ユーザー拡張性能解析トレース設定ファイルに有効な設定がないことを検出した日時。 `FILEPATH` ユーザー拡張性能解析トレース設定ファイルの絶対パス。	ユーザー拡張性能解析トレース設定ファイルに有効な設定がありません。
`[UPR^※1]<DATE>User Extended PRF started successfully.<file=FILEPATH>`	`DATE`^※2 ユーザー拡張性能解析トレース設定ファイルの読み込みに成功した日時。 `FILEPATH` 有効に読み込みが行われたユーザー拡張性能解析トレース設定ファイルの絶対パス。	ユーザー拡張性能解析トレース設定ファイルが正常に読み込まれ、ユーザー拡張性能解析トレースが有効になりました。

注※1: ユーザー拡張性能解析トレースが出力したログであることを示す識別子です。
注※2: 拡張verbosegc情報と同じ形式で出力します。

ユーザー拡張性能解析トレースでは、JavaVM内のクラスやApplication Server内のクラスはトレース対象のメソッドに指定できません。次のパッケージが該当します。
- 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()

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

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

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

注※1: クラスの宣言時にimplementsを使用して指定したインターフェースを実装しているクラスです。
注※2: 指定したインターフェースを直接実装しているクラスのサブクラス、または指定したインターフェースを継承しているインターフェースを直接実装しているクラスです。

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

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,,

格納先

JDKのインストールディレクトリー/usrconf/userprf.cfg

記述例

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

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

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

サブクラスフラグが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」が出力されます。

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

サブクラスフラグが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)

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

サブクラスフラグが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」が出力されます。

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

重要

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

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

サブクラスフラグがfalseの場合

com.sample.*,6000,false

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

トレース対象のメソッドを次に示します。

ClassA、ClassB、ClassC、ClassDのすべてのメソッド

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

サブクラスフラグがtrueの場合

com.sample.*,6000,true

サブクラスフラグがtrueの場合、記述したパッケージ（com.sample）にあるすべてのクラスのすべてのメソッドと、そのメソッドをオーバーライドしているメソッドのすべてがトレース対象となります。

トレース対象のメソッドを次に示します。

ClassA、ClassB、ClassC、ClassDのすべてのメソッドと、そのメソッドをオーバーライドしているすべてのメソッド

注意事項

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

ページの先頭へ

8.4 userprf.cfg

8.4　userprf.cfg