Rastreamento de operação do driver

Baixar o JDBC Driver

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.

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.

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.

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

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.

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.

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

Confira também

Diagnosticando problemas com o JDBC Driver