Rastreamento de operação do driver

Baixar driver JDBC

O Microsoft JDBC Driver para SQL Server é compatível com o uso de rastreamento (ou log) para ajudar a resolver problemas com o driver JDBC quando ele é usado em seu aplicativo. Para habilitar o uso de rastreamento, o driver JDBC usa as APIs de log no java.util.logging, que fornece um conjunto de classes para criar objetos Logger e LogRecord.

Observação

Para o componente nativo (sqljdbc_xa.dll) que está incluído com o driver JDBC, o rastreamento é habilitado pela estrutura de Diagnósticos Internos (BID). Para obter mais informações sobre BID, consulte Rastreamento do acesso a dados no SQL Server.

Quando você desenvolve seu aplicativo, pode fazer chamadas para objetos Logger, que, por sua vez, criam objetos LogRecord, que serão então passados aos objetos Handler para processamento. Ambos os objetos Logger e Handler usam níveis de log e, opcionalmente, filtros de log para regulamentar quais LogRecords são processados. Quando as operações de log estiverem concluídas, os objetos Handler poderão usar objetos Formatter como opção para publicar as informações de log.

Por padrão, a estrutura do java.util.logging grava sua saída em um arquivo. Este arquivo de log de saída deve ter permissões de gravação para o contexto sob o qual o driver JDBC está executando.

Observação

Para obter mais informações sobre como usar os vários objetos de log para rastreamento de programa, consulte a documentação do Java Logging APIs no site da Sun Microsystems.

As seções a seguir descrevem os níveis de log e as categorias que podem ser registradas em log, e fornecem informações sobre como habilitar rastreamento em seu aplicativo.

Níveis de log

Toda mensagem de log que é criada tem um nível de log associado. O nível de registro em log determina a importância da mensagem de log, que é definida pela classe Level em java.util.logging. Habilitar log em um nível também habilita log em todos os níveis mais altos. Esta seção descreve os níveis de log para categorias de log públicas e categorias de log internas. Para saber mais sobre categorias de log, consulte a seção Categorias de log neste artigo.

A tabela a seguir descreve cada nível de log disponível para categorias de log públicas.

Nome	Descrição
SEVERE	Indica uma falha séria e é o nível mais alto de log. No driver JDBC, este nível é usado para relatar erros e exceções.
WARNING	Indica um problema potencial.
INFO	Fornece mensagens informativas.
CONFIG	Fornece mensagens de configuração. O driver JDBC atualmente não fornece nenhuma mensagem de configuração.
FINE	Fornece informações básicas de rastreamento inclusive todas as exceções lançadas pelos métodos públicos.
FINER	Fornece informações de rastreamento detalhadas inclusive todas as entradas de método público e pontos de saída com tipos de dados de parâmetro associados e todas as propriedades públicas para classes públicas. Além disso, os parâmetros de entrada, os parâmetros de saída e o método retornam valores, exceto os tipos de valores retornados CLOB, BLOB, NCLOB, Reader, <stream>.
FINEST	Fornece informações de rastreamento altamente detalhadas. Esta configuração é o nível mais baixo de registrar em log.
OFF	Desliga o log.
ALL	Habilita log de todas as mensagens.

A tabela a seguir descreve cada nível de log disponível para as categorias de log internas.

Nome	Descrição
SEVERE	Indica uma falha séria e é o nível mais alto de log. No driver JDBC, este nível é usado para relatar erros e exceções.
WARNING	Indica um problema potencial.
INFO	Fornece mensagens informativas.
FINE	Fornece informações de rastreamento que incluem criação e destruição básicas de objeto. Além disso, todas as exceções lançadas pelos métodos públicos.
FINER	Fornece informações de rastreamento detalhadas inclusive todas as entradas de método público e pontos de saída com tipos de dados de parâmetro associados e todas as propriedades públicas para classes públicas. Além disso, os parâmetros de entrada, os parâmetros de saída e o método retornam valores, exceto os tipos de valores retornados CLOB, BLOB, NCLOB, Reader, <stream>. As seguintes categorias de log existiam na versão 1.2 do JDBC Driver e tinham o nível de registros em log FINE: SQLServerConnection, SQLServerStatement, XA e SQLServerDataSource. Desde a versão 2.0, estas categorias são atualizadas para o nível FINER.
FINEST	Fornece informações de rastreamento altamente detalhadas. Esta configuração é o nível mais baixo de registrar em log. As seguintes categorias de log existiam na versão 1.2 do JDBC Driver e tinham o nível de registros em log FINEST: TDS.DATA e TDS.TOKEN. Desde a versão 2.0, eles mantêm o nível de log FINEST.
OFF	Desliga o log.
ALL	Habilita log de todas as mensagens.

Categorias de log

Ao criar um objeto Logger, você deve dizer a ele sobre qual entidade ou categoria nomeada você está interessado em obter informações de log. O driver JDBC suporta as categorias de log públicas a seguir, que estão todas definidas no pacote do driver com.microsoft.sqlserver.jdbc.

Nome	Descrição
Conexão	Registra em log mensagens na classe SQLServerConnection. Os aplicativos podem definir o nível de log como FINER.
de	Registra em log mensagens na classe SQLServerStatement. Os aplicativos podem definir o nível de log como FINER.
DataSource	Registra mensagens em log na classe SQLServerDataSource. Os aplicativos podem definir o nível de log como FINE.
ResultSet	Registra em log mensagens na classe SQLServerResultSet. Os aplicativos podem definir o nível de log como FINER.
Driver	Registra em log mensagens na classe SQLServerDriver. Os aplicativos podem definir o nível de log como FINER.
Resiliência	Registra mensagens na classe SQLServerConnection relacionadas somente a reconexões de resiliência de conexão ociosa. Os aplicativos podem definir o nível de log como FINE e FINER.
Redirecionamento	Registra mensagens na classe SQLServerConnection relacionadas somente a tentativas abertas de conexão. Os aplicativos podem definir o nível de log como FINE.

A partir do Microsoft JDBC Driver versão 2.0, o driver também fornece o pacote com.microsoft.sqlserver.jdbc.internals, que inclui o suporte de log para as categorias de log internas a seguir.

Nome	Descrição
AuthenticationJNI	Registra mensagens em log sobre problemas de autenticação integrada no Windows (quando a propriedade de conexão authenticationScheme está definida de maneira implícita ou explícita como NativeAuthentication). Os aplicativos podem definir o nível de log como FINEST e FINE.
SQLServerConnection	Registra em log mensagens na classe SQLServerConnection. Os aplicativos podem definir o nível de log como FINE e FINER.
SQLServerDataSource	Registra mensagens em log nas classes SQLServerDataSource, SQLServerConnectionPoolDataSource e SQLServerPooledConnection. Os aplicativos podem definir o nível de log como FINER.
InputStream	Registra mensagens em logs sobre os seguintes tipos de dados: java.io.InputStream, java.io.Reader e os tipos de dados que têm um especificador máx como tipos de dados varchar, nvarchar e varbinary. Os aplicativos podem definir o nível de log como FINER.
SQLServerException	Registra mensagens em log na classe SQLServerException. Os aplicativos podem definir o nível de log como FINE.
SQLServerResultSet	Registra em log mensagens na classe SQLServerResultSet. Os aplicativos podem definir o nível de log como FINE, FINER e FINEST.
SQLServerStatement	Registra em log mensagens na classe SQLServerStatement. Os aplicativos podem definir o nível de log como FINE, FINER e FINEST.
XA	Registra mensagens para todas as transações XA na classe SQLServerXADataSource. Os aplicativos podem definir o nível de log como FINE e FINER.
KerbAuthentication	Registra mensagens em log sobre a autenticação Kerberos tipo 4 (quando a propriedade de conexão authenticationScheme está definida como JavaKerberos). O aplicativo pode definir o nível de log como FINE ou FINER.
TDS.DATA	Registra mensagens que contêm a conversa no nível do protocolo TDS entre o driver e o SQL Server. O conteúdo detalhado de cada pacote TDS enviado e recebido é registrado em ASCII e hexadecimal. As credenciais de logon (nomes de usuários e senhas) não são registradas. Todos os outros dados são registrados. Esta categoria cria mensagens muito detalhadas e detalhadas, e só poderá ser habilitada definindo o nível de registro como FINEST.
TDS.Channel	Esta categoria rastreia ações do canal de comunicação TCP com SQL Server. As mensagens registradas incluem abertura e fechamento de soquete, além de leituras e gravações. Elas também rastreiam mensagens relacionadas ao estabelecimento de uma conexão TLS, anteriormente conhecido como SSL, com o SQL Server. Esta categoria só poderá ser habilitada definindo o nível de log como FINE, FINER ou FINEST.
TDS.Writer	Esta categoria rastreia gravações no canal de TDS. Somente o comprimento das gravações é rastreado, não o conteúdo. Esta categoria também rastreia problemas quando um sinal de atenção é enviado ao servidor para cancelar a execução de uma instrução. Esta categoria só poderá ser habilitada definindo o nível de log como FINEST.
TDS.Reader	Esta categoria rastreia determinadas operações de leitura do canal de TDS no nível FINEST. No nível FINEST, o rastreamento pode ser detalhado. Nos níveis WARNING e SEVERE, esta categoria rastreia quando o driver recebe um protocolo TDS inválido do SQL Server antes de o driver fechar a conexão. Esta categoria só poderá ser habilitada definindo o nível de log como FINER e FINEST.
TDS.Command	Esta categoria rastreia transições de estado de baixo nível e outras informações associadas à execução de comandos TDS, como execuções de instrução Transact-SQL, buscas do cursor ResultSet, confirmações e assim por diante. Esta categoria só poderá ser habilitada definindo o nível de log como FINEST.
TDS.TOKEN	Esta categoria registra somente os tokens dentro dos pacotes TDS e é menos detalhada que a categoria TDS.DATA. Ela só poderá ser habilitada definindo o nível de log como FINEST. No nível FINEST, esta categoria rastreia tokens de TDS à medida que eles são processados na resposta. No nível SEVERE, esta categoria rastreia quando um token de TDS inválido é encontrado.
SQLServerDatabaseMetaData	Registra mensagens em log na classe SQLServerDatabaseMetaData. Os aplicativos podem definir o nível de log como FINE.
SQLServerResultSetMetaData	Registra mensagens em log na classe SQLServerResultSetMetaData. Os aplicativos podem definir o nível de log como FINE.
SQLServerParameterMetaData	Registra mensagens em log na classe SQLServerParameterMetaData. Os aplicativos podem definir o nível de log como FINE.
SQLServerBlob	Registra mensagens em log na classe SQLServerBlob. Os aplicativos podem definir o nível de log como FINE.
SQLServerClob	Registra mensagens em log na classe SQLServerClob. Os aplicativos podem definir o nível de log como FINE.
SQLServerSQLXML	Registra mensagens em log na classe SQLServerSQLXML interna. Os aplicativos podem definir o nível de log como FINE.
SQLServerDriver	Registra em log mensagens na classe SQLServerDriver. Os aplicativos podem definir o nível de log como FINE.
SQLServerNClob	Registra mensagens em log na classe SQLServerNClob. Os aplicativos podem definir o nível de log como FINE.

Habilitando o rastreamento programaticamente

O rastreamento pode ser habilitado programaticamente criando um objeto Logger e indicando a categoria a ser registrada. Por exemplo, o código a seguir mostra como habilitar log para instruções SQL:

Logger logger = Logger.getLogger("com.microsoft.sqlserver.jdbc.Statement");
logger.setLevel(Level.FINER);

No seu código, para desabilitar o registro em log, use o seguinte código:

logger.setLevel(Level.OFF);

Para registrar todas as categorias disponíveis, use o seguinte código:

Logger logger = Logger.getLogger("com.microsoft.sqlserver.jdbc");
logger.setLevel(Level.FINE);

Para desabilitar uma categoria específica de ser registrada, use o seguinte código:

Logger logger = Logger.getLogger("com.microsoft.sqlserver.jdbc.Statement");
logger.setLevel(Level.OFF);

Habilitando rastreamento usando o arquivo logging.properties

Você também pode habilitar rastreamento usando o arquivo logging.properties, que está localizado no diretório lib da instalação do JRE (Java Runtime Environment) 8 ou na pasta conf para Java 9 e posterior. Este arquivo poderá ser usado para definir os valores padrão para agentes e manipuladores que serão usados quando o rastreamento for habilitado.

A seguinte configuração é um exemplo das configurações que você pode fazer nos arquivos 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

Observação

Você pode definir as propriedades no arquivo logging.properties usando o objeto LogManager que faz parte de java.util.logging.

Confira também

Diagnosticando problemas com o JDBC Driver