Compartilhar via

Registrador de desempenho e callback

Baixar JDBC Driver

A partir da versão 13.4, o Microsoft JDBC Driver for SQL Server fornece uma estrutura de métricas de desempenho para acompanhar o tempo das operações críticas do driver. Você pode usar essa estrutura para observar e analisar o comportamento de execução de conexão e instrução, ajudando a identificar gargalos de latência nas interações do aplicativo com o SQL Server.

As métricas estão disponíveis por meio de dois mecanismos que podem ser usados de forma independente ou em conjunto:

  • Retorno de chamada programático – registre um PerformanceLogCallback para receber métricas no código da aplicação.
  • Log do Java – Assine os registradores dedicados java.util.logging para capturar métricas na saída de log.

Atividades controladas

O driver controla as atividades em dois níveis: conexão e instrução.

Atividades no nível da conexão

Atividade Descrição
CONNECTION Tempo total para estabelecer uma conexão, incluindo todas as subatividades.
PRELOGIN Tempo de negociação de pré-login do TDS com o servidor.
LOGIN Hora do logon e autenticação do TDS por handshake.
TOKEN_ACQUISITION Hora de adquirir tokens de autenticação federados ao usar a autenticação do Microsoft Entra.

Atividades no nível da declaração

Atividade Descrição
STATEMENT_REQUEST_BUILD Tempo do cliente para construir a solicitação TDS (associação de parâmetros, processamento de SQL, construção de pacotes). Apenas tempo; não rastreia exceções.
STATEMENT_FIRST_SERVER_RESPONSE Hora de enviar a solicitação para receber a primeira resposta do servidor. Somente cronometragem; não rastreia exceções.
STATEMENT_PREPARE Hora de sp_prepare quando prepareMethod=prepare.
STATEMENT_PREPEXEC Tempo para preparação e execução combinadas por meio de sp_prepexec.
STATEMENT_EXECUTE Hora de execução da instrução (sp_executesql, sp_execute, SQL direto ou lote).

Habilitar métricas de desempenho

Opção 1: registrar um retorno de chamada

Registre um PerformanceLogCallback para receber dados de desempenho programaticamente:

SQLServerDriver.registerPerformanceLogCallback(new PerformanceLogCallback() {
    @Override
    public void publish(PerformanceActivity activity, int connectionId,
            long durationMs, Exception exception) {
        // Connection-level metrics
        System.out.printf("Activity: %s, Connection: %d, Duration: %d ms%n",
                activity, connectionId, durationMs);
    }

    @Override
    public void publish(PerformanceActivity activity, int connectionId,
            int statementId, long durationMs, Exception exception) {
        // Statement-level metrics
        System.out.printf("Activity: %s, Connection: %d, Statement: %d, Duration: %d ms%n",
                activity, connectionId, statementId, durationMs);
    }
});

Opção 2: Configurar o log do Java

Configure java.util.logging para os registradores de métricas de desempenho no nível FINE.

Em um logging.properties arquivo:

com.microsoft.sqlserver.jdbc.PerformanceMetrics.Connection.level = FINE
com.microsoft.sqlserver.jdbc.PerformanceMetrics.Statement.level = FINE
handlers = java.util.logging.ConsoleHandler
java.util.logging.ConsoleHandler.level = FINE

Ou programaticamente:

Logger.getLogger("com.microsoft.sqlserver.jdbc.PerformanceMetrics.Connection")
      .setLevel(Level.FINE);
Logger.getLogger("com.microsoft.sqlserver.jdbc.PerformanceMetrics.Statement")
      .setLevel(Level.FINE);

Preparar o efeito do método sobre as atividades de declaração

As atividades rastreáveis PreparedStatement dependem da propriedade de conexão prepareMethod. Para obter mais informações sobre prepareMethod, consulte Como definir as propriedades de conexão.

configuração de prepareMethod Primeira execução Segunda execução Terceira execução
prepexec (padrão) STATEMENT_EXECUTE (sp_executesql) STATEMENT_PREPEXEC (sp_prepexec) STATEMENT_EXECUTE (sp_execute)
prepare STATEMENT_PREPARE + STATEMENT_EXECUTE STATEMENT_EXECUTE STATEMENT_EXECUTE
none STATEMENT_EXECUTE (SQL direto) STATEMENT_EXECUTE (SQL direto) STATEMENT_EXECUTE (SQL direto)

Observação

Com a configuração padrão prepexec, o driver adia a preparação supondo uso único. A segunda execução usa sp_prepexec (preparação e execução combinadas). A partir da terceira execução em diante, o identificador armazenado em cache é reutilizado por meio de sp_execute. Para forçar sp_prepexec na primeira chamada, defina a propriedade enablePrepareOnFirstPreparedStatementCall de conexão como true.

Saída de log de exemplo

A saída a seguir mostra as atividades rastreadas em três execuções consecutivas de uma PreparedStatement com a configuração padrão prepexec:

ConnectionID:1, StatementID:1 Request build time, duration: 8ms
ConnectionID:1, StatementID:1 First server response, duration: 17ms
ConnectionID:1, StatementID:1 Statement execute, duration: 75ms        ← 1st call: sp_executesql
ConnectionID:1, StatementID:1 Request build time, duration: 9ms
ConnectionID:1, StatementID:1 First server response, duration: 0ms
ConnectionID:1, StatementID:1 Statement prepexec, duration: 0ms        ← 2nd call: sp_prepexec
ConnectionID:1, StatementID:1 Request build time, duration: 0ms
ConnectionID:1, StatementID:1 First server response, duration: 0ms
ConnectionID:1, StatementID:1 Statement execute, duration: 0ms         ← 3rd call: sp_execute

Consulte também

Melhorando o desempenho e a confiabilidade com o driver JDBC Definindoas propriedades de conexão

  • Last updated on