Activer le suivi d’événements dans SqlClient
S'applique à : 
.NET Framework .NET .NET Standard
Le Suivi des événements pour Windows (ETW) est une fonctionnalité de suivi efficace au niveau du noyau qui permet de journaliser des événements définis par le pilote pour le débogage et le test. SqlClient prend en charge la capture des événements ETW à différents niveaux d’information. Pour capturer le suivi d’événements, les applications clientes doivent détecter les événements dans l’implémentation EventSource de SqlClient :
Microsoft.Data.SqlClient.EventSource
L’implémentation actuelle prend en charge les mots clés d’événements suivants :
| Nom du mot clé | Valeur | Description |
|---|---|---|
| ExecutionTrace | 1 | Active la capture des événements de démarrage/arrêt avant et après l’exécution de la commande. |
| Trace | 2 | Active la capture des événements de suivi de flux d’application de base. |
| Étendue | 4 | Active la capture des événements d’entrée et de sortie. |
| NotificationTrace | 8 | Active la capture des événements de suivi SqlNotification. |
| NotificationScope | 16 | Active la capture des événements d’entrée et de sortie de portée SqlNotification. |
| PoolerTrace | 32 | Active la capture des événements de suivi de flux de regroupement de connexions. |
| PoolerScope | 64 | Active la capture des événements de suivi de portée de regroupement de connexions. |
| AdvancedTrace | 128 | Active la capture des événements de suivi de flux avancés. |
| AdvancedTraceBin | 256 | Active la capture des événements de suivi de flux avancés avec des informations supplémentaires. |
| CorrelationTrace | 512 | Active la capture des événements de suivi de flux de corrélation. |
| StateDump | 1 024 | Active la capture du vidage de l’état complet de SqlConnection. |
| SNITrace | 2 048 | Active la capture des événements de suivi de flux à partir de l’implémentation réseau gérée (s’applique uniquement à .NET Core). |
| SNIScope | 4096 | Active la capture des événements de portée à partir de l’implémentation réseau gérée (s’applique uniquement à .NET Core). |
Exemple
L’exemple suivant active le suivi d’événements pour une opération de données sur l’exemple de base de données AdventureWorks et affiche les événements dans la fenêtre de console.
using System;
using System.Diagnostics.Tracing;
using Microsoft.Data.SqlClient;
// This listener class will listen for events from the SqlClientEventSource class.
// SqlClientEventSource is an implementation of the EventSource class which gives
// it the ability to create events.
public class SqlClientListener : EventListener
{
protected override void OnEventSourceCreated(EventSource eventSource)
{
// Only enable events from SqlClientEventSource.
if (eventSource.Name.Equals("Microsoft.Data.SqlClient.EventSource"))
{
// Use EventKeyWord 2 to capture basic application flow events.
// See the above table for all available keywords.
EnableEvents(eventSource, EventLevel.Informational, (EventKeywords)2);
}
}
// This callback runs whenever an event is written by SqlClientEventSource.
// Event data is accessed through the EventWrittenEventArgs parameter.
protected override void OnEventWritten(EventWrittenEventArgs eventData)
{
// Print event data.
Console.WriteLine(eventData.Payload[0]);
}
}
class Program
{
public static void Main()
{
// Create a new event listener.
using (SqlClientListener listener = new SqlClientListener())
{
string connectionString = "Data Source=localhost; " +
"Initial Catalog=AdventureWorks; Integrated Security=true";
// Open a connection to the AdventureWorks database.
using (SqlConnection connection = new SqlConnection(connectionString))
{
connection.Open();
string sql = "SELECT * FROM Sales.Currency";
SqlCommand command = new SqlCommand(sql, connection);
// Perform a data operation on the server.
SqlDataReader reader = command.ExecuteReader();
while (reader.Read())
{
// Read the data.
}
reader.Close();
}
}
}
}
Support du suivi des événements dans Native SNI
Microsoft.Data.SqlClient assure la prise en charge du suivi d’événements dans Microsoft.Data.SqlClient.SNI et Microsoft.Data.SqlClient.SNI.runtime à partir de la version 2.1. Les événements peuvent être collectés à partir des DLL natives avec les outils Xperf et PerfView.
À compter de la version 3.0 de Microsoft.Data.SqlClient, le suivi d’événements peut être activé sans aucune modification de l’application cliente à l’aide des outils de collecte d’événements.
Avec Microsoft.Data.SqlClient v2.1, le suivi des événements doit être activé en configurant EventCommand avec un écouteur sur la source d’événements. Les valeurs EventCommand valides applicables à Native SNI sont :
// Enables trace events:
EventSource.SendCommand(eventSource, (EventCommand)8192, null);
// Enables flow events:
EventSource.SendCommand(eventSource, (EventCommand)16384, null);
// Enables both trace and flow events:
EventSource.SendCommand(eventSource, (EventCommand)(8192 | 16384), null);
L’exemple suivant active le suivi d’événements dans les DLL SNI natives.
// Native SNI tracing example
using System;
using System.Diagnostics.Tracing;
using Microsoft.Data.SqlClient;
public class SqlClientListener : EventListener
{
protected override void OnEventSourceCreated(EventSource eventSource)
{
if (eventSource.Name.Equals("Microsoft.Data.SqlClient.EventSource"))
{
// Enables both trace and flow events
EventSource.SendCommand(eventSource, (EventCommand)(8192 | 16384), null);
}
}
}
class Program
{
static string connectionString = @"Data Source = localhost; Initial Catalog = AdventureWorks;Integrated Security=true;";
static void Main(string[] args)
{
// Event source listener configuration is not required in v3.0 onwards.
using (SqlClientListener listener = new SqlClientListener())
using (SqlConnection connection = new SqlConnection(connectionString))
{
connection.Open();
}
}
}
Utilisez Xperf pour collecter des traces
Démarrez le suivi en utilisant la commande suivante.
xperf -start trace -f myTrace.etl -on *Microsoft.Data.SqlClient.EventSourceExécutez l’exemple de traçage SNI natif pour vous connecter à SQL Server.
Arrêtez le suivi en utilisant la ligne de commande suivante.
xperf -stop traceUtilisez PerfView pour ouvrir le fichier myTrace.etl spécifié à l’étape 1. Le journal de suivi SNI peut être trouvé avec les noms d’événements
Microsoft.Data.SqlClient.EventSource/SNIScopeetMicrosoft.Data.SqlClient.EventSource/SNITrace.
Utilisez PerfView pour collecter des traces
Démarrez PerfView et exécutez
Collect > Collectà partir de la barre de menus.Configurez le nom du fichier de trace, le chemin de sortie et le nom du fournisseur.
Démarrez le regroupement.
Exécutez l’exemple de traçage SNI natif pour vous connecter à SQL Server.
Arrêtez le regroupement à partir de PerfView. La génération du fichier PerfViewData.etl en fonction de la configuration à l’étape 2 prend un certain temps.
Ouvrez le fichier
etldans PerfView. Le journal de suivi SNI peut être trouvé avec les noms d’événementsMicrosoft.Data.SqlClient.EventSource/SNIScopeetMicrosoft.Data.SqlClient.EventSource/SNITrace.
Utiliser dotnet-trace pour collecter des traces
Sur Linux, macOS ou Windows, vous pouvez utiliser dotnet-trace pour capturer des traces. L’outil donet-trace permet de collecter des traces pour les applications .NET. Pour plus d’informations sur dotnet-trace, consultez l’utilitaire d’analyse des performances dotnet-trace Les traces créées par dotnet-trace peuvent être consultées dans PerfView.
S’il n’est pas déjà installé, installez le SDK .NET sur l’ordinateur client.
Exécutez dotnet-trace. Le paramètre
--providersnécessite que le nom du fournisseur et les mots clés soient spécifiés pour les traces à partir de Microsoft.Data.SqlClient. L’option de mots clés est une somme des valeurs de mot clé dans la table des mots clés d’événement convertie en valeur hexadécimale. Pour collecter tous les événements au niveau de détail deMyApplicationà partir du démarrage de l’application, la somme des mots clés est 8191, ou1FFFen hexadécimal. Le niveau de détail est spécifié dans cette commande par5.dotnet-trace collect --providers Microsoft.Data.SqlClient.EventSource:1FFF:5 -- dotnet MyApplication.dllLa sortie est la suivante :
Provider Name Keywords Level Enabled By Microsoft.Data.SqlClient.EventSource 0x0000000000001FFF Verbose(5) --providers Launching: dotnet MyApplication.dll Process : /usr/lib/dotnet/dotnet Output File : /home/appuser/dotnet_20240927_102506.nettrace [00:00:00:00] Recording trace 0.00 (B) Press <Enter> or <Ctrl+C> to exit... Trace completed. Process exited with code '1'.Pour collecter tous les événements de niveau information sur une application en cours d’exécution, recherchez d’abord l’ID de processus de l’application. Exécutez ensuite dotnet-trace sur le processus. Le niveau information est spécifié par
4.dotnet-trace ps 8734 MyApplication /home/appuser/MyApplication/MyApplication dotnet-trace collect -–process-id 8734 --providers Microsoft.Data.SqlClient.EventSource:1FFF:4Exécutez l'application séparément et laissez-la tourner aussi longtemps que nécessaire pour reproduire le problème. S'il s'agit d'un problème de CPU élevé, 5 à 10 secondes suffisent généralement.
Provider Name Keywords Level Enabled By Microsoft.Data.SqlClient.EventSource 0x0000000000001FFF LogAlways(0) --providers Process : /usr/lib/dotnet/dotnet Output File : /home/appuser/dotnet_20240927_104154.nettrace [00:00:00:10] Recording trace 4.096 (KB) Press <Enter> or <Ctrl+C> to exit... Stopping the trace. This may take several minutes depending on the application being traced. Trace completed.Le nom du fichier de trace se termine par
.nettrace. Si vous n’effectuez pas le suivi sur Windows, copiez le fichier dans un système Windows. Affichez le fichier de trace dans PerfView.
Ressources externes
Pour obtenir un autre ensemble d’exemples sur la façon de suivre Microsoft.Data.SqlClient multiplateforme, consultez le wiki des outils de mise en réseau CSS SQL.
Pour plus d’informations sur le suivi des événements, consultez les ressources suivantes.
| Ressource | Description |
|---|---|
| EventSource Class | Utilisé pour créer des événements ETW. |
| Classe EventListener | Fournit des méthodes permettant d’activer et de désactiver des événements à partir des sources d’événements. |