Monitorização da operação do driver

Baixar driver JDBC

O Microsoft JDBC Driver para SQL Server suporta o uso de rastreamento (ou logging) para ajudar na resolução de questões e problemas com o driver JDBC quando é usado na sua aplicação. Para permitir o uso do rastreamento, o driver JDBC utiliza as APIs de registo em 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 no driver JDBC, o rastreio é ativado pelo framework Built-In Diagnostics (BID). Para informações sobre BID, consulte Rastreamento de Acesso a Dados no SQL Server.

Quando desenvolves a tua aplicação, podes fazer chamadas para objetos Logger, que por sua vez criam objetos LogRecord, que são depois passados para objetos Handler para processamento. Os objetos Logger e Handler usam ambos os níveis de registo e, opcionalmente, filtros de registo para regular quais os registros (LogRecords) são processados. Quando as operações de registo estão concluídas, os objetos Handler podem opcionalmente usar objetos Formatter para publicar a informação de registo.

Por padrão, o framework java.util.logging escreve a sua saída num ficheiro. Este ficheiro de registo de saída deve ter permissões de escrita para o contexto em que o driver JDBC está a correr.

Observação

Para mais informações sobre a utilização dos vários objetos de registo para rastreamento de programas, consulte a documentação Java Logging APIs no site da Sun Microsystems.

As secções seguintes descrevem os níveis de registo e as categorias que podem ser registadas, fornecendo informações sobre como ativar o rastreio na sua aplicação.

Níveis de registo

Cada mensagem de registo criada tem um nível de registo associado. O nível de registo determina a importância da mensagem de registo, que é definida pela classe Level em java.util.logging. Permitir o registo a um nível também permite o registo em todos os níveis superiores. Esta secção descreve os níveis de registo tanto para categorias públicas como para as categorias internas. Para mais informações sobre as categorias de registo, consulte a secção Categorias de Registo neste artigo.

A tabela seguinte descreve cada um dos níveis de registo disponíveis para categorias públicas de registo de eventos.

Nome	Description
GRAVE	Indica uma falha grave e é o nível mais elevado de exploração florestal. No driver JDBC, este nível é usado para reportar erros e exceções.
ADVERTÊNCIA	Indica um potencial problema.
INFORMAÇÃO	Fornece mensagens informativas.
CONFIGURAÇÃO	Fornece mensagens de configuração. O driver JDBC atualmente não fornece quaisquer mensagens de configuração.
MULTA	Fornece informações básicas de rastreamento, incluindo todas as exceções lançadas pelos métodos públicos.
FINER	Fornece informações detalhadas de rastreamento, incluindo todos os pontos de entrada e saída de métodos públicos com os tipos de dados dos parâmetros associados, assim como todas as propriedades públicas das classes disponíveis ao público. Além disso, parâmetros de entrada, parâmetros de saída e valores de retorno de métodos, exceto CLOB, BLOB, NCLOB, Reader, <tipos de retorno de fluxo> .
Mais Fino	Fornece informações de rastreamento altamente detalhadas. Esta configuração é o nível mais baixo de registo.
DESLIGADO	Desativa o registo.
ALL	Permite o registo de todas as mensagens.

A tabela seguinte descreve cada um dos níveis de registo disponíveis para as categorias internas de registo.

Nome	Description
GRAVE	Indica uma falha grave e é o nível mais elevado de exploração florestal. No driver JDBC, este nível é usado para reportar erros e exceções.
ADVERTÊNCIA	Indica um potencial problema.
INFORMAÇÃO	Fornece mensagens informativas.
MULTA	Fornece informações de rastreamento, incluindo criação e destruição básica de objetos. Além disso, todas as exceções lançadas pelos métodos públicos.
FINER	Proporciona informações detalhadas de rastreio, incluindo todos os pontos de entrada e saída dos métodos públicos com os tipos de dados dos parâmetros associados, bem como todas as propriedades públicas das classes públicas. Além disso, parâmetros de entrada, parâmetros de saída e valores de retorno de métodos, exceto CLOB, BLOB, NCLOB, Reader, <tipos de retorno de fluxo> . As seguintes categorias de registo existiam na versão 1.2 do driver JDBC e tinham o nível de registo FINE: SQLServerConnection, SQLServerStatement, XA e SQLServerDataSource. A partir da versão 2.0, estas categorias são atualizadas para o nível FINER.
Mais Fino	Fornece informações de rastreamento altamente detalhadas. Esta configuração é o nível mais baixo de registo. As seguintes categorias de registo existiam na versão 1.2 do driver JDBC e tinham o nível de registo FINEST: TDS. DADOS e TDS. TOKEN. A partir da versão 2.0, mantêm o nível de registo FINEST.
DESLIGADO	Desativa o registo.
ALL	Permite o registo de todas as mensagens.

Categorias de Registo

Quando cria um objeto Logger, deve indicar ao objeto qual entidade ou categoria nomeada está interessado em obter informação de log. O driver JDBC suporta as seguintes categorias de registo público, todas definidas no pacote de drivers com.microsoft.sqlserver.jdbc.

Nome	Description
Connection	Regista mensagens na classe SQLServerConnection . As aplicações podem definir o nível de registo como FINER.
Statement	Regista mensagens na classe SQLServerStatement . As aplicações podem definir o nível de registo como FINER.
Fonte de dados	Regista mensagens na classe SQLServerDataSource . As aplicações podem definir o nível de registo como FINE.
Conjunto de Resultados	Regista mensagens na classe SQLServerResultSet . As aplicações podem definir o nível de registo como FINER.
Driver	Regista mensagens na classe SQLServerDriver . As aplicações podem definir o nível de registo como FINER.
Resiliency	Regista mensagens na classe SQLServerConnection relacionadas apenas com a resiliência de reconexão de ligações inativas. As aplicações podem definir o nível de registo como FINE e FINER.
Redirection	Regista mensagens na classe SQLServerConnection apenas relacionadas com tentativas abertas de ligação. As aplicações podem definir o nível de registo 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 suporte para registos para as seguintes categorias internas de registo.

Nome	Description
AutenticaçãoJNI	Regista mensagens sobre os problemas de autenticação integrada no Windows (quando a propriedade de ligação authenticationScheme está implícita ou explicitamente definida como NativeAuthentication). As aplicações podem definir o nível de registo como FINEST e FINE.
SQLServerConnection	Regista mensagens na classe SQLServerConnection . As aplicações podem definir o nível de registo como FINE e FINER.
SQLServerDataSource	Regista mensagens nas classes SQLServerDataSource, SQLServerConnectionPoolDataSource e SQLServerPooledConnection . As aplicações podem definir o nível de registo como FINER.
Fluxo de Entrada	Regista mensagens sobre os seguintes tipos de dados: java.io.InputStream, java.io.Reader e os tipos de dados, que têm um especificador máximo como varchar, nvarchar e varbinary. As aplicações podem definir o nível de registo como FINER.
SQLServerException	Regista mensagens na classe SQLServerException . As aplicações podem definir o nível de registo como FINE.
SQLServerResultSet	Regista mensagens na classe SQLServerResultSet . As aplicações podem definir o nível de registo como FINE, FINER e FINEST.
SQLServerStatement	Regista mensagens na classe SQLServerStatement . As aplicações podem definir o nível de registo como FINE, FINER e FINEST.
XA	Regista mensagens para todas as transações XA na classe SQLServerXADataSource . As aplicações podem definir o nível de registo como FINE e FINER.
KerbAuthentication	Regista mensagens sobre autenticação tipo 4 Kerberos (quando a propriedade de ligação authenticationScheme está definida para JavaKerberos). A aplicação pode definir o nível de registo como FINE ou FINER.
TDS. DADOS	Regista mensagens que contêm a conversa ao nível do protocolo TDS entre o driver e o SQL Server. O conteúdo detalhado de cada pacote TDS enviado e recebido está registado em ASCII e hexadecimal. As credenciais de login (nomes de utilizador e palavras-passe) não são registadas. Todos os outros dados são registados. Esta categoria cria mensagens muito detalhadas e extensas, e só pode ser ativada definindo o nível de registo para FINEST.
TDS. Canal	Esta categoria acompanha as ações do canal de comunicações TCP com o SQL Server. As mensagens registadas incluem abertura e fecho de sockets, bem como leituras e escritas. Também rastreia mensagens relacionadas com o estabelecimento de uma ligação Transport Layer Security (TLS), anteriormente conhecida como Secure Sockets Layer (SSL), com SQL Server. Esta categoria só pode ser ativada definindo o nível de registo para FINE, FINNER ou FINEST.
TDS. Escritor	Esta categoria rastreia as escritas até ao canal TDS. Apenas o comprimento das escritas é rastreado, não o conteúdo. Esta categoria também identifica problemas quando um sinal de atenção é enviado ao servidor para cancelar a execução de uma declaração. Esta categoria só pode ser ativada definindo o nível de registo para FINEST.
TDS.Reader	No nível FINEST, esta categoria rastreia certas operações de leitura a partir do canal TDS. Ao MAIS ALTO nível, o traçado pode ser prolixo. Nos níveis WARNING e SEVERE, esta categoria rastreia quando o driver recebe um protocolo TDS inválido do SQL Server antes do driver encerrar a ligação. Esta categoria só pode ser ativada definindo o nível de registo para FINER e FINEST.
TDS.Command	Esta categoria traça transições de estado de baixo nível e outras informações associadas à execução de comandos TDS, como execuções de Transact-SQL sentenças, buscas de cursor ResultSet, commits, entre outros. Esta categoria só pode ser ativada definindo o nível de registo para FINEST.
TDS. TOKEN	Esta categoria regista apenas os tokens dentro dos pacotes TDS e é menos prolixa do que a categoria TDS.DADOS. Só pode ser ativado definindo o nível de registo para FINEST. Ao nível FINEST, esta categoria rastreia os tokens TDS à medida que são processados na resposta. Ao nível SEVERE, esta categoria rastreia quando é encontrado um token TDS inválido.
SQLServerDatabaseMetaData	Regista mensagens na classe SQLServerDatabaseMetaData . As aplicações podem definir o nível de registo como FINE.
SQLServerResultSetMetaData	Regista mensagens na classe SQLServerResultSetMetaData . As aplicações podem definir o nível de registo como FINE.
SQLServerParameterMetaData	Regista mensagens na classe SQLServerParameterMetaData . As aplicações podem definir o nível de registo como FINE.
SQLServerBlob	Regista mensagens na classe SQLServerBlob . As aplicações podem definir o nível de registo como FINE.
SQLServerClob	Regista mensagens na classe SQLServerClob . As aplicações podem definir o nível de registo como FINE.
SQLServerSQLXML	Regista mensagens na classe interna SQLServerSQLXML. As aplicações podem definir o nível de registo como FINE.
SQLServerDriver	Regista mensagens na classe SQLServerDriver . As aplicações podem definir o nível de registo como FINE.
SQLServerNClob	Regista mensagens na classe SQLServerNClob . As aplicações podem definir o nível de registo como FINE.

Permitir o rastreamento programaticamente

O rastreamento pode ser ativado programaticamente criando um objeto Logger e indicando a categoria a registar. Por exemplo, o seguinte código mostra como ativar o registo para instruções SQL:

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

Para desativar o login no seu código, use o seguinte código:

logger.setLevel(Level.OFF);

Para registar todas as categorias disponíveis, utilize o seguinte código:

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

Para desativar o registo de uma categoria específica, use o seguinte código:

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

Ativar o traçado usando o ficheiro logging.properties

Também pode ativar o rastreamento usando o logging.properties ficheiro, que pode ser encontrado na lib pasta da sua instalação do Java Runtime Environment (JRE) 8 ou na conf pasta para Java 9 e superiores. Este ficheiro pode ser usado para definir os valores predefinidos dos loggers e handlers que serão usados quando o rastreamento estiver ativado.

A configuração seguinte é um exemplo das definições que pode fazer nos logging.properties ficheiros:

# 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

Podes definir as propriedades no logging.properties ficheiro usando o objeto LogManager, que faz parte do java.util.logging.

Consulte também

Diagnóstico de problemas com o driver JDBC