Примечание.
Для доступа к этой странице требуется авторизация. Вы можете попробовать войти или изменить каталоги.
Для доступа к этой странице требуется авторизация. Вы можете попробовать изменить каталоги.
Драйвер 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. Включение логгирования на одном уровне также включает логгирование на всех более высоких уровнях. В данном разделе приводится описание уровней ведения журнала как для открытых категорий ведения журнала, так и для внутренних. Смотрите раздел "Категории ведения журнала" в этой статье для получения дополнительной информации о категориях ведения журнала.
В следующей таблице приводится описание каждого из доступных уровней ведения журнала для открытых категорий ведения журнала.
| Имя | Описание |
|---|---|
| СЕРЬЕЗНЫЙ | Указывает на серьезный сбой, и имеет самый высокий уровень логирования. В драйвере JDBC этот уровень используется для выдачи ошибок и исключений. |
| ПРЕДУПРЕЖДЕНИЕ | Указывает на возможную проблему. |
| Информация | Предоставляет информационные сообщения. |
| Конфигурация | Предоставляет сообщения о конфигурации. Драйвер JDBC сейчас не предоставляет сообщений о конфигурации. |
| FINE | Обеспечивает базовую информацию об отслеживании, включая все исключения, возникшие по вине открытых методов. |
| FINER | Предоставляет подробные данные трассировки, включая все входные и выходные точки открытых методов с типами данных связанных параметров, а также все открытые свойства для открытых классов. Кроме этого, входные параметры, выходные параметры и значения, возвращаемые методами, за исключением случаев, когда возвращаемые значения имеют типы CLOB, BLOB, NCLOB, Reader, <stream>. |
| Наилучший | Обеспечивает наивысший уровень детализации данных трассировки. Эта настройка обеспечивает самый низкий уровень журналирования. |
| ВЫКЛ. | Отключает ведение журнала. |
| ВСЕ | Включает регистрацию в журнале всех сообщений. |
В следующей таблице приводится описание каждого из доступных уровней ведения журнала для внутренних категорий ведения журнала.
| Имя | Описание |
|---|---|
| СЕРЬЕЗНЫЙ | Указывает на серьезный сбой, и имеет самый высокий уровень логирования. В драйвере JDBC этот уровень используется для выдачи ошибок и исключений. |
| ПРЕДУПРЕЖДЕНИЕ | Указывает на возможную проблему. |
| Информация | Предоставляет информационные сообщения. |
| FINE | Обеспечивает информацию о трассировке, включая создание и уничтожение основных объектов. Помимо этого, информирует обо всех исключениях, возникших из-за открытых методов. |
| FINER | Предоставляет подробные данные трассировки, включая все входные и выходные точки открытых методов с типами данных связанных параметров, а также все открытые свойства для открытых классов. Кроме этого, входные параметры, выходные параметры и значения, возвращаемые методами, за исключением случаев, когда возвращаемые значения имеют типы CLOB, BLOB, NCLOB, Reader, <stream>. Указанные ниже категории ведения журнала существовали в версии 1.2 драйвера JDBC и имели уровень ведения журнала FINE: SQLServerConnection, SQLServerStatement, XA и SQLServerDataSource. Начиная с версии 2.0, эти категории обновлены до уровня FINER. |
| Наилучший | Обеспечивает наивысший уровень детализации данных трассировки. Эта настройка обеспечивает самый низкий уровень журналирования. Следующие категории ведения журнала существовали в версии 1.2 драйвера JDBC и имели уровень ведения журнала FINEST: TDS.DATA и TDS.TOKEN. Начиная с версии 2.0, они сохраняют уровень журналирования FINEST. |
| ВЫКЛ. | Отключает ведение журнала. |
| ВСЕ | Включает регистрацию в журнале всех сообщений. |
Категории журналирования
При создании объекта Logger следует указать именованную сущность или категорию, из которой нужно получать сведения журнала. Драйвер JDBC поддерживает следующие открытые категории ведения журнала, определенные в пакете драйвера com.microsoft.sqlserver.jdbc.
| Имя | Описание |
|---|---|
| Соединение | Регистрирует сообщения в классе SQLServerConnection. Приложение может задать уровень ведения журнала FINER. |
| Заявление | Регистрирует сообщения в классе SQLServerStatement. Приложения могут задать уровень логирования FINER. |
| Источник данных | Регистрирует сообщения в классе SQLServerDataSource. Приложения могут задать уровень логирования FINE. |
| РезалтСет | Регистрирует сообщения в классе 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. |
| ПотокВвода | Регистрирует сообщения о следующих типах данных: 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. Вносимые в журнал сообщения включают открытие и закрытие сокета, а также операции считывания и записи. Кроме того, она отслеживает сообщения, связанные с установлением соединения Transport Layer Security (TLS), ранее известного как Secure Sockets Layer (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.
Ведение журнала метрик производительности
Начиная с версии 13.4.0 драйвер предоставляет выделенные средства ведения журнала метрик производительности, отслеживающие время операций подключения и инструкций. В отличие от категорий диагностической трассировки, описанных ранее, эти логгеры предназначены специально для измерения задержки выполнения, а не для отладки поведения на уровне протокола.
Доступны два средства ведения журнала производительности:
| Имя логгера | Описание |
|---|---|
com.microsoft.sqlserver.jdbc.PerformanceMetrics.Connection |
Отслеживает время подключения, предварительного входа, входа и получения токена. |
com.microsoft.sqlserver.jdbc.PerformanceMetrics.Statement |
Отслеживает сборку запроса инструкции, первый ответ сервера, подготовку, prepexec и время выполнения. |
Установите эти журналы на уровень FINE, чтобы включить вывод метрик. Вы также можете зарегистрировать программируемый обратный вызов для сбора метрик в процессе выполнения вместо вывода в журнал (или в дополнение к нему).
Сведения о конфигурации, отслеживаемые действия и примеры кода см. в разделе "Журнал производительности" и "Обратный вызов".