Habilitación del seguimiento de eventos en SqlClient

Se aplica a: .NET Framework .NET .NET Standard

Descargar ADO.NET

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:

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

1. Inicie el seguimiento con el comando siguiente.

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

2. Ejecute el ejemplo de seguimiento de SNI nativo para conectarse a SQL Server.

3. Detenga el seguimiento con la siguiente línea de comandos.

   xperf -stop trace
   

4. 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.

   

Uso de PerfView para recopilar trazas de seguimiento

1. Inicie PerfView y ejecute Collect > Collect desde la barra de menús.

2. Configure el nombre del archivo de seguimiento, la ruta de acceso de la salida y el nombre del proveedor.

   

3. Inicie la recopilación.

4. Ejecute el ejemplo de seguimiento de SNI nativo para conectarse a SQL Server.

5. Detenga la recopilación de PerfView. Se tarda un tiempo en generar el archivo PerfViewData.etl según la configuración del paso 2.

6. 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 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.

1. Si aún no está instalado, instale el SDK de .NET en el equipo cliente.

2. Instalación de dotnet-trace.

3. 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 detallado 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 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.