追蹤驅動程式作業
Microsoft JDBC Driver for SQL Server 支援使用追蹤 (或記錄)，協助解決在應用程式中使用 JDBC 驅動程式所發生的問題。 為了啟用追蹤，JDBC 驅動程式使用 java.util.logging 中的記錄 API，它會提供一組類別來建立 Logger 和 LogRecord 物件。
注意
若是 JDBC 驅動程式隨附的原生元件 (sqljdbc_xa.dll)，內建診斷 (BID) 架構會啟用追蹤。 如需 BID 的資訊，請參閱 SQL Server 中的資料存取追蹤。
開發應用程式時，您可以呼叫 Logger 物件，進而建立 LogRecord 物件，這些物件接著會傳遞至 Handler 物件以進行處理。 Logger 和 Handler 物件都會使用記錄層級和記錄篩選 (選擇性)，來規範要處理哪些 LogRecord。 完成記錄作業時，Handler 物件可以選擇性地使用 Formatter 物件，以發佈記錄資訊。
根據預設，java.util.logging 架構會將其輸出寫入到檔案。 此輸出記錄檔必須將寫入權限授與給執行 JDBC 驅動程式的內容。
注意
如需使用各種記錄物件以進行程式追蹤的詳細資訊，請參閱 Sun Microsystems 網站上的＜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> 傳回值類型除外。 下列記錄類別存在於 JDBC 驅動程式 1.2 版中，而且具有 FINE 記錄層級：SQLServerConnection、SQLServerStatement、XA 及 SQLServerDataSource。 從 2.0 版開始，這些類別已升級為 FINER 層級。 |
| FINEST | 提供非常詳細的追蹤資訊。 此設定是最低的記錄層級。 下列記錄類別存在於 JDBC 驅動程式 1.2 版中，而且具有 FINEST 記錄層級：TDS.DATA 和 TDS.TOKEN。 從 2.0 版開始，它們會保留 FINEST 記錄層級。 |
| OFF | 關閉記錄。 |
| ALL | 啟用所有訊息的記錄。 |
記錄類別目錄
建立 Logger 物件時，必須告知物件您有興趣從中取得記錄資訊的具名實體或類別目錄。 JDBC Driver 支援下列公用記錄類別目錄，而且它們定義於 com.microsoft.sqlserver.jdbc 驅動程式封裝中。
| 名稱 | 描述 |
|---|---|
| Connection | 記錄 SQLServerConnection 類別中的訊息。 應用程式可以將記錄層級設定為 FINER。 |
| 引數 | 記錄 SQLServerStatement 類別中的訊息。 應用程式可以將記錄層級設定為 FINER。 |
| DataSource | 記錄 SQLServerDataSource 類別中的訊息。 應用程式可以將記錄層級設定為 FINE。 |
| ResultSet | 記錄 SQLServerResultSet 類別中的訊息。 應用程式可以將記錄層級設定為 FINER。 |
| 驅動程式 | 記錄 SQLServerDriver 類別中的訊息。 應用程式可以將記錄層級設定為 FINER。 |
| 復原 | 僅與閒置連線復原重新連線相關的 SQLServerConnection 類別中的記錄訊息。 應用程式可以將記錄層級設定為 FINE 和 FINER。 |
| 重新導向 | 僅與連線開啟重試相關的 SQLServerConnection 類別中的記錄訊息。 應用程式可以將記錄層級設定為 FINE。 |
從 Microsoft JDBC Driver 2.0 版開始，此驅動程式也提供了 com.microsoft.sqlserver.jdbc.internals 封裝，其中包含下列內部記錄類別目錄的記錄支援。
| 名稱 | 描述 |
|---|---|
| AuthenticationJNI | 記錄有關 Windows 整合式驗證問題的訊息 (當 authenticationScheme 連線屬性以隱含或明確方式設定為 NativeAuthentication 時)。 應用程式可以將記錄層級設定為 FINEST 和 FINE。 |
| SQLServerConnection | 記錄 SQLServerConnection 類別中的訊息。 應用程式可以將記錄層級設定為 FINE 和 FINER。 |
| SQLServerDataSource | 記錄 SQLServerDataSource、SQLServerConnectionPoolDataSource 和 SQLServerPooledConnection 類別中的訊息。 應用程式可以將記錄層級設定為 FINER。 |
| InputStream | 記錄有關下列資料類型的訊息：java.io.InputStream、java.io.Reader 以及具有最大規範的資料類型，例如 varchar、nvarchar 和 varbinary 資料類型。 應用程式可以將記錄層級設定為 FINER。 |
| SQLServerException | 記錄 SQLServerException 類別中的訊息。 應用程式可以將記錄層級設定為 FINE。 |
| SQLServerResultSet | 記錄 SQLServerResultSet 類別中的訊息。 應用程式可以將記錄層級設定為 FINE、FINER 和 FINEST。 |
| SQLServerStatement | 記錄 SQLServerStatement 類別中的訊息。 應用程式可以將記錄層級設定為 FINE、FINER 和 FINEST。 |
| XA | 記錄 SQLServerXADataSource 類別中所有 XA 交易的訊息。 應用程式可以將記錄層級設定為 FINE 和 FINER。 |
| KerbAuthentication | 記錄有關類型 4 Kerberos 驗證的訊息 (當 authenticationScheme 連線屬性設定為 JavaKerberos 時)。 此應用程式可以將記錄層級設定為 FINE 或 FINER。 |
| TDS.DATA | 記錄包含此驅動程式與 SQL Server 之間 TDS 通訊協定層級交談的訊息。 每個所傳送和接收之 TDS 封包的詳細內容都會以 ASCII 和十六進位的格式記錄。 但是，系統不會記錄登入認證 (使用者名稱和密碼)， 只會記錄所有其他資料。 這個類別目錄會建立非常詳細的訊息，並只能透過將記錄層次設為 FINEST 而啟用。 |
| TDS.Channel | 這個類別目錄會追蹤與 SQL Server 進行 TCP 通訊通道的動作。 記錄的訊息包括通訊端開啟和關閉，以及讀取和寫入。 此外，也會追蹤與 SQL Server 建立傳輸層安全性 (TLS) (先前稱為安全通訊端層 (SSL)) 連線的相關訊息。 這個類別目錄只能透過將記錄層級設定為 FINE、FINER 或 FINEST 而啟用。 |
| TDS.Writer | 這個類別目錄會追蹤 TDS 通道的寫入作業。 只會追蹤寫入的長度，而非內容。 當注意訊號傳送至伺服器以取消陳述式的執行時，這個類別目錄也會追蹤問題。 這個類別目錄只能透過將記錄層級設定為 FINEST 而啟用。 |
| TDS.Reader | 這個類別目錄會在 FINEST 層級中追蹤來自 TDS 通道的特定讀取作業。 在 FINEST 層級中，追蹤可能會很詳細。 在 WARNING 和 SEVERE 層級中，這個類別目錄會追蹤此驅動程式關閉連接之前，從 SQL Server 收到無效 TDS 通訊協定的時間。 這個類別目錄只能透過將記錄層級設定為 FINER 和 FINEST 而啟用。 |
| TDS.Command | 這個類別目錄會追蹤低層級的狀態轉換以及與執行 TDS 命令相關聯的其他資訊，例如 Transact-SQL 陳述式執行、ResultSet 資料指標擷取、認可等等。 這個類別目錄只能透過將記錄層級設定為 FINEST 而啟用。 |
| TDS.TOKEN | 這個類別目錄只會記錄 TDS 封包中的 Token，跟 TDS.DATA 類別目錄比起來較不詳細。 它只能透過將記錄層級設定為 FINEST 而啟用。 在 FINEST 層級中，這個類別目錄會在回應中處理 TDS Token 時追蹤它們。 在 SEVERE 層級中，這個類別目錄會追蹤遇到無效 TDS Token 的時間。 |
| 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 Runtime Environment (JRE) 8 安裝的 lib 目錄或 Java 9 和更高版本的 conf 資料夾中。 可以用這個檔案來設定當啟用追蹤時，所要使用的記錄器和處理常式預設值。
下列設定是可在 logging.properties 檔案中進行的設定範例：
# Specify the handler, the handlers will be installed during VM startup.
handlers= java.util.logging.FileHandler
# Default global logging level.
.level= OFF
# default file output is in user's home directory.
java.util.logging.FileHandler.pattern = %h/java%u.log
java.util.logging.FileHandler.limit = 5000000
java.util.logging.FileHandler.count = 20
java.util.logging.FileHandler.formatter = java.util.logging.SimpleFormatter
java.util.logging.FileHandler.level = FINEST
# Facility specific properties.
com.microsoft.sqlserver.jdbc.level=FINEST
注意
您可以使用 LogManager 物件 (屬於 java.util.logging 的一部分) 設定 logging.properties 檔案的屬性。