1. Universal Connection Pool開発者ガイド
  2. 接続プールの診断
  3. UCPでのロギングおよびトレースの概要

14.3 UCPでのロギングおよびトレースの概要

UCP診断の主要な2つの側面は、ロギングとトレースです。

ロギングでは、ログ・レコードをコンソール、ファイルまたは標準のロギング・プロパティで定義されたその他のログ・ハンドラに書き込みます。ログ出力の名前は、プール・データソース名と同じです。プール・データソース名は、適切なプロパティを使用して設定されます。名前を付けないままにしておくこともできます。その場合、すべての診断が共通のログ出力に入ります。共通ログ出力の名前はoracle.ucpです。ロギングは、JavaロギングAPI java.util.loggingを実装します。

トレースは特殊なロギング・ユースケースで、イベントによってUCP診断がトリガーされ、そのバッファが対応するログ出力にダンプされるまで、ログ・レコードがインメモリー・リング・バッファに書き込まれます。UCPには、次の2つのカテゴリのトレース・バッファがあります。

ノート:

プール・データソースとUCPには1対1のマッピングがあります。
  • 指定された名前のプールに直接関係しない静的メソッドからのログのトレースに使用される、1つの共通バッファで構成されるカテゴリ。共通バッファは、関連付けられたUCPの全存続期間、永続的です。
  • 名前付きプール・データソース(PDS)オブジェクト数と同じ数のバッファを含むカテゴリで、すべてのバッファは単一の名前付きPDSにマップされます。そのPDSからのすべてのトレースが対応するバッファに入ります。その存続期間はプール起動から始まり、プール破棄で終わります。

14.3.1 ロギングおよびトレース設定

ロギングを有効にする場合は、ログ・レコードがログ出力に即時にダンプされ、ログ・レコードをトレース・バッファに複製する必要がないため、トレースを有効にしないでください。そのため、ロギングがオンの場合、トレース設定に関係なく、トレースは自動的に無効になります。

ノート:

デフォルトでは、トレースはオンでロギングはオフです。

次の表に、この機能の概要を示します。

ロギング設定 トレース設定 ロギング機能 トレース機能
off off 無効 無効
on off 有効 無効
off on 無効 有効
on on 有効 無効

14.3.2 診断システム・プロパティおよびコマンドライン

初期診断プロパティをJVMシステム・プロパティとして設定できます。

次の方法で可能です。

  • Oracle JVMコマンドラインの使用
  • アプリケーション・ソース・コード内
  • Java Management Extensions (JMX)の使用
プロパティ名 説明
oracle.ucp.diagnostic.enableTrace トレースを有効にするフラグです。このプロパティのデフォルト値はtrueです。
oracle.ucp.diagnostic.enableLogging デバッグ・ロギングを有効にするフラグです。このプロパティのデフォルト値はfalseです。
oracle.ucp.diagnostic.bufferSize インメモリー・トレース・バッファ・サイズを指定します。デフォルト値は1024です。
oracle.ucp.diagnostic.loggingLevel ロギング構成ファイルでログ出力に他の値が指定されていない場合に使用されるデフォルトのロギング・レベルを指定します。このプロパティのデフォルト値はINFOです。
java.util.logging.config.file ロードするロギング・プロパティ・ファイル名を指定します。すべてのログ出力のデフォルト値はConsoleHandlerです。
oracle.ucp.diagnostic.errorCodesToWatchList すべてのトレースをログ出力にダンプする例外およびエラー・コードのリストを提供します。

14.3.3 ロギング構成ファイル

ロギング構成ファイルでは、java.util.loggingパッケージの説明に従ってロギング設定を構成できます。異なるログ出力に異なるレベルを設定する場合は、ロギング構成ファイルでレベルを設定する必要があります。

共通ログ出力を構成するには、次を実行します。

  • ログ出力をoracle.ucpとして指定します。
  • 適切なロギング・レベルを設定します。
  • ログの書込み先と書込み方法を指定します。たとえば、ログをコンソールに書き込むか、ファイルに書き込むかなどです。ファイルの場合は、ファイル名、フォーマッタなどを指定します。

プール・データソース・オブジェクトに固有のログ出力を構成するには、次を実行します。

  • そのプール・データソースの名前でログ出力のレベルを設定します。
  • 適切なロギング・レベルを設定します。

    ノート:

    ログ出力のレベルを指定しない場合は、ucp.diagnostic.loggingLevelに設定されているデフォルト・レベルが使用されます。

例14-1 ロギング構成ファイル

次に、UCP診断ロギング構成ファイルの例を示します。

oracle.ucp.level=FINE
handlers = java.util.logging.FileHandler
java.util.logging.FileHandler.pattern = ./test.log
java.util.logging.FileHandler.limit = 0
java.util.logging.FileHandler.count = 1
java.util.logging.FileHandler.formatter = java.util.logging.SimpleFormatter
pool-name1=FINEST
pool-name2=SEVERE

ロギング・レベル

UCP診断フレームワークのロギング・レベルは、java.util.loggingパッケージで使用可能なものと同じですが、UCPではInteger.MIN_VALUEからInteger.MAX_VALUEまでの範囲の数値ロギング・レベルもサポートされています。次の表に、有効なすべてのロギング・レベルを示します。

ロギング・レベル 値
OFF Integer.MAX_VALUE
SEVERE 1000
WARNING 900
INFO 800
CONFIG 700
FINE 500
FINER 400
FINEST 300
ALL Integer.MIN_VALUE

14.3.4 監視するエラー・コードのトレース

監視するエラー・コードはトレースにのみ適用できます。トレースが無効になっている場合、設定を監視するエラー・コードは無視されます。

トレース・バッファを適切なログ出力にダンプするトリガーとなるイベント・タイプは2つあります。

  • SEVEREログ・レベルのログ・メッセージ。
  • JDBCドライバまたはUCPによってスローされるjava.lang.Throwableクラスのサブクラスなど、一部の例外またはエラー。これらのエラーまたは例外は内部で捕捉され、WARNINGレベルでログに記録されます。これらの例外のサブセットは、ucp.diagnostic.errorCodesToWatchListプロパティで定義されます。

WARNINGログ・メッセージ(java.lang.Throwableのサブクラスを含む)では、エラー・コードのリストに例外が見つかった場合、トレース・バッファをログ出力にダンプできます。例外にエラーまたは例外のスタックが含まれている場合、UCPはそのスタックを横断し、一致する例外および対応するエラー・コード(該当する場合)を見つけようとします。エラー・コードのリストの形式は次のとおりです。 

["<subclass1>.<Exception1>:111,222,333", "<subclass2>.<Exception2>:444,555,666", "<subclass3>.<Exception3>"]

ここで、subclass1.Exception1、subclass2.Exception2およびsubclass3.Exception3はjava.lang.Throwableサブクラスです。

たとえば、次のようなエラー・コードが表示された場合:

[ "oracle.ucp.UniversalConnectionPoolException:45054,45065,45067", 
"java.sql.SQLException:12521,12514,12757,12523", 
"java.lang.IllegalStateException", "java.lang.NullPointerException" ]

これは、トレースが次の順序でトリガーされることを意味します。

  1. ベンダー・エラー・コード45054、45065および45067を含むoracle.ucp.UniversalConnectionPoolException
  2. ベンダー・エラー・コード12521、12514、12757および12523を含むjava.sql.SQLException
  3. IllegalStateException
  4. NullPointerException

完全修飾されたjava.lang.Throwableサブクラス名のみが、トレース・バッファをログ出力にダンプできます。たとえば、java.sql.NullPointerExceptionは有効な名前ですが、NullP、NullPointerException、["12154"]、["ORA-"]または["ORA-12154"]は有効ではありません。誤って指定した場合、サブクラス名は解析エラーまたはクラス解決エラー(あるいはその両方)をWARNINGとともにログに記録します。数値変換エラーでも、WARNINGとともに解析エラーがログに記録される場合があります。

解析およびクラス解決が失敗した場合、すべてのWARNINGログ・レコードに例外が発生すると、トレース・バッファがダンプされます。これは、例外タイプと指定のエラー・コードには関係ありません。ロギング・モードでエラー・コードが無視されると、解析されなくなります。

エラー・コードのカンマ区切りリストは、次の2つのクラスとそのサブクラスの場合にのみ使用されます。

  • java.sql.SQLExceptionおよびそのサブクラス(java.sql.SQLRecoverableExceptionやjava.sql.SQLSyntaxErrorなど)
  • oracle.ucp.UniversalConnectionPoolExceptionおよびそのサブクラス(NoAvailableConnectionsExceptionなど)

他の例外タイプとともにエラー・コードのカンマ区切りリストを指定した場合、それらのエラー・コードは無視されます。前述の2つの例外とそのサブクラスに対するエラー・コードのリストが空の場合、すべてのエラー・コードを適用できます。UCP診断には、デフォルトのエラー・コード・リストがあります。oracle.UCP.UniversalConnectionPoolExceptionエラー・コードのリストは、「UCP例外エラー・コード」を参照してください。

トレース・バッファを例外のあるWARNINGメッセージによってダンプする場合は、次のように実行できます。

例14-2 例外によってトレースをダンプする場合

"["java.lang.Throwable"]"

14.3.5 UCP診断用のMBeans

UCPは、UCP診断に2つのMBeansを提供します。
  • ucp.admin: JVM全体に対する属性および操作が含まれています。すべてのプール・データソースに関連付けられたバッファ、および一般的なインメモリー・バッファを管理します。次のMBean属性の初期値を変更して設定できます。
    • enableTrace
    • enableLogging
    • loggingLevel
    • bufferSize
    • errorCodesToWatchList
    • loggingConfigFileName

    また、dumpInMemoryTraceという操作もあります。この操作を起動すると、すべてのインメモリー・バッファの内容を適切なログ出力にダンプできます。

  • ucp.admin.UniversalConnectionPoolMBean: 既存のプール・インスタンスのツリーが含まれています。すべてのインスタンスには、その特定のプールの適切なプロパティを変更する独自の属性があります。属性は次のとおりです。
    • enableTrace
    • enableLogging
    • loggingLevel
    • inMemoryTraceSize