Microsoft JDBC Driver for SQL Server 支持使用跟踪（或日志记录）协助解决在应用程序中使用 JDBC 驱动程序时出现的问题。 若要启用跟踪，JDBC 驱动程序需要使用 java.util.logging 中的日志记录 API，java.util.logging 可提供用于创建 Logger 和 LogRecord 对象的类集。
从 13.6 版本开始，在未启用 FINER 级别时，驱动会避免为公共方法进入和退出日志记录产生参数分配和方法调用开销。 该优化是自动的，启用时 FINER 日志输出不变。
开发应用程序时，可对 Logger 对象进行调用，它会转而创建 LogRecord 对象（这些对象随后会传递给 Handler 对象进行处理）。 Logger 和 Handler 对象都会使用日志记录级别和日志记录筛选器（可选）来规定要处理的 LogRecord。 完成日志记录操作后，Handler 对象可选择使用 Formatter 对象发布日志信息。
默认情况下，java.util.logging 框架会将其输出写入到文件中。 该输出日志文件必须对 JDBC 驱动程序运行时所在的上下文具有写入权限。
注意
有关使用各种日志记录对象进行程序跟踪的详细信息，请参阅 Sun Microsystems 网站上的 Java Logging APIs（英文）文档。
以下各部分介绍了可记录的日志记录级别和类别，并提供了有关如何在应用程序中启用跟踪的信息。
日志记录级别
创建的每条日志消息都有相关联的日志记录级别。 日志记录级别决定了日志消息的重要性，该重要性由 java.util.logging 中的 Level 类定义 。 启用一个级别的日志记录还会启用所有较高级别的日志记录。 本节介绍公共日志记录类别和内部日志记录类别的日志记录级别。 有关日志记录类别的详细信息，请参阅本文的“日志记录类别”部分。
下表逐一介绍了公共日志记录类别每个可用的日志记录级别。
| 名称 | 说明 |
|---|---|
| 严重 | 表示严重故障，为最高日志记录级别。 在 JDBC 驱动程序中，该级别用于报告错误和异常。 |
| 警告 | 指示潜在的问题。 |
| 信息 | 提供信息提示。 |
| CONFIG | 提供配置消息。 JDBC 驱动程序当前不提供任何配置消息。 |
| FINE | 提供基本的跟踪信息，包括公共方法引发的所有异常。 |
| FINER | 提供详细的跟踪信息，包括具有相关参数数据类型的所有公共方法的进入点和退出点，以及公共类的所有公共属性。 此外，还包括输入参数、输出参数以及除 CLOB、BLOB、NCLOB、Reader 和 <stream> 返回值类型以外的方法返回值。 |
| 最佳 | 提供非常详细的跟踪信息。 该设置为最低日志记录级别。 |
| 关闭 | 关闭日志记录功能。 |
| 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 日志记录级别。 |
| 关闭 | 关闭日志记录功能。 |
| ALL | 启用所有消息的日志记录。 |
日志记录类别
创建 Logger 对象时，必须告知该对象你希望从中获取日志信息的命名实体或类别。 JDBC Driver 支持下列公共日志记录类别，这些日志记录类别都是在 com.microsoft.sqlserver.jdbc 驱动程序包中定义的。
| 名称 | 说明 |
|---|---|
| 连接 | 在 SQLServerConnection 类中记录消息。 应用程序可将日志记录级别设置为 FINER。 |
| 声明 | 在 SQLServerStatement 类中记录消息。 应用程序可将日志记录级别设置为 FINER。 |
| 数据源 | 在 SQLServerDataSource 类中记录消息。 应用程序可将日志记录级别设置为 FINE。 |
| 结果集 | 在 SQLServerResultSet 类中记录消息。 应用程序可将日志记录级别设置为 FINER。 |
| 驱动程序 | 在 SQLServerDriver 类中记录消息。 应用程序可将日志记录级别设置为 FINER。 |
| 复原 | 在 SQLServerConnection 类中记录仅与空闲连接复原重新连接相关的消息。 应用程序可将日志记录级别设置为 FINE 和 FINER。 |
| 重定向 | 在 SQLServerConnection 类中记录仅与连接打开重试相关的消息。 应用程序可将日志记录级别设置为 FINE。 |
从 Microsoft JDBC Driver 2.0 开始，JDBC Driver 还提供了 com.microsoft.sqlserver.jdbc.internals 包，后者包括对下列内部日志记录类别的日志记录支持。
| 名称 | 说明 |
|---|---|
| AuthenticationJNI | 记录有关 Windows 集成身份验证问题的信息（当authenticationScheme连接属性被隐式或显式设置为NativeAuthentication时）。 应用程序可将日志记录级别设置为 FINEST 和 FINE。 |
| SQLServerConnection | 在 SQLServerConnection 类中记录消息。 应用程序可将日志记录级别设置为 FINE 和 FINER。 |
| SQLServerDataSource | 在 SQLServerDataSource、SQLServerConnectionPoolDataSource 和 SQLServerPooledConnection 类中记录消息。 应用程序可将日志记录级别设置为 FINER。 |
| 输入流 | 记录有关下列数据类型的消息：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。 |
| 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 包内的标记，不如 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) 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
注意
使用 java.util.logging 中的 LogManager 对象可设置 logging.properties 文件中的属性。
性能指标日志记录
从版本 13.4.0 开始，驱动程序提供专用的性能指标记录器，用于跟踪连接和语句操作的时间。 与前面所述的诊断跟踪类别不同，这些记录器专为测量执行延迟而不是调试协议级别行为而设计。
有两个性能记录器可用：
| 记录器名称 | 说明 |
|---|---|
com.microsoft.sqlserver.jdbc.PerformanceMetrics.Connection |
跟踪连接、预登录、登录和令牌获取计时。 |
com.microsoft.sqlserver.jdbc.PerformanceMetrics.Statement |
跟踪语句请求构建、首次服务器响应、准备、prepexec 和执行的时间。 |
将这些记录器设置为 FINE 级别以启用指标输出。 您还可以为进程内的指标收集注册一个程序化回调函数，替代（或额外使用）日志输出。
从 13.6 版本开始，回调支持可选启用的纳秒级计时、SQL 文本和语句类型上下文，以及连接的应用程序名称。
有关配置详细信息、跟踪的活动和代码示例，请参阅 性能记录器和回调。