状況によっては、
WebSphere® Application Server に付属する Java™ Persistence API (JPA) プロバイダーによって生成されるトレース情報では問題の診断に不十分な場合があります。
このような場合は、拡張トレース・メカニズムを使用可能に設定し、トレース・ファイルに追加情報を生成することが可能です。
拡張トレースは、IBM が提供するパーシスタンス・プロバイダーでのみ機能します。
アプリケーションにバンドルされたり共有ライブラリーとして構成されたりしている代替バージョンの OpenJPA などの、サード・パーティーのプロバイダーでは機能しません。
このタスクについて
注: このトピックでは、
1 つ以上のアプリケーション・サーバー・ログ・ファイルを参照します。推奨される代替案として、分散システムや IBM® i システムの SystemOut.log、SystemErr.log、trace.log、activity.log ファイルではなく、High Performance Extensible Logging (HPEL) ログおよびトレース・インフラストラクチャーを使用するようにサーバーを構成できます。また HPEL は、ネイティブ z/OS® ロギング機能と連携させて使用することができます。HPEL を使用する場合、LogViewer コマンド・ライン・ツールを
サーバー・プロファイルの bin ディレクトリーから使用して、すべてのログ・ファイルにアクセスし、
情報をトレースできます。HPEL の使用について詳しくは、HPEL を使用してのアプリケーションの
トラブルシューティングに関する情報を参照してください。
WebSphere Application Server で実行されるアプリケーションの拡張 JPA トレースは、
wsadmin スクリプトまたは管理コンソールを使用した簡単な手順で使用可能にできます。
このトピックのステップで、管理コンソールを使用した拡張トレースの構成方法について説明します。このプロセスではサーバー設定を変更するため、以下を実行する前にサーバー構成をバックアップすることをお奨めします。
手順
- トレース・エージェントを使用可能にします。 トレース・エージェントは、サーバーの Java 仮想マシン (JVM) に引数を引き渡すことにより、
アプリケーション・サーバーごとに使用可能にする必要があります。トレース・エージェントを使用可能にするには、管理コンソールで以下のステップを使用します。
- ナビゲーション・ペインで、「サーバー」を選択します。
「アプリケーション・サーバー」を選択します。
- サーバー・リストのペインで、拡張 JPA トレースが必要なサーバーを選択します。
アプリケーションに対して複数のサーバーが JPA 機能を提供している場合は、各サーバーごとに上記のステップを実行する必要があります。
- 「サーバー・インフラストラクチャー」見出しの下にある「Java およびプロセス管理」を選択します。
「プロセス定義」を選択します。
- 「追加プロパティー」見出しの下にある「Java 仮想マシン」を選択します。
- 「汎用 JVM 引数」フィールドに以下の引数を追加します。
ここで、<app_server_root> は、アプリケーション・サーバーのインストール・ディレクトリーの完全修飾パスです。
使用するオペレーティング・システムに適したパス分離文字を使用しているかを確認してください。
-javaagent:<app_server_root>/optionalLibraries/IBM/wsjpa/wsjpatrace.jar
重要: 管理コンソールでの汎用 JVM 引数の使用では、現在は引数内のスペースがサポートされていません。
このフィールドにスペースが指定されると、サーバーの始動が失敗する恐れがあります。これは、Windows 環境でのデフォルト・インストール・パスが C:¥Program Files¥IBM¥WebSphere¥AppServer であり、そのパスにスペースが含まれているため、Windows 環境では発生する可能性が高くなります。Windows 環境でのこの問題を回避するには、<app_server_root> に短縮したパス名を使用します。
例えば、C:¥Progra~1¥IBM¥WebSphere|AppServer のようにします。
UNIX タイプのシステムの場合は、シンボリック・リンクを使用すると <app_server_root> でのスペースを除去できます。
例えば、WebSphere Application Server のインストール・パスが /opt/app_server_root/AppServer である場合は、
<app_server_root> から AppServerRoot へのシンボリック・リンクを /opt に作成することにより、スペースを除去できます。
次に、汎用 JVM 引数の <app_server_root> として /opt/AppServerRoot/AppServer を指定します。
- 追加のトレース・コンポーネントを使用可能にして、トレース・ファイル・オプションを調整します。 このステップは、wsadmin スクリプトまたは管理コンソールを使用して実行することができます。
以下に、管理コンソールを使用してトレース・ファイル設定を調整し、コンポーネントを使用可能にする方法のステップを説明します。
- ナビゲーション・ペインで、「トラブルシューティング」を選択します。
「ログおよびトレース」をクリックします。
- トレースするサーバーの名前を選択します。
- 「一般プロパティー」の下にある「診断トレース」を選択します。
- 「ログを使用可能にする」がチェックされているかを確認し、
必要に応じて「最大ファイル・サイズ」 と「ヒストリー・ファイルの最大数」 を増やします。
選択した追加のトレース・カテゴリーの数およびトレース・レベルによっては、
トレース・ファイルが大きくなる場合があります。
- 「追加プロパティー」見出しの下にある「ログ詳細レベルの変更」を選択します。
- 以下の表にある 1 つ以上のトレース・カテゴリーを指定することにより、さまざまな拡張トレース・カテゴリーを使用可能にします。
例えば、トレース・ストリングは *=info:JPA=all:openjpa.*=finer:openjpa.kernel=finest のようにします。
拡張トレースでは、FINER または FINEST のトレース・レベルでトレースします。
FINEST レベルには、FINER より詳細な情報が含まれています。
ALL を指定した場合、拡張トレースでは FINEST レベルでトレースします。
表 1. トレース・カテゴリー. 拡張トレースを有効にする前に、サーバー構成をバックアップしてください。カテゴリー |
該当するトレース・レベル |
説明 |
JPA |
OFF、ALL、FINER、FINEST |
JPA トレース・グループに拡張トレースを追加します。 |
openjpa.* |
OFF、ALL、FINER、FINEST |
通常の OpenJPA トレース、および拡張トレースが有効である場合の OpenJPA のすべてのカテゴリーに対する拡張トレース。 |
openjpa.xtrace.* |
OFF、ALL、FINER、FINEST |
拡張トレースが有効である場合の OpenJPA のすべてのカテゴリーに対する拡張トレース。 |
openjpa.xtrace.Jdbc |
OFF、ALL、FINER、FINEST |
拡張トレースが有効である場合の OpenJPA JDBC クラスに対する拡張トレース。 |
openjpa.xtrace.Lib |
OFF、ALL、FINER、FINEST |
拡張トレースが有効である場合の OpenJPA ライブラリー・クラスに対する拡張トレース。 |
openjpa.xtrace.Persist |
OFF、ALL、FINER、FINEST |
拡張トレースが有効である場合の OpenJPA パーシスタンス・クラスに対する拡張トレース。 |
openjpa.xtrace.Kernel |
OFF、ALL、FINER、FINEST |
拡張トレースが有効である場合の OpenJPA カーネル・クラスに対する拡張トレース。 |
openjpa.xtrace.General |
OFF、ALL、FINER、FINEST |
拡張トレースが有効である場合の JDBC、ライブラリー、パーシスタンス、またはカーネルの各カテゴリーに含まれない OpenJPA クラスに対する拡張トレース。 |
openjpa.xtrace.ApiSpi |
OFF、ALL、FINER、FINEST |
拡張トレースが有効である場合の WsJPA、OpenJPA、および JPA に対して定義された、
公開 API/SPI インターフェースの拡張トレース。 |
- アプリケーション・サーバー構成を保存し、アプリケーション・サーバーを再始動します。
タスクの結果
アプリケーション・サーバーが再始動されると、新規のトレース設定が使用されます。
次のタスク
トラブルの回避 (Avoid trouble): トレースによりパフォーマンスが大幅に低下することがあるため、使用しない場合はトレースを使用不可にする必要があります。
トレースを使用不可にするには、汎用 JVM 引数、および拡張トレース用に追加したすべてのトレース詳細レベルを削除してください。
gotcha