Habilitación del seguimiento de eventos en SqlClient

Artículo
05/23/2023

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 el registro de seguimiento

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.

Uso de PerfView para recopilar el registro de seguimiento

Inicie PerfView y ejecute Collect > Collect desde 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 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.

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.

Share via