ここでは、制御ファイルの作成方法を説明します。
制御ファイルは、メソッドトレース機能の動作を定義するためのファイルです。
制御ファイル名は、メソッドトレース機能を使用するJava VMの起動時に指定します。
トレース対象のメソッド名、トレース情報の出力形式、トレース情報の出力先、ファイルローテーションの動作などを定義できます。
■記述形式
制御ファイルは、以下の形式で記述します。
定義名=定義値 |
1行1項目で指定します。
コメントを記述する場合は、“#”以降に記述します。
定義名を重複して指定した場合は、最後に正しく指定した項目が有効になります。
ただし、重複指定可能な“traceMethod”および“not_traceMethod”を除きます。
1行の記述が“定義名=定義値”の形式になっていない場合、または、以下の“制御ファイルの定義項目”に記載されていない定義名を指定した場合、その行は無効となります。
定義値の指定に誤りがある場合の解釈は、定義項目によって異なります。詳細は、それぞれの定義項目を参照してください。
定義名および定義値に使用する文字列は、大文字と小文字は区別され、異なる文字として扱われます。
なお、メソッドトレース機能の格納先に、制御ファイルのサンプル(fjtrace.conf)がありますので、参考にしてください。
■定義項目の一覧
制御ファイルに定義できる項目を、次の表に示します。
定義名 | 説明 |
|---|---|
トレース対象のメソッドの指定に正規表現を用いるかを指定します。 | |
トレース対象のメソッドを指定します。 | |
非トレース対象のメソッドを指定します。 | |
動的に決定されるクラスパスを指定します。 | |
メソッドの引数および戻り値情報の出力形式を指定します。 | |
タイムスタンプ出力の有無を指定します。 | |
トレース情報を出力するファイル名を指定します。 | |
トレース情報出力ファイルを格納するディレクトリを指定します。 | |
トレース情報出力ファイルのローテーション数を指定します。 | |
トレース情報出力ファイルの最大サイズを指定します。 |
■定義項目の詳細
制御ファイルに定義する項目の詳細を説明します。
◆statementStyle
statementStyle=REGEX ｜ BASIC |
トレース対象のメソッドの指定に正規表現を使用するかを指定します。
以下のいずれかの定義値を指定します。
REGEX: 正規表現を使用する
BASIC: 正規表現を使用しない(省略値)
“REGEX”、“BASIC”以外の定義値を指定した場合、その行は無効となります。また、“statementStyle”の記述がない場合、“BASIC”が指定されたものと解釈します。
本指定に誤りがある場合は、制御ファイルの記述に誤りがあったことを通知するメッセージを標準出力（IJServerでは標準出力がロギングされるファイル）に出力します。
（“statementStyle”の記述が無い場合は、メッセージの出力は行われません。）
◆traceMethod
◆not_traceMethod
traceMethod=クラス名 メソッド名 [シグネチャ] |
not_traceMethod=クラス名 メソッド名 [シグネチャ] |
[ ]は省略可能です。
“traceMethod”は、トレース対象のメソッドを指定します。
“not_traceMethod”は、非トレース対象のメソッドを指定します。
“traceMethod”、“not_traceMethod”ともに複数指定できます。
“traceMethod”が1つも指定されていない場合は、トレースを行わずにアプリケーションを実行します。
“not_traceMethod”、“statementStyle=REGEX”が指定されている場合にのみ有効です。
（“statementStyle=BASIC”の場合、無効となります。）
クラス名、メソッド名、シグネチャはそれぞれ半角空白で区切ります。
“traceMethod”、“not_traceMethod”とも、“statementStyle”の指定に影響を受けます。
定義値の記述内容を下表に示します。
【statementStyle=REGEX指定の場合】
クラス名 | クラス名を指定します。パッケージ階層の区切りは'/'です。 例) javax/servlet/http/HttpServletRequest クラス名には、インターフェース名やスーパークラス名を指定することもできます。 正規表現を用いることで、“すべてのクラス”の指定ができます。
正規表現の詳細は、apacheの提供する、jakarta-regexp V1.2のorg.apache.regexp.REのAPI仕様を参照してください(※注)。 (※注)正規表現"[:graph:]"には既存のバグが存在するため正しく動作しません。 正規表現の構文が誤っていた場合、その行を無効とし、Warningメッセージ（FJTRACE:400）を標準出力（IJServerでは標準出力がロギングされるファイル）に出力します。 注）.*を用いた場合、実行性能が極度に劣化します。パッケージ名を指定するなど、部分的な総称となるように指定してください。 |
メソッド名 | メソッド名を指定します。 クラス名の指定に応じて、次の意味になります。 クラス名：実装したメソッド名
正規表現の詳細は、apacheの提供する、jakarta-regexp V1.2のorg.apache.regexp.REのAPI仕様を参照してください(※注)。 (※注)正規表現"[:graph:]"には既存のバグが存在するため正しく動作しません。 正規表現の構文が誤っていた場合、その行を無効とし、Warningメッセージ（FJTRACE:400）を標準出力（IJServerでは標準出力がロギングされるファイル）に出力します。 |
シグネチャ(省略可) | シグネチャを指定します。省略可能です。 指定するとクラス名、メソッド名で限定されたメソッドのうち、さらにシグネチャの一致する特定のメソッドを対象とします。たとえば、クラス内にメソッド名に一致するメソッドが複数存在する(オーバーロードメソッド)場合に、特定のメソッドにトレースを限定できます。 例1) 引数を持たず、戻り値がvoid型のメソッドの場合 例2) String型の配列とboolean型の2つ引数を持ち、戻り値がint型のメソッドの場合 |
【statementStyle=BASIC指定の場合】
クラス名 | クラス名を指定します。パッケージ階層の区切りは'.'です。 例) org.apache.catalina.connector.RequestFacade |
メソッド名 | メソッド名を指定します。指定には、次の2つの方法があります。
|
シグネチャ(省略可) | シグネチャを指定します。省略可能です。 指定するとクラス名、メソッド名で限定されたメソッドのうち、さらにシグネチャの一致する特定のメソッドを対象とします。たとえば、クラス内にメソッド名に一致するメソッドが複数存在する(オーバーロードメソッド)場合に、特定のメソッドにトレースを限定できます。 例1) 引数を持たず、戻り値がvoid型のメソッドの場合 例2) String型の配列とboolean型の2つ引数を持ち、戻り値がint型のメソッドの場合 |
型 | シグネチャの文字 |
|---|---|
boolean | Z |
byte | B |
char | C |
short | S |
int | I |
long | J |
float | F |
double | D |
void | V(戻り値の場合のみ) |
クラス(注) | Lクラス名; |
配列 | [ |
注) クラスは、'L'で始まり、';'で終わります。
クラス名は、パッケージ名を含む完全なクラス名を使用します。この時の区切り文字は'/'です。
例) Stringクラスの場合
"Ljava/lang/String;"
メソッドのシグネチャを確認するには、JDKに含まれるjavapコマンドに-sオプションを指定します。
javap -s クラス名 |
以下のパッケージ配下のクラスは、メソッドトレースの指定はできません。指定しても、無効となります。
com.fujitsu.jvm.mt
org.apache.bcel
org.apache.regexp
また、“トレース不可のクラス”に示すクラスについては、トレース情報を出力できません。
mainメソッドを含むクラスに実装されたメソッドがトレース対象となった場合、クラスをロードするタイミングでメソッドトレースの使用するオブジェクトと競合を起こし、まれにデッドロックが発生することがあります。
その場合、以下の指定を追加することで回避できることがあります。
statementStyle=REGEX指定の場合、以下の指定を追加してください。
traceMethod=java/net/URLClassLoader.* .*
statementStyle=BASIC指定の場合、以下の指定を追加してください。
traceMethod=java.net.URLClassLoader$1 *
◆classPath
classPath=動的設定されるクラスパス |
メソッドトレース対象のアプリケーションが動的に決定するクラスパス（環境変数CLASSPATHに記述せず、アプリケーション内で設定するクラスパス）を持つ場合に指定します。
クラスパスの設定は、メソッドトレース機能が動作するOS環境の決まりに従います（環境変数CLASSPATHと同様の記述を行います）。
“classPath”の指定がない場合、環境変数CLASSPATHに指定されたパスが使われます。
“classPath”の指定がある場合、指定したパスの後ろに環境変数CLASSPATHのパスをつなげたものが使われます。
“classPath”は、“statementStyle=REGEX”が指定されている場合にのみ有効です。
（“statementStyle=BASIC”の場合、無効となります。）
注意
複数のクラスパスを記述する必要がある場合、区切り文字“;”でつないで1行で制御ファイルに記載します。改行はしないでください。
classPath=C:\Interstage\lib\isjmxrt.jar;C:\Interstage\lib\isjmxcommon.jar;[…略]
上記は、Windows(R)上で、製品をC:\Interstageにインストールした場合です。
SolarisおよびLinuxの場合は、区切り文字はコロン(:)となります。
◆valueLevel
valueLevel=full | addHex | none |
メソッドの引数および戻り値の出力形式を指定します。
以下のいずれかの定義値を指定します。
full | : | 引数および戻り値の情報を出力する(省略値) |
addHex | : | “full”の機能に加え、文字列の16進数表示を出力する |
none | : | 引数および戻り値の情報を出力しない |
“full”、“addHex”、“none”以外の定義値を指定した場合、その行は無効となります。また、“valueLevel”の記述がない場合、“full”が指定されたものと解釈します。
引数、戻り値の出力形式の詳細は、“A.1.6 トレース情報出力の形式”を参照してください。
◆timeStamp
timeStamp=true | false |
タイムスタンプ出力の有効/無効を指定します。
以下のいずれかの定義値を指定します。
true | : | タイムスタンプを出力する |
false | : | タイムスタンプを出力しない(省略値) |
“true”、“false”以外の定義値を指定した場合、その行を無効とします。また、“timeStamp”の記述がない場合、“false”が指定されたものと解釈します。
注意
“timeStamp=true”を指定した場合、メソッドトレース機能は日付と時刻の表示のため、以下のクラスを使用しています。
java.util.Calendar
java.text.SimpleDateFormat
これらのクラスおよび関連するクラス（※注）を直接または間接的に、複数のスレッド間で同時に使用するアプリケーションでは、デッドロックを引き起こす場合があります。
その場合、本指定をfalseに変更するか、または、トレースを行わないクラスとして“not_traceMethod”で指定してください。
※注：たとえば、以下のクラスです。
java.util.GregorianCalendar
java.util.SimpleTimeZone
java.util.TimeZone
◆traceFile
traceFile=トレース情報出力ファイル名 |
トレース情報を出力するファイルのフルパスを指定します。
パス中のディレクトリは存在している必要があります。
パス中のディレクトリが存在しない場合、この行は無効となります。
また、同名のファイルがすでに存在した場合、上書きされます。
メソッドトレース機能を一般ユーザで起動した場合には、その一般ユーザに対する書き込み権が付与されているファイルを指定します。
“traceDirectory”と同時に指定された場合、本指定が優先されます。
本指定が省略された場合、“traceDirectory”が指定されたものとして処理します。
本指定と“traceDirectory”が省略された場合は、標準出力（IJServerでは標準出力がロギングされるファイル）にトレース情報が出力されます。
本指定と同時に“traceFileCount”、“traceFileSize”を指定した場合、“traceFileCount”、“traceFileSize”の指定は無効となります。
ファイル出力中、出力先のディスク容量が不足した場合、それ以降のトレースは出力されません。
◆traceDirectory
traceDirectory=トレース情報出力ファイルを格納するディレクトリ |
トレース情報出力ファイルを格納するディレクトリのフルパスを指定します。
ディレクトリは存在している必要があります。
存在しないディレクトリを指定した場合は、この行は無効となります。
また、メソッドトレース機能を一般ユーザで起動した場合には、その一般ユーザに対する書き込み権が付与されているディレクトリを指定します。
指定のディレクトリには、次のルールでトレース情報出力ファイルを作成します。
mt<プロセスID>_n.log |
mt | : | トレース情報出力ファイルであることを示す固有の文字列です。 |
<プロセスID> | : | Javaアプリケーションが動作しているプロセスIDです。 |
_n | : | ファイル番号を示します。nは、0から始まり、最大で“traceFileCount”に指定した値-1までの番号が振られます。 |
.log | : | ファイルの拡張子です。 |
“traceFile”と同時に指定された場合、本指定は無効となります。
“traceFile”と本指定が省略された場合は、標準出力（IJServerでは標準出力がロギングされるファイル）にトレース情報が出力されます。
作成されるメソッドトレース情報出力ファイルは、“traceFileCount”に指定した個数作成され、さらに出力がある場合、ファイル番号0のファイルから上書きします。
同名のメソッドトレース情報出力ファイルが存在した場合、上書きします。
ファイル出力中、出力先のディスク容量が不足した場合、それ以降のトレースは出力されません。
◆traceFileCount
traceFileCount=トレース情報出力ファイルのローテーション数 |
トレース情報出力ファイルのローテーション数を指定します。1～10(個)が指定可能です。省略値は、2(個)です。
“traceFileCount”の記述がない場合、省略値と解釈します。
0以下の定義値を指定した場合は1と解釈します。11以上の定義値を指定した場合は10と解釈します。
数字以外を指定した場合は、省略値と解釈します。
本指定は“traceDirectory”が指定された場合に有効です。
“traceFile”が指定された場合は、無効となります。
◆traceFileSize
traceFileSize=トレース情報出力ファイルの最大サイズ |
トレース情報出力ファイルの1個あたりの最大サイズ(MB)を指定します。1～2147483647(MB)が指定可能です。省略値は、1(MB)です。
“traceFileSize”の記述がないか、以下を指定した場合は、省略値と解釈します。
1より小さな値
2147483647より大きな値
整数値以外の値
数字以外を指定
本指定は“traceDirectory”が指定された場合に有効です。
“traceFile”が指定された場合は、無効となります。
指定された定義値を境にファイルローテーションされます。
1行で示されるenter情報またはexit情報が2つのファイルに分割されるのを防ぐため、ファイルのサイズが定義値より大きくなる場合があります。
■制御ファイルの記述例
制御ファイルの記述例を、次に示します。
---------------------------------------------------------------------- # # Interstage Component FJTRACE sample configuration file. #
statementStyle=REGEX valueLevel=full timeStamp=false traceDirectory=D:\tmp traceFileCount=2 traceFileSize=1 traceMethod=^com/fujitsu/interstage/XXXX$ ^methodA$ traceMethod=^com/fujitsu/interstage/XXXX$ ^methodB$ (Ljava/lang/String;)V traceMethod=^com/fujitsu/interstage/XXXX/YYYY$ .* ----------------------------------------------------------------------
上記の記述例では、以下のようになります。
トレース情報出力形式 | : | メソッドの引数および戻り値の情報を出力する |
タイムスタンプ出力 | : | タイムスタンプを出力しない |
ファイル出力先ディレクトリ | : | D:\tmp 配下 |
ファイルローテーション数 | : | 2(個) |
ファイルの最大サイズ | : | 1ファイルあたり1(MB) |
トレース対象メソッド | : | "com.fujitsu.interstage.XXXX"クラスの |
statementStyle=BASIC（指定を省略）とした場合、以下は上記例と同じ意味を示しています。
---------------------------------------------------------------------- # # Interstage Component FJTRACE sample configuration file. #
valueLevel=full timeStamp=false traceDirectory=D:\tmp traceFileCount=2 traceFileSize=1 traceMethod=com.fujitsu.interstage.XXXX methodA traceMethod=com.fujitsu.interstage.XXXX methodB (Ljava/lang/String;)V traceMethod=com.fujitsu.interstage.XXXX.YYYY * ----------------------------------------------------------------------
◆Servletサービスの記述例
statementStyle=REGEXとし、総称指定を使用してServletサービスのトレースを採取する場合、ClassNotFoundExceptionというエラーメッセージが発生する場合があります。
このメッセージを止めたい場合は、トレースするクラスを詳細に指定し直すか、あるいは使用中のIJServerに合わせ（○印が指定）、以下のjarファイルのパスをclassPath指定に追加してください。
※以下の説明は、Windows(R)上で、製品をC:\Interstageにインストールした場合です。
クラス名 | V9.0以降のIJServer |
C:\Interstage\lib\isjmxrt.jar | ○ |
C:\Interstage\lib\isjmxcommon.jar | ○ |
C:\Interstage\lib\log4j-1.2.8.jar | ○ |
C:\Interstage\lib\commons-logging-api.jar | ○ |
C:\Interstage\lib\commons-digester.jar | ○ |
C:\Interstage\lib\commons-collections.jar | ○ |
C:\Interstage\lib\commons-modeler.jar | ○ |
C:\Interstage\lib\commons-beanutils.jar | ○ |
C:\Interstage\lib\javax77.jar | ○ |
C:\Interstage\lib\j2ee-sv-server.jar | ○ |
C:\Interstage\lib\servlet-server.jar | ○ |
C:\Interstage\lib\servlet-common.jar | ○ |
C:\Interstage\lib\ejb-server.jar | ○ |
C:\Interstage\J2EE\lib\isj2ee.jar | ○ |
C:\Interstage\J2EE\lib\isdeploy60.jar | ○ |
C:\Interstage\J2EE\lib\ijserverconfig.jar | ○ |
C:\Interstage\jmx\addons\jmxremote\lib\jmxremote.jar | ○ |
C:\Interstage\F3FMjs5\common\jslib配下のjarファイル (注1) | ○ |
C:\Interstage\F3FMjs5\common\lib配下のjarファイル (注1) | ○ |
C:\Interstage\F3FMjs5\server\jslib配下のjarファイル (注1) | ○ |
C:\Interstage\F3FMjs5\server\lib配下のjarファイル (注1) | ○ |
コンテナログにIJServer31009のメッセージで出力されるjarファイル | ○ |
(注1) 必ずこの順番で記載してください。
Webアプリケーションで使用しているユーザが作成したクラスで、ClassNotFoundExceptionが発生する場合があります。
これは、Webアプリケーションから使用されるjar群、class群は、war形式に沿ってWEB-INF/libやWEB-INF/classesに配置され動的に決定される場合があるためです。
この場合、配備されるパスをclassPathに追加します。
SampleServer.warというアプリケーションの場合の例を、以下に示します。
C:\Interstage\J2EE\var\deployment\ijserver\SampleServer\apps\SampleServer.war\WEB-INF\classes
C:\Interstage\J2EE\var\deployment\ijserver\SampleServer\apps\SampleServer.war\WEB-INF\lib\app-library.jar
※上記は、Windows(R)上で、製品をC:\Interstageにインストールした場合です。
また、他にもアプリケーションで使用しているjarファイルがある場合（IJServerディレクトリのShared/libディレクトリ配下など）、これらもあわせてclassPathに追加してください。
Servletサービスのトレースを採取する場合の設定ファイル例（statementStyle=BASIC）を以下に示します。
〔V9.0以降のIJServerを使用している場合〕 ---------------------------------------------------------------------- # # Interstage Component FJTRACE sample configuration file. # # javax.servlet.ServletConfigの実装クラス traceMethod=org.apache.catalina.core.StandardWrapperFacade * # javax.servlet.ServletContextの実装クラス traceMethod=org.apache.catalina.core.ApplicationContextFacade * # javax.servlet.http.HttpServletRequestの実装クラス traceMethod=org.apache.catalina.connector.RequestFacade * # javax.servlet.http.HttpServletRequest(ディスパッチ後) traceMethod=org.apache.catalina.core.ApplicationHttpRequest * # javax.servlet.http.HttpServletResponseの実装クラス traceMethod=org.apache.catalina.connector.ResponseFacade * # javax.servlet.http.HttpServletResponse(include後) traceMethod=org.apache.catalina.core.ApplicationHttpResponse *
# javax.servlet.http.HttpSessionの実装クラス traceMethod=org.apache.catalina.session.StandardSessionFacade * # javax.servlet.RequestDispatcherの実装クラス traceMethod=org.apache.catalina.core.ApplicationDispatcher * # javax.servlet.ServletInputStreamの実装クラス traceMethod=org.apache.catalina.connector.CoyoteInputStream *
# javax.servlet.ServletOutputStreamの実装クラス traceMethod=org.apache.catalina.connector.CoyoteOutputStream * # HttpServletResponseから取り出すjava.io.PrintWriter traceMethod=org.apache.catalina.connector.CoyoteWriter * # JSP outオブジェクトの実装クラス traceMethod=org.apache.jasper.runtime.JspWriterImpl * #サーブレットの実装クラス traceMethod=<サーブレットクラス名> * # javax.servlet.jsp.HttpJspPageの実装クラス traceMethod=org.apache.jsp.<JSP file name>_jsp * valueLevel=addHex timeStamp=true ----------------------------------------------------------------------
サーブレットクラスのメソッドトレースを採取する場合、サーブレットクラス名はweb.xmlファイル等から確認してください。
JSPで作成したクラスのメソッドトレースを採取する場合、次のように指定します。
traceMethod=org.apache.jsp.<JSP file name>_jsp * |
パッケージ“org.apache.jsp.”にクラス名<JSP file name>_jsp(JSP file nameにJSPソースのファイル名を指定し、その後ろに“_jsp”をつけます)と指定します。
Webアプリケーションのルートディレクトリ配下のサブディレクトリにJSPが格納されている場合は、サブディレクトリ名がorg.apache.jsp.に続くパッケージ名に含まれます。
メソッド名、シグネチャに関しては、通常と同じ指定が可能です。
注意
状況に応じて必要のないクラスはコメントアウトしてください。
上記各実装クラスやJSPで作成したクラスの名前は、使用状況やInterstageのバージョン・レベル等により変化する場合があります。
◆EJBサービスの記述例
statementStyle=BASICを指定した場合、EJBアプリケーションのデバッグ時にメソッドトレース機能を使用する場合は、作成したEJBアプリケーションのEnterprise Beanクラスを指定してください。
CMP2.0 Entity Beanの場合、Enterprise Beanクラスに“_PM”を加えた文字列を指定してください。
CMP2.0 Entity BeanのEnterprise BeanクラスがflightSample.CustomerBeanの場合
flightSample.CustomerBean_PM |
■制御ファイルの更新を反映する方法
制御ファイルは、アプリケーションの起動時に一度だけ読み込まれます。
制御ファイルの内容を更新し、その内容をメソッドトレースに反映させるためには、javaコマンドの再起動が必要になります。IJServerの場合では、ワークユニットの再起動が必要になります。
なお、ワークユニットの操作方法は、“Interstage管理コンソール ヘルプ”の[Interstage管理コンソール] > [Interstage Application Server] > [システム] > [ワークユニット] > [ワークユニットごとの操作] > [IJServer] > [操作]を参照してください。
