Habilitación del seguimiento de eventos en SqlClient

Se aplica a: .NET Framework .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 trazas de eventos, las aplicaciones cliente deben escuchar los 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	Valor	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 básicos de seguimiento del flujo de la aplicación.
Ámbito	4	Activa la captura de eventos de entrada y salida.
NotificationTrace	8	Activa la captura de eventos de seguimiento `SqlNotification`.
Ámbito de notificación	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 el registro de eventos de seguimiento del ámbito de la 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 generación del volcado completo del estado 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();
            }
        }
    }
}

Soporte para 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();
        }
    }
}

Use Xperf para recopilar trazas

Inicie el seguimiento con el comando siguiente.

xperf -start trace -f myTrace.etl -on *Microsoft.Data.SqlClient.EventSource

Ejecute el ejemplo de seguimiento de SNI nativo para conectarse a SQL Server.
Detenga el seguimiento con la siguiente línea de comandos.
```
xperf -stop trace
```
Use 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/SNIScope y Microsoft.Data.SqlClient.EventSource/SNITrace.

Use PerfView para recopilar trazas

Inicie PerfView y ejecute Collect > Collect desde la barra de menús.
Configure el nombre del archivo de seguimiento, la ruta de 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 etl en PerfView. El registro de seguimiento de SNI se puede encontrar con los nombres de evento Microsoft.Data.SqlClient.EventSource/SNIScope y Microsoft.Data.SqlClient.EventSource/SNITrace.

Uso de dotnet-trace para recopilar seguimientos

En sistemas Linux, macOS o Windows, se puede usar dotnet-trace para capturar trazas. La herramienta dotnet-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.
Instalación de dotnet-trace.

Ejecute dotnet-trace. El parámetro --providers requiere 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 de MyApplication desde el inicio de la aplicación, la suma de palabras clave es 8191 y 1FFF en hexadecimal. El nivel de detalle se especifica en este comando mediante 5.

dotnet-trace collect --providers Microsoft.Data.SqlClient.EventSource:1FFF:5 -- dotnet MyApplication.dll

La 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:4

Ejecute 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 va a realizar un rastreo en Windows, copie el archivo a un sistema Windows. Vea el archivo de seguimiento en PerfView.

Comentarios

¿Le resultó útil esta página?

Last updated on 2026-08-24