Enregistreur d’événements de performances et rappel

Télécharger le pilote JDBC

À compter de la version 13.4, Microsoft JDBC Driver pour SQL Server fournit une infrastructure de métriques de performances pour le suivi du minutage des opérations de pilote critiques. Vous pouvez utiliser cette infrastructure pour observer et analyser le comportement d’exécution des connexions et des instructions, ce qui permet d’identifier les goulots d’étranglement de latence dans les interactions de votre application avec SQL Server.

Les métriques sont disponibles via deux mécanismes qui peuvent être utilisés indépendamment ou ensemble :

• Rappel programmatique : Enregistrez un PerformanceLogCallback pour recevoir des métriques dans votre code d’application.
• Journalisation Java - Abonnez-vous aux journaliseurs dédiés java.util.logging pour capturer les métriques dans la sortie de log.

Activités suivies

Le pilote effectue le suivi des activités à deux niveaux : la connexion et l’instruction.

Activités au niveau de la connexion

Activité	Description
CONNECTION	Temps total d’établissement d’une connexion, y compris toutes les sous-activités.
PRELOGIN	Temps de négociation pour le prélogin TDS avec le serveur.
LOGIN	C'est le moment de lancer la connexion TDS et la procédure de poignée de main d'authentification.
TOKEN_ACQUISITION	Temps d’acquisition de jetons d’authentification fédérés lors de l’utilisation de l’authentification Microsoft Entra.

Activités au niveau de la déclaration

Activité	Description
STATEMENT_REQUEST_BUILD	Temps côté client pour générer la requête TDS (liaison de paramètre, traitement SQL, construction de paquets). Mesure du temps uniquement ; ne suit pas les exceptions.
STATEMENT_FIRST_SERVER_RESPONSE	Délai d’envoi de la demande à la réception de la première réponse du serveur. Chronométrage uniquement ; ne suit pas les exceptions.
STATEMENT_PREPARE	Temps pour sp_prepare quand prepareMethod=prepare.
STATEMENT_PREPEXEC	Temps de préparation et d’exécution combinés via sp_prepexec.
STATEMENT_EXECUTE	Durée de l’exécution des instructions (sp_executesql, sp_executeSQL direct ou batch).

Activer les métriques de performances

Option 1 : Inscrire un rappel

Inscrivez un PerformanceLogCallback pour recevoir des données de performance de manière programmatique :

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);
    }
});

Option 2 : Configurer la journalisation Java

Configurez java.util.logging les enregistreurs de métriques de performance pour le niveau FINE.

Dans un logging.properties fichier :

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 par programmation :

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

Préparation de l'effet des méthodes sur les activités de déclaration

Les activités suivies pour PreparedStatement dépendent de la propriété de connexion prepareMethod. Pour plus d’informations sur prepareMethod, consultez Définition des propriétés de connexion.

Paramètre prepareMethod	Première exécution	Deuxième exécution	Troisième exécution+
prepexec (valeur par défaut)	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 directe)	STATEMENT_EXECUTE (SQL direct)	STATEMENT_EXECUTE (SQL directe)

Note

Avec le paramètre par défaut prepexec , le pilote reporte la préparation en supposant qu’il s’agit d’une utilisation unique. La deuxième exécution utilise sp_prepexec (préparation et exécution combinées). À partir de la troisième exécution, le handle mis en cache est réutilisé via sp_execute. Pour forcer sp_prepexec pour le premier appel, définissez la propriété de connexion enablePrepareOnFirstPreparedStatementCall sur true.

Exemple de sortie de journalisation

La sortie suivante montre les activités suivies sur trois exécutions consécutives d’un PreparedStatement avec le paramètre par défaut 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

Voir également

Amélioration des performances et de la fiabilité avec le pilote JDBCDéfinissant les propriétés de connexion