Habilitar o rastreamento de eventos no SqlClient

Aplicável a: .NET Framework .NET .NET Standard

Baixar ADO.NET

O ETW (Rastreamento de Eventos para Windows) é um recurso de rastreamento eficiente no nível de kernel que permite registrar eventos definidos pelo driver para fins de depuração e teste. O SqlClient dá suporte à captura de eventos ETW em diferentes níveis informativos. Para começar a capturar esses rastreamentos de eventos, os aplicativos cliente devem escutar eventos da implementação EventSource do SqlClient:

Microsoft.Data.SqlClient.EventSource

A implementação atual dá suporte às seguintes palavras-chave de evento:

Nome da palavra-chave	Valor	DESCRIÇÃO
ExecutionTrace	1	Ativa a captura de eventos Iniciar/Parar antes e depois da execução do comando.
Trace	2	Ativa a captura de eventos básicos de rastreamento de fluxo de aplicativo.
Escopo	4	Ativa a captura de eventos de entrada e saída
NotificationTrace	8	Ativa a captura de eventos de rastreamento de SqlNotification
NotificationScope	16	Ativa a captura de eventos de entrada e saída de escopo de SqlNotification
PoolerTrace	32	Ativa a captura de eventos de rastreamento de fluxo do pool de conexões.
PoolerScope	64	Ativa a captura de eventos de rastreamento do escopo do pool de conexões.
AdvancedTrace	128	Ativa a captura de eventos de rastreamento de fluxo avançado.
AdvancedTraceBin	256	Ativa a captura de eventos de rastreamento de fluxo avançado com informações adicionais.
CorrelationTrace	512	Ativa a captura de eventos de rastreamento de fluxo de correlação.
StateDump	1024	Ativa a captura do despejo de estado completo de SqlConnection
SNITrace	2.048	Ativa a captura de eventos de rastreamento de fluxo da implementação de Rede Gerenciada (aplicável somente no .NET Core)
SNIScope	4096	Ativa a captura de eventos de escopo da implementação de Rede Gerenciada (aplicável somente no .NET Core)

Exemplo

O exemplo a seguir habilita o rastreamento de eventos para uma operação de dados no banco de dados de exemplo AdventureWorks e exibe os eventos na janela do 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();
            }
        }
    }
}

Suporte ao rastreamento de eventos no SNI nativo

Começando no v2.1, o Microsoft.Data.SqlClient dá suporte ao rastreamento de eventos em Microsoft.Data.SqlClient.SNI e Microsoft.Data.SqlClient.SNI.runtime. Os eventos podem ser coletados das DLLs nativas usando as ferramentas Xperf e PerfView.

Começando no Microsoft.Data.SqlClient v3.0, o rastreamento de eventos pode ser habilitado sem modificações no aplicativo cliente usando ferramentas de coleta de eventos.

Com o Microsoft.Data.SqlClient v2.1, o rastreamento de eventos precisa ser habilitado configurando o EventCommand com um ouvinte de origem do evento. Os valores EventCommand válidos aplicáveis ao SNI Nativo são:

// 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);

O exemplo a seguir habilita o rastreamento de eventos em DLLs do 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();
        }
    }
}

Usar Xperf para coletar o log de rastreamento

1. Inicie o rastreamento usando o comando a seguir.

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

2. Execute o exemplo de rastreamento do SNI nativo para se conectar ao SQL Server.

3. Pare o rastreamento usando a linha de comando a seguir.

   xperf -stop trace
   

4. Use PerfView para abrir o arquivo myTrace.etl especificado na etapa 1. O log de rastreamento do SNI pode ser encontrado com os nomes de evento Microsoft.Data.SqlClient.EventSource/SNIScope e Microsoft.Data.SqlClient.EventSource/SNITrace.

   

Usar PerfView para coletar o log de rastreamento

1. Inicie o PerfView e execute Collect > Collect na barra de menus.

2. Configure o nome do arquivo de rastreamento, o caminho de saída e o nome do provedor.

   

3. Inicie a coleta.

4. Execute o exemplo de rastreamento do SNI nativo para se conectar ao SQL Server.

5. Interrompa a coleta no PerfView. Leva algum tempo para gerar o arquivo PerfViewData.etl de acordo com a configuração na Etapa 2.

6. Abra o arquivo etl no PerfView. O log de rastreamento do SNI pode ser encontrado com os nomes de evento Microsoft.Data.SqlClient.EventSource/SNIScope e Microsoft.Data.SqlClient.EventSource/SNITrace.

Recursos externos

Para obter outro conjunto de exemplos sobre como rastrear a plataforma cruzada Microsoft.Data.SqlClient, confira o Wiki Ferramentas de Rede do SQL do CSS.

Para obter mais informações sobre o rastreamento de eventos, confira os recursos a seguir.

Recurso	Descrição
EventSource Class	Usado para criar eventos de ETW.
Classe EventListener	Fornece métodos para habilitar e desabilitar eventos de origens do evento.