Habilitación del seguimiento de eventos en SqlClient
Se aplica a: 
.NET Framework .NET .NET Standard
Seguimiento de eventos para Windows (ETW) es una eficaz herramienta de seguimiento de nivel de kernel que permite registrar eventos definidos por el controlador para la depuración y la realización de pruebas. SqlClient admite la captura de eventos ETW en diferentes niveles informativos. Para comenzar a capturar seguimientos de eventos, las aplicaciones cliente deberían escuchar eventos de la implementación de EventSource de SqlClient:
Microsoft.Data.SqlClient.EventSource
La implementación actual admite las siguientes palabras clave de evento:
| Nombre de palabra clave | Value | Descripción |
|---|---|---|
| ExecutionTrace | 1 | Activa la captura de eventos de inicio y detención antes y después de la ejecución del comando. |
| Seguimiento | 2 | Activa la captura de eventos de seguimiento de flujo de aplicación básicos. |
| Ámbito | 4 | Activa la captura de eventos de entrada y salida. |
| NotificationTrace | 8 | Activa la captura de eventos de seguimiento SqlNotification. |
| NotificationScope | 16 | Activa la captura de eventos de entrada y salida del ámbito SqlNotification. |
| PoolerTrace | 32 | Activa la captura de eventos de seguimiento de flujo de agrupación de conexiones. |
| PoolerScope | 64 | Activa la captura de eventos de seguimiento de ámbito de agrupación de conexiones. |
| AdvancedTrace | 128 | Activa la captura de eventos de seguimiento de flujo avanzados. |
| AdvancedTraceBin | 256 | Activa la captura de eventos de seguimiento de flujo avanzados con información adicional. |
| CorrelationTrace | 512 | Activa la captura de eventos de seguimiento de flujo de correlación. |
| StateDump | 1024 | Activa la captura del volcado del estado completo de SqlConnection. |
| SNITrace | 2048 | Activa la captura de eventos de seguimiento de flujo de la implementación de redes administradas (solo es aplicable en .NET Core). |
| SNIScope | 4096 | Activa la captura de eventos de ámbito de la implementación de redes administradas (solo es aplicable en .NET Core). |
Ejemplo
En el ejemplo siguiente se habilita el seguimiento de eventos para una operación de datos en la base de datos de ejemplo AdventureWorks y se muestran los eventos en la ventana de la consola.
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();
}
}
}
}
Compatibilidad con el seguimiento de eventos en SNI nativo
Microsoft.Data.SqlClient proporciona compatibilidad con el seguimiento de eventos en Microsoft.Data.SqlClient.SNI y Microsoft.Data.SqlClient.SNI.runtime a partir de v.2.1. Los eventos se pueden recopilar de los archivos DLL nativos mediante las herramientas Xperf y PerfView.
A partir de Microsoft.Data.SqlClient v3.0, el seguimiento de eventos se puede habilitar sin realizar modificaciones en la aplicación cliente, mediante el uso de herramientas de recopilación de eventos.
Con Microsoft.Data.SqlClient v2.1, el seguimiento de eventos debe habilitarse mediante la configuración de EventCommand con el agente de escucha de origen de eventos. Los valores EventCommand válidos aplicables a SNI nativo son:
// 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);
En el ejemplo siguiente se habilita el seguimiento de eventos en archivos DLL de SNI nativo.
// 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();
}
}
}
Uso de Xperf para recopilar trazas de seguimiento
Inicie el seguimiento con el comando siguiente.
xperf -start trace -f myTrace.etl -on *Microsoft.Data.SqlClient.EventSourceEjecute el ejemplo de seguimiento de SNI nativo para conectarse a SQL Server.
Detenga el seguimiento con la siguiente línea de comandos.
xperf -stop traceUse PerfView para abrir el archivo myTrace.etl especificado en el paso 1. El registro de seguimiento de SNI se puede encontrar con los nombres de evento
Microsoft.Data.SqlClient.EventSource/SNIScopeyMicrosoft.Data.SqlClient.EventSource/SNITrace.
Uso de PerfView para recopilar trazas de seguimiento
Inicie PerfView y ejecute
Collect > Collectdesde la barra de menús.Configure el nombre del archivo de seguimiento, la ruta de acceso de la salida y el nombre del proveedor.
Inicie la recopilación.
Ejecute el ejemplo de seguimiento de SNI nativo para conectarse a SQL Server.
Detenga la recopilación de PerfView. Se tarda un tiempo en generar el archivo PerfViewData.etl según la configuración del paso 2.
Abra el archivo
etlen PerfView. El registro de seguimiento de SNI se puede encontrar con los nombres de eventoMicrosoft.Data.SqlClient.EventSource/SNIScopeyMicrosoft.Data.SqlClient.EventSource/SNITrace.
Uso de dotnet-trace para recopilar seguimientos
En Linux, macOS o Windows, se puede usar dotnet-trace para capturar seguimientos. La herramienta donet-trace se usa para recopilar seguimientos para aplicaciones .NET. Para obtener más información sobre dotnet-trace, consulte la utilidad de análisis de rendimiento dotnet-trace. Los seguimientos creados por dotnet-trace se pueden ver en PerfView.
Si aún no está instalado, instale el SDK de .NET en el equipo cliente.
Ejecute dotnet-trace. El parámetro
--providersrequiere que se especifiquen el nombre del proveedor y las palabras clave para los seguimientos de Microsoft.Data.SqlClient. La opción de palabras clave es una suma de los valores de palabra clave de la tabla de palabras clave de evento convertidas en hexadecimal. Para recopilar todos los eventos en el nivel detallado deMyApplicationdesde el inicio de la aplicación, la suma de palabras clave es 8191 y1FFFen hexadecimal. El nivel detallado se especifica en este comando mediante5.dotnet-trace collect --providers Microsoft.Data.SqlClient.EventSource:1FFF:5 -- dotnet MyApplication.dllLa salida es la siguiente:
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'.Para recopilar todos los eventos en el nivel de información de una aplicación en ejecución, primero busque el identificador de proceso de la aplicación. A continuación, ejecute dotnet-trace en el proceso. El nivel de información se especifica mediante
4.dotnet-trace ps 8734 MyApplication /home/appuser/MyApplication/MyApplication dotnet-trace collect -–process-id 8734 --providers Microsoft.Data.SqlClient.EventSource:1FFF:4Ejecute la aplicación por separado y deje que se ejecute el tiempo que sea necesario para reproducir el problema. Si se trata de un problema de CPU elevado, normalmente es suficiente con entre 5 y 10 segundos.
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.El nombre del archivo de seguimiento termina en
.nettrace. Si no realiza el seguimiento en Windows, copie el archivo en un sistema Windows. Vea el archivo de seguimiento en PerfView.
Recursos externos
Para otro conjunto de ejemplos sobre cómo realizar un seguimiento de Microsoft.Data.SqlClient multiplataforma, consulte la wiki de herramientas de redes de SQL de CSS.
Para más información sobre el seguimiento de eventos, consulte los recursos siguientes.
| Resource | Descripción |
|---|---|
| clase EventSource | Se utiliza para crear eventos ETW. |
| Clase EventListener | Proporciona métodos para habilitar y deshabilitar eventos de orígenes de eventos. |