Трассировка операций драйвера
Драйвер Microsoft JDBC для SQL Server поддерживает использование трассировки (или ведения журнала) для устранения проблем и проблем с драйвером JDBC при его использовании в приложении. Чтобы включить использование трассировки, драйвер JDBC использует интерфейсы API ведения журнала в java.util.logging, который обеспечивает набор классов для создания объектов Logger и LogRecord.
Примечание.
Для собственного компонента (sqljdbc_xa.dll), который включен в комплект драйвера JDBC, трассировка включается стандартом BID. Дополнительные сведения о BID см. в статье Трассировка доступа к данным в SQL Server.
При разработке приложения вы можете выполнять вызовы объектов Logger, которые в свою очередь создают объекты LogRecord, передаваемые затем объектам Handler для обработки. Объекты Logger и Handler используют уровни ведения журнала и, при необходимости, фильтры ведения журнала для регулирования обрабатываемых записей журнала (LogRecord). Когда операции ведения журнала завершены, объекты Handler могут также использовать объекты Formatter для публикации данных журнала.
По умолчанию, среда java.util.logging записывает выходные данные в файл. Файл журнала с выходными данными должен иметь разрешения записи для контекста, в рамках которого работает драйвер JDBC.
Примечание.
Дополнительные сведения об использовании различных объектов ведения журнала для отслеживания программ см. в разделе API-интерфейсы ведения журнала Java документации на веб-сайте Sun Microsystems.
В следующих разделах приводится описание уровней ведения журнала и категорий, которые могут быть занесены в журнал, а также включение трассировки в приложении.
Уровни ведения журнала
Каждое создаваемое сообщение журнала имеет связанный уровень ведения журнала. Уровень ведения журнала определяет важность сообщения журнала, которая задается классом Level в java.util.logging. Включение ведения журнала на одном уровне также включает ведение журнала на всех более высоких уровнях. В данном разделе приводится описание уровней ведения журнала как для открытых категорий ведения журнала, так и для внутренних. Дополнительные сведения о категориях ведения журнала см. в разделе "Категории ведения журнала" этой статьи.
В следующей таблице приводится описание каждого из доступных уровней ведения журнала для открытых категорий ведения журнала.
| Имя | Описание |
|---|---|
| SEVERE | Указывает серьезный сбой и имеет самый высокий уровень ведения журнала. В драйвере JDBC этот уровень используется для выдачи ошибок и исключений. |
| ПРЕДУПРЕЖДЕНИЕ | Указывает на возможную проблему. |
| INFO | Предоставляет информационные сообщения. |
| CONFIG | Предоставляет сообщения о конфигурации. Драйвер JDBC сейчас не предоставляет сообщений о конфигурации. |
| FINE | Обеспечивает базовую информацию об отслеживании, включая все исключения, возникшие по вине открытых методов. |
| FINER | Предоставляет подробные данные трассировки, включая все входные и выходные точки открытых методов с типами данных связанных параметров, а также все открытые свойства для открытых классов. Кроме этого, входные и выходные параметры и значения, возвращенные методами, кроме возвращаемых значений <потоковых> типов CLOB, BLOB, NCLOB, Reader. |
| FINEST | Обеспечивает наивысший уровень детализации данных трассировки. Этот вариант дает самый низкий уровень ведения журнала. |
| ВЫКЛ. | Отключает ведение журнала. |
| ВСЕ | Включает регистрацию в журнале всех сообщений. |
В следующей таблице приводится описание каждого из доступных уровней ведения журнала для внутренних категорий ведения журнала.
| Имя | Описание |
|---|---|
| SEVERE | Указывает серьезный сбой и имеет самый высокий уровень ведения журнала. В драйвере JDBC этот уровень используется для выдачи ошибок и исключений. |
| ПРЕДУПРЕЖДЕНИЕ | Указывает на возможную проблему. |
| INFO | Предоставляет информационные сообщения. |
| FINE | Обеспечивает информацию о трассировке, включая создание и удаление базового объекта. Помимо этого, информирует обо всех исключениях, возникших из-за открытых методов. |
| FINER | Предоставляет подробные данные трассировки, включая все входные и выходные точки открытых методов с типами данных связанных параметров, а также все открытые свойства для открытых классов. Кроме этого, входные и выходные параметры и значения, возвращенные методами, кроме возвращаемых значений <потоковых> типов CLOB, BLOB, NCLOB, Reader. Указанные ниже категории ведения журнала существовали в версии 1.2 драйвера JDBC и имели уровень ведения журнала FINE: SQLServerConnection, SQLServerStatement, XA и SQLServerDataSource. Начиная с версии 2.0, эти категории обновлены до уровня FINER. |
| FINEST | Обеспечивает наивысший уровень детализации данных трассировки. Этот вариант дает самый низкий уровень ведения журнала. Следующие категории ведения журнала существовали в версии 1.2 драйвера JDBC и имели уровень ведения журнала FINEST: TDS.DATA и TDS.TOKEN. Начиная с версии 2.0, эти категории сохраняют уровень ведения журнала FINEST. |
| ВЫКЛ. | Отключает ведение журнала. |
| ВСЕ | Включает регистрацию в журнале всех сообщений. |
Категории ведения журнала
При создании объекта Logger следует указать именованную сущность или категорию, из которой нужно получать сведения журнала. Драйвер JDBC поддерживает следующие открытые категории ведения журнала, определенные в пакете драйвера com.microsoft.sqlserver.jdbc.
| Имя | Описание |
|---|---|
| Connection | Регистрирует сообщения в классе SQLServerConnection. Приложение может задать уровень ведения журнала FINER. |
| Оператор | Регистрирует сообщения в классе SQLServerStatement. Приложение может задать уровень ведения журнала FINER. |
| DataSource | Регистрирует сообщения в классе SQLServerDataSource. Приложение может задать уровень ведения журнала FINE. |
| ResultSet | Регистрирует сообщения в классе SQLServerResultSet. Приложение может задать уровень ведения журнала FINER. |
| Драйвер | Регистрирует сообщения в классе SQLServerDriver. Приложение может задать уровень ведения журнала FINER. |
| Устойчивость | Регистрирует сообщения в классе SQLServerConnection , относящиеся только к повторному подключению к неактивным подключениям. Приложение может задать уровень ведения журнала FINE и FINER. |
| Перенаправление | Регистрирует сообщения в классе SQLServerConnection , относящиеся только к открытым повторным попыткам подключения. Приложение может задать уровень ведения журнала FINE. |
Начиная с версии 2.0 драйвера Microsoft JDBC, драйвер также обеспечивает пакет 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 | Регистрирует сообщения для всех транзакций XA в классе SQLServerXADataSource. Приложение может задать уровень ведения журнала FINE и FINER. |
| KerbAuthentication | Записывает сообщения о проверке подлинности Kerberos типа 4 (когда для свойства подключения authenticationScheme установлено значение JavaKerberos). Приложение может задать уровень ведения журнала FINE или FINER. |
| TDS.DATA | Регистрирует сообщения, содержащие диалог на уровне протокола TDS между драйвером и SQL Server. Подробное содержимое каждого отправленного и полученного пакета TDS вносится в журнал в виде значений ASCII или шестнадцатеричных значений. Учетные данные для входа (имена пользователей и пароли) не вносятся в журнал. Все остальные данные записываются в журнал. Данная категория создает очень длинные и подробные сообщения, ее можно включить, только если установить уровень ведения журнала на FINEST. |
| TDS.Channel | Данная категория отслеживает действия канала связи TCP с SQL Server. Вносимые в журнал сообщения включают открытие и закрытие сокета, а также операции считывания и записи. Категория также отслеживает сообщения, связанные с установкой соединения TLS, ранее называемого SSL, с SQL Server. Эта категория может быть включена, если установить уровень ведения журнала на FINE, FINER или FINEST. |
| TDS.Writer | Эта категория отслеживает операции записи в канал TDS. Отслеживается только длина записей, но не их содержимое. Данная категория также отслеживает отправку сигнала на сервер, запрашивающего отмену выполнения инструкции. Эта категория может быть включена только установкой уровня ведения журнала FINEST. |
| TDS.Reader | Данная категория отслеживает операции считывания из канала TDS на уровне FINEST. На уровне FINEST отслеживание может быть подробным. На уровнях WARNING и SEVERE данная категория отслеживает получение драйвером недействительного протокола TDS от SQL Server до того, как драйвер закроет соединение. Эта категория может быть включена, если установить уровень ведения журнала на 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 файла, который можно найти в lib каталоге установки среды выполнения Java (JRE) 8 или conf папки для Java 9 и более поздних версий. Файл может быть использован для установки значений по умолчанию для журналов и обработчиков, которые будут использованы, если трассировка включена.
Далее приведен пример конфигурации, которую можно задать в файлах 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
Примечание.
Свойства можно задать в файлеlogging.properties с помощью объекта LogManager, который является частью java.util.logging.