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 類別所定義。 啟用單一層級的記錄也會啟用所有較高層級的記錄。 本節將描述公用記錄類別目錄和內部記錄類別目錄的記錄層級。 如需有關記錄類別目錄的詳細資訊，請參閱此文章中的「記錄類別目錄」一節。
下表將描述公用記錄類別目錄的每個可用記錄層級。
| 名稱 | 描述 |
|---|---|
| 嚴重 | 表示嚴重失敗，這是最高的記錄層級。 在 JDBC 驅動程式中，這個層次用於報告錯誤和例外狀況。 |
| 警告 | 表示潛在問題。 |
| 資訊 | 提供參考訊息。 |
| 配置 | 提供組態訊息。 JDBC 驅動程式目前無法提供任何組態訊息。 |
| FINE | 提供基本追蹤資訊，其中涵蓋所有由公用方法引發的例外狀況。 |
| FINER | 提供詳細的追蹤資訊，包括所有公用方法的進入和結束點 (包含相關聯的參數資料類型)，以及公用類別的所有公用屬性。 同時，輸入參數、輸出參數和方法傳回值中，排除 CLOB、BLOB、NCLOB、Reader、<stream> 這些傳回值類型。 |
| 最優 | 提供非常詳細的追蹤資訊。 此設定是最低的記錄層級。 |
| OFF | 關閉記錄。 |
| ALL | 啟用所有訊息的記錄。 |
下表描述內部日誌類別的每個可用的記錄層級。
| 名稱 | 描述 |
|---|---|
| 嚴重 | 表示嚴重失敗，這是最高的記錄層級。 在 JDBC 驅動程式中，這個層次用於報告錯誤和例外狀況。 |
| 警告 | 表示潛在問題。 |
| 資訊 | 提供參考訊息。 |
| FINE | 提供追蹤資訊，包括基本物件的建立和銷毀。 還有，所有由公用方法擲出的例外狀況。 |
| FINER | 提供詳細的追蹤資訊，包括所有公用方法的進入和結束點 (包含相關聯的參數資料類型)，以及公用類別的所有公用屬性。 同時，輸入參數、輸出參數和方法傳回值中，排除 CLOB、BLOB、NCLOB、Reader、<stream> 這些傳回值類型。 下列記錄類別存在於 JDBC 驅動程式 1.2 版中，而且具有 FINE 記錄層級：SQLServerConnection、SQLServerStatement、XA 及 SQLServerDataSource。 從 2.0 版開始，這些類別已升級為 FINER 層級。 |
| 最優 | 提供非常詳細的追蹤資訊。 此設定是最低的記錄層級。 下列記錄類別存在於 JDBC 驅動程式 1.2 版中，而且具有 FINEST 記錄層級：TDS.DATA 和 TDS.TOKEN。 從 2.0 版開始，它們會保留 FINEST 記錄層級。 |
| OFF | 關閉記錄。 |
| ALL | 啟用所有訊息的記錄。 |
記錄類別
建立 Logger 物件時，必須告知物件您有興趣取得記錄資訊的具名實體或類別。 JDBC 驅動程式支援下列公共記錄類別，全都定義於 com.microsoft.sqlserver.jdbc 驅動程式套件中。
| 名稱 | 描述 |
|---|---|
| 連接 | 記錄 SQLServerConnection 類別中的訊息。 應用程式可以將記錄層級設定為 FINER。 |
| 敘述 | 記錄 SQLServerStatement 類別中的訊息。 應用程式可以將記錄層級設定為 FINER。 |
| 資料來源 | 記錄 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.寫作器 | 這個類別會追蹤 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 檔案的屬性。
效能指標紀錄
從 13.4.0 版本開始，驅動程式提供專用的效能指標記錄器，追蹤連線與語句操作的時序。 與前述的診斷追蹤類別不同，這些記錄器專為測量執行延遲而設計，而非除錯協定層級行為。
目前有兩種性能記錄器可供選擇：
| 日誌名稱 | 描述 |
|---|---|
com.microsoft.sqlserver.jdbc.PerformanceMetrics.Connection |
追蹤連線、預登入、登入及代幣取得時間。 |
com.microsoft.sqlserver.jdbc.PerformanceMetrics.Statement |
追蹤陳述式請求建置、首次伺服器回應、準備、預備執行及執行時序。 |
將這些記錄器設為 FINE 電平以啟用公制輸出。 你也可以註冊程式化回調，用於進行中度量收集，取代（或附加）日誌輸出。
關於設定細節、追蹤活動及程式碼範例，請參見 效能記錄器與回調。