Ativar rastreamento de eventos no SqlClient

Aplica-se a: .NET Framework .NET .NET Standard

O Rastreamento de Eventos para Windows (ETW) é uma funcionalidade eficiente de rastreamento ao nível do kernel que permite registar eventos definidos pelo driver para fins de depuração e testes. O SqlClient suporta a captura de eventos ETW em diferentes níveis informativos. Para começar a capturar vestígios de eventos, as aplicações cliente devem ouvir eventos da implementação EventSource do SqlClient:

Microsoft.Data.SqlClient.EventSource

A implementação atual suporta as seguintes Palavras-Chave de Evento:

Nome da palavra-chave	Valor	Description
ExecutionTrace	1	Ativa a captura de eventos Start/Stop antes e depois da execução do comando.
Rastreio	2	Ativa a captura de eventos básicos de rastreio de fluxo de aplicação.
Scope	4	Ativa-se a captura de eventos de entrada e saída
NotificationTrace	8	Ativa a captura de eventos de rastreio `SqlNotification`
NotificationScope	16	Ativa a `SqlNotification` captura de eventos de entrada e saída do âmbito
PoolerTrace	32	Ativa a captura de eventos de rastreamento do fluxo de pooling de ligação.
PoolerScope	64	Ativa a captura de eventos de rastreamento do âmbito do pool de conexões.
AdvancedTrace	128	Ativa a captura de eventos avançados de rastreio de fluxo.
AdvancedTraceBin	256	Ativa a captura de eventos de rastreio de fluxo avançados com informação adicional.
CorrelationTrace	512	Ativa a captura de eventos de traço de fluxo de correlação.
StateDump	1024	Ativa a captura de estado completo do dump de `SqlConnection`
SNITrace	2048	Ativa a captura de eventos de rastreamento de fluxo a partir da implementação de Rede Gerida (aplicável apenas em .NET Core)
SNIScope	4096	Ativa a captura de eventos de âmbito a partir da implementação de Redes Geridas (aplicável apenas em .NET Core)

Example

O exemplo seguinte permite o rastreamento de eventos para uma operação de dados na base de dados de exemplos AdventureWorks e apresenta os eventos na janela da 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();
            }
        }
    }
}

Suporte para rastreamento de eventos no SNI nativo

O Microsoft.Data.SqlClient fornece suporte para rastreamento de eventos em Microsoft.Data.SqlClient.SNI e Microsoft.Data.SqlClient.SNI.runtime a partir da v2.1. Os eventos podem ser recolhidos a partir das DLLs nativas usando as ferramentas Xperf e PerfView .

A partir do Microsoft.Data.SqlClient v3.0, o rastreamento de eventos pode ser ativado sem quaisquer modificações na aplicação cliente usando ferramentas de recolha de eventos.

Com o Microsoft.Data.SqlClient v2.1, o rastreamento de eventos precisa ser ativado configurando o EventCommand com um listener de fonte de eventos. Os valores válidos EventCommand 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 seguinte permite rastreamento de eventos em DLLs SNI nativas.

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

Usa o Xperf para recolher vestígios

Comece a traçar usando o seguinte comando.

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

Executa o exemplo nativo de rastreamento SNI para ligar ao SQL Server.
Pare de rastrear usando a seguinte linha de comandos.
```
xperf -stop trace
```
Use o PerfView para abrir o ficheiro myTrace.etl especificado no Passo 1. O registo de rastreamento SNI pode ser encontrado sob os nomes de eventos Microsoft.Data.SqlClient.EventSource/SNIScope e Microsoft.Data.SqlClient.EventSource/SNITrace.

Use o PerfView para recolher rastreios

Inicia o PerfView e executa Collect > Collect a partir da barra de menus.
Configure o nome do ficheiro de rastreio, o caminho de saída e o nome do fornecedor.
Inicia a recolha.
Executa o exemplo nativo de rastreamento SNI para ligar ao SQL Server.
Parar a recolha de dados do PerfView. Demora algum tempo a gerar o ficheiro PerfViewData.etl de acordo com a configuração do Passo 2.
Abra o etl ficheiro no PerfView. O registo de rastreamento SNI pode ser encontrado sob os nomes de eventos Microsoft.Data.SqlClient.EventSource/SNIScope e Microsoft.Data.SqlClient.EventSource/SNITrace.

Use dotnet-trace para capturar rastros

No Linux, macOS ou Windows, o dotnet-trace pode ser usado para capturar traços. A ferramenta dotnet-trace é usada para recolher traços para aplicações .NET. Para mais informações sobre dotnet-trace, consulte a ferramenta de análise de desempenho dotnet-trace Os traços criados por dotnet-trace podem ser visualizados no PerfView.

Se ainda não estiver instalado, instale o SDK .NET na máquina cliente.
Instala dotnet-trace.

Executa dotnet-trace. O --providers parâmetro exige que o nome do fornecedor e as palavras-chave sejam especificados para os rastreios do Microsoft.Data.SqlClient. A opção de palavras-chave é a soma dos valores das palavras-chave na tabela de palavras-chave de eventos convertida para hexadecimal. Para recolher todos os eventos ao nível prolixo desde MyApplication o início da aplicação, a soma das palavras-chave é 8191 e 1FFF em hexadecimal. O nível verboso é especificado neste comando por 5.

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

A saída é:


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 recolher todos os eventos no nível de informação de uma aplicação em execução, primeiro localize o ID do processo da aplicação. Depois executa dotnet-trace no processo. O nível de informação é especificado por 4.

dotnet-trace ps
8734  MyApplication  /home/appuser/MyApplication/MyApplication

dotnet-trace collect --process-id 8734 --providers Microsoft.Data.SqlClient.EventSource:1FFF:4

Executa a aplicação separadamente e deixa-a correr o tempo necessário para reproduzir o problema. Se for um problema de CPU elevado, 5-10 segundos costumam ser suficientes.

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.

O nome do ficheiro de rastreio termina em .nettrace. Se não estiver a rastrear no Windows, copie o ficheiro para um sistema Windows. Veja o ficheiro de rastreamento no PerfView.

Comentários

Esta página foi útil?

Last updated on 2026-08-24