ドライバー操作のトレース

[アーティクル]
09/18/2009

Microsoft SQL Server JDBC Driver をアプリケーションで使用すると、トレース (またはログ記録) を使用して JDBC ドライバーで発生した問題の解決に役立てることができます。トレースを有効にするため、JDBC ドライバーでは java.util.logging でログ記録 API を使用しています。この API には、Logger および LogRecord オブジェクトを作成するための一連のクラスが用意されています。

メモ :
JDBC ドライバーに含まれているネイティブのコンポーネント sqljdbc_xa.dll については、Built-In Diagnostics (BID) フレームワークを使用してトレースを有効にしています。BID の詳細については、「SQL Server 2005 でのデータアクセスのトレース」を参照してください。

アプリケーションを開発するとき、Logger オブジェクトを呼び出すことができます。このオブジェクトは、LogRecord オブジェクトを順に作成し、作成されたこれらのオブジェクトは Handler オブジェクトに渡されて処理されます。Logger および Handler オブジェクトは、いずれもログ記録のレベルを使用し、どの LogRecords を処理するかを管理することができます。また、オプションでログ記録フィルターを使用することもできます。ログの記録が完了すると、Handler オブジェクトは、Formatter オブジェクトを使用してオプションでログ情報を公開することができます。

既定では、java.util.logging フレームワークは出力をファイルに書き込みます。この出力ログファイルは、JDBC ドライバーが動作しているコンテキストについて書き込みアクセス許可を持つ必要があります。

メモ :
プログラムをトレースするためのさまざまなログ記録オブジェクトの使用の詳細については、Sun Microsystems の Web サイトで Java ログ記録 API についてのドキュメント (英語ページの可能性があります) を参照してください。

次のセクションでは、ログ記録のレベルおよびログ記録可能なカテゴリについて説明し、アプリケーションでトレースを有効にする方法についての情報を提供します。

ログ記録のレベル

作成されるすべてのログメッセージは、ログ記録のレベルと関連付けられています。ログ記録のレベルはログメッセージの重要度を決定し、java.util.logging の Level クラスで定義されます。あるレベルでログ記録を有効にすると、それより上のすべてのレベルでログ記録が有効になります。このセクションでは、ログ記録のパブリックなカテゴリと内部的なカテゴリの両方を対象に、ログ記録のレベルについて説明します。ログ記録カテゴリの詳細については、このトピックの「ログ記録のカテゴリ」を参照してください。

次の表では、パブリックなログ記録のカテゴリで利用可能なログ記録の各レベルについて説明します。

名前	説明
SEVERE	重大なエラーを示す、最高レベルのログ記録です。JDBC ドライバーでは、このレベルはエラーや例外の報告に使用されます。
WARNING	問題が発生する可能性があることを示します。
INFO	情報としてのメッセージを提供します。
CONFIG	構成に関するメッセージを提供します。ただし、現時点では JDBC ドライバーから構成メッセージは一切提供されません。
FINE	パブリックメソッドによってスローされるすべての例外を含め、基本的なトレース情報を提供します。
FINER	パブリックメソッドのすべての開始ポイントと終了ポイント、関連するパラメーターのデータ型、パブリッククラスのすべてのパブリックプロパティなど、詳細なトレース情報を提供します。入力パラメーター、出力パラメーター、メソッドの戻り値 (CLOB、BLOB、NCLOB、Reader、<stream> の戻り値の型を除く) も含まれます。
FINEST	より詳細なトレース情報を提供します。これは最低レベルのログ記録です。
OFF	ログ記録をオフにします。
ALL	すべてのメッセージのログ記録を有効にします。

次の表では、内部的なログ記録のカテゴリで利用可能なログ記録の各レベルについて説明します。

名前	説明
SEVERE	重大なエラーを示す、最高レベルのログ記録です。JDBC ドライバーでは、このレベルはエラーや例外の報告に使用されます。
WARNING	問題が発生する可能性があることを示します。
INFO	情報としてのメッセージを提供します。
FINE	基本的なオブジェクトの作成と破棄など、各種のトレース情報を提供します。パブリックメソッドによってスローされるすべての例外も含まれます。
FINER	パブリックメソッドのすべての開始ポイントと終了ポイント、関連するパラメーターのデータ型、パブリッククラスのすべてのパブリックプロパティなど、詳細なトレース情報を提供します。入力パラメーター、出力パラメーター、メソッドの戻り値 (CLOB、BLOB、NCLOB、Reader、<stream> の戻り値の型を除く) も含まれます。バージョン 1.2 の JDBC ドライバーには、SQLServerConnection、SQLServerStatement、XA、SQLServerDataSource の各ログ記録カテゴリが存在し、いずれも FINE のログ記録レベルが割り当てられていました。これらは、バージョン 2.0 リリースで FINER レベルにアップグレードされています。
FINEST	より詳細なトレース情報を提供します。これは最低レベルのログ記録です。バージョン 1.2 の JDBC ドライバーには、TDS.DATA および TDS.TOKEN というログ記録カテゴリが存在し、いずれも FINEST のログ記録レベルが割り当てられていました。バージョン 2.0 リリースでも、ログ記録レベルは FINEST から変更されていません。
OFF	ログ記録をオフにします。
ALL	すべてのメッセージのログ記録を有効にします。

ログ記録のカテゴリ

Logger オブジェクトを作成するときは、どの名前付きエンティティまたはカテゴリからログ情報を取得するのかをそのオブジェクトに知らせる必要があります。JDBC ドライバーは、パブリックなログ記録のカテゴリとして、次のカテゴリをサポートします。いずれも com.microsoft.sqlserver.jdbc ドライバーパッケージで定義されています。

名前	説明
Connection	SQLServerConnection クラスのメッセージを記録します。アプリケーションは、ログ記録レベルを FINER として設定できます。
Statement	SQLServerStatement クラスのメッセージを記録します。アプリケーションは、ログ記録レベルを FINER として設定できます。
DataSource	SQLServerDataSource クラスのメッセージを記録します。アプリケーションは、ログ記録レベルを FINE として設定できます。
ResultSet	SQLServerResultSet クラスのメッセージを記録します。アプリケーションは、ログ記録レベルを FINER として設定できます。
Driver	SQLServerDriver クラスのメッセージを記録します。アプリケーションは、ログ記録レベルを FINER として設定できます。

Microsoft JDBC Driver Version 2.0 以降では、さらに com.microsoft.sqlserver.jdbc.internals パッケージが用意されており、内部的なログ記録のカテゴリとして、次のカテゴリがサポートされています。

名前	説明
AuthenticationJNI	Windows 統合認証の問題に関するメッセージをログに記録します。アプリケーションは、ログ記録レベルを FINEST および FINE として設定できます。
SQLServerConnection	SQLServerConnection クラスのメッセージを記録します。アプリケーションは、ログ記録レベルを FINE および FINER として設定できます。
SQLServerDataSource	SQLServerDataSource、SQLServerConnectionPoolDataSource、および SQLServerPooledConnection クラスのメッセージを記録します。アプリケーションは、ログ記録レベルを FINER として設定できます。
InputStream	java.io.InputStream、java.io.Reader のほか、max 指定子を持つデータ型 (varchar、nvarchar、varbinary など) に関するメッセージを記録します。アプリケーションは、ログ記録レベルを FINER として設定できます。
SQLServerException	SQLServerException クラスのメッセージを記録します。アプリケーションは、ログ記録レベルを FINE として設定できます。
SQLServerResultSet	SQLServerResultSet クラスのメッセージを記録します。アプリケーションは、ログ記録レベルを FINE、FINER、および FINEST として設定できます。
SQLServerStatement	SQLServerStatement クラスのメッセージを記録します。アプリケーションは、ログ記録レベルを FINE、FINER、および FINEST として設定できます。
XA	SQLServerXADataSource クラスのすべての XA トランザクションについてメッセージを記録します。アプリケーションは、ログ記録レベルを FINE および FINER として設定できます。
TDS.DATA	ドライバーと SQL Server の間で交わされる TDS プロトコルレベルのメッセージ交換を含んだメッセージを記録します。送受信される各 TDS パケットの詳細な内容が ASCII および 16 進形式で記録されます。ログイン資格情報 (ユーザー名とパスワード) は記録されません。それ以外のすべてのデータが記録されます。このカテゴリは非常に冗長で詳細なメッセージを作成します。ログ記録のレベルを FINEST に設定したときにのみ有効になります。
TDS.Channel	SQL Server との TCP 通信チャネルのアクションをトレースします。記録されるメッセージには、読み取りや書き込みのほか、ソケットの開閉が含まれます。SQL Server との SSL (Secure Sockets Layer) 接続の確立に関連したメッセージもトレースされます。このカテゴリは、ログ記録レベルを FINE、FINER、または FINEST に設定したときにのみ有効になります。
TDS.Writer	TDS チャネルへの書き込みをトレースします。トレースされるのは書き込みの長さのみです。書き込みの内容がトレースされるわけではありません。このカテゴリでは、アテンションシグナルがサーバーに送信され、ステートメントの実行がキャンセルされた場合にも、問題がトレースされます。このカテゴリは、ログ記録レベルを FINEST に設定したときにのみ有効になります。
TDS.Reader	TDS チャネルからの特定の読み取り操作を FINEST レベルでトレースします。FINEST レベルのトレースは、非常に冗長になる場合があります。WARNING レベルや SEVERE レベルでは、ドライバーが接続を閉じる前に SQL Server から無効な TDS プロトコルを受信した場合にトレースが行われます。このカテゴリは、ログ記録レベルを FINER または FINEST に設定したときにのみ有効になります。
TDS.Command	低レベルの状態遷移や、TDS コマンドの実行に関連したその他の情報 (T-SQL ステートメントの実行、ResultSet カーソルのフェッチ、コミットなど) をトレースします。このカテゴリは、ログ記録レベルを FINEST に設定したときにのみ有効になります。
TDS.TOKEN	このカテゴリは、TDS パケット内のトークンのみを記録しますが、TDS.DATA カテゴリほど冗長ではありません。ログ記録レベルを FINEST に設定したときにのみ有効になります。 FINEST レベルでは、応答で処理される TDS トークンがトレースされます。SEVERE レベルでは、無効な TDS トークンが検出された場合にトレースが実行されます。
SQLServerDatabaseMetaData	SQLServerDatabaseMetaData クラスのメッセージを記録します。アプリケーションは、ログ記録レベルを FINE として設定できます。
SQLServerResultSetMetaData	SQLServerResultSetMetaData クラスのメッセージを記録します。アプリケーションは、ログ記録レベルを FINE として設定できます。
SQLServerParameterMetaData	SQLServerParameterMetaData クラスのメッセージを記録します。アプリケーションは、ログ記録レベルを FINE として設定できます。
SQLServerBlob	SQLServerBlob クラスのメッセージを記録します。アプリケーションは、ログ記録レベルを FINE として設定できます。
SQLServerClob	SQLServerClob クラスのメッセージを記録します。アプリケーションは、ログ記録レベルを FINE として設定できます。
SQLServerSQLXML	内部的な SQLServerSQLXML クラスのメッセージを記録します。アプリケーションは、ログ記録レベルを FINE として設定できます。
SQLServerDriver	SQLServerDriver クラスのメッセージを記録します。アプリケーションは、ログ記録レベルを FINE として設定できます。
SQLServerNClob	SQLServerNClob クラスのメッセージを記録します。アプリケーションは、ログ記録レベルを FINE として設定できます。

トレースをプログラムで有効にする

トレースは、Logger オブジェクトを作成し、ログ記録するカテゴリを指定することにより、プログラムで有効にすることができます。たとえば、次のコードは SQL ステートメントのログ記録を有効にする方法を示しています。

Logger logger = Logger.getLogger("com.microsoft.sqlserver.jdbc.Statement");
logger.setLevel(Level.FINER);

コードの中でログ記録を無効にするには、次のようにします。

logger.setLevel(Level.OFF);

利用可能なすべてのカテゴリをログ記録するには、次のようにします。

Logger logger = Logger.getLogger("com.microsoft.sqlserver.jdbc");
logger.setLevel(Level.FINE);

特定のカテゴリのログ記録を無効にするには、次のようにします。

Logger logger = Logger.getLogger("com.microsoft.sqlserver.jdbc.Statement");
logger.setLevel(Level.OFF);

Logging.Properties ファイルを使用してトレースを有効にする

logging.properties ファイルを使用してトレースを有効にすることもできます。このファイルは、Java ランタイム環境 (JRE) のインストールディレクトリ lib にあります。このファイルを使用すると、トレースが有効になったときに使用されるロガーやハンドラーに既定値を設定することができます。

次は、logging.properties ファイルで行うことができる設定の一例です。

   # Specify the handlers to create in the root logger
   # (all loggers are children of the root logger).
   # The following creates two handlers.
   handlers = java.util.logging.ConsoleHandler, java.util.logging.FileHandler

   # Set the default logging level for the root logger.
   .level = OFF

   # Set the default logging level for new ConsoleHandler instances.
   java.util.logging.ConsoleHandler.level = FINE

   # Set the default logging level for new FileHandler instances.
   java.util.logging.FileHandler.level = OFF

   # Set the default formatter for new ConsoleHandler instances.
   java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter

   # Set the default logging level for the logger named ConnectionPool.
   ConnectionPool.level = OFF

メモ :
java.util.logging に含まれる LogManager オブジェクトを使用して、`logging.properties` ファイルでプロパティを設定することができます。

参照

その他の技術情報

JDBC ドライバで発生した問題の診断

次の方法で共有