Abilitare la traccia eventi in SqlClient

Si applica a: .NET Framework .NET Standard

Scarica ADO.NET

Event Tracing for Windows (ETW) è un'efficiente funzionalità di traccia a livello di kernel che consente di registrare gli eventi definiti dal driver per scopi di debug e test. SqlClient supporta l'acquisizione di eventi ETW a diversi livelli informativi. Per iniziare ad acquisire questi eventi, le applicazioni client devono restare in ascolto degli eventi dall'implementazione EventSource di SqlClient:

Microsoft.Data.SqlClient.EventSource

L'implementazione corrente supporta le parole chiave degli eventi seguenti:

Nome parola chiave	Valore	Descrizione
ExecutionTrace	1	Attiva l'acquisizione di eventi di avvio/arresto prima e dopo l'esecuzione del comando.
Traccia	2	Attiva l'acquisizione di eventi di traccia del flusso applicazione di base.
Ambito	4	Attiva l'acquisizione di eventi di ingresso e uscita
NotificationTrace	8	Attiva l'acquisizione di eventi di traccia di SqlNotification
NotificationScope	16	Attiva l'acquisizione di eventi di ingresso e uscita dell'ambito di SqlNotification
PoolerTrace	32	Attiva l'acquisizione di eventi di traccia del flusso del pool di connessioni
PoolerScope	64	Attiva l'acquisizione di eventi di traccia dell'ambito del pool di connessioni
AdvancedTrace	128	Attiva l'acquisizione di eventi di traccia del flusso avanzati
AdvancedTraceBin	256	Attiva l'acquisizione di eventi di traccia del flusso avanzati con informazioni aggiuntive
CorrelationTrace	512	Attiva l'acquisizione di eventi di traccia del flusso di correlazione.
StateDump	1024	Attiva l'acquisizione del backup dello stato completo di SqlConnection
SNITrace	2048	Attiva l'acquisizione di eventi di traccia del flusso dall'implementazione di rete gestita (applicabile solo in .NET Core)
SNIScope	4096	Attiva l'acquisizione di eventi dell'ambito dall'implementazione di rete gestita (applicabile solo in .NET Core)

Esempio

L'esempio seguente abilita la traccia eventi per un'operazione sui dati nel database di esempio AdventureWorks e visualizza gli eventi nella finestra della 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();
            }
        }
    }
}

Supporto della traccia eventi in SNI nativo

Microsoft.Data.SqlClient offre supporto per la traccia eventi in Microsoft.Data.SqlClient.SNI e Microsoft.Data.SqlClient.SNI.runtime a partire da v2.1. Gli eventi possono essere raccolti dalle DLL native usando gli strumenti Xperf e PerfView.

A partire da Microsoft.Data.SqlClient v3.0, la traccia eventi può essere abilitata senza alcuna modifica nell'applicazione client usando gli strumenti di raccolta eventi.

Con Microsoft.Data.SqlClient v2.1, è necessario abilitare la traccia eventi configurando EventCommand con un listener dell'origine evento. I valori validi EventCommand applicabili a Native SNI sono elencati di seguito:

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

L'esempio seguente abilita la traccia eventi nelle DLL SNI native.

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

Usare Xperf per raccogliere il log di traccia

1. Avviare la traccia usando la riga di comando seguente.

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

2. Eseguire l'esempio di traccia SNI nativo per connettersi a SQL Server.

3. Arrestare la traccia usando la riga di comando seguente.

   xperf -stop trace
   

4. Usare PerfView per aprire il file myTrace.etl specificato nel passaggio 1. Il log di traccia SNI è reperibile con i nomi degli eventi Microsoft.Data.SqlClient.EventSource/SNIScope e Microsoft.Data.SqlClient.EventSource/SNITrace.

   

Usare PerfView per raccogliere il log di traccia

1. Avviare PerfView ed eseguire Collect > Collect dalla barra dei menu.

2. Configurare il nome del file di traccia, il percorso di output e il nome del provider.

   

3. Avviare la raccolta.

4. Eseguire l'esempio di traccia SNI nativo per connettersi a SQL Server.

5. Arrestare la raccolta da PerfView. La generazione del file PerfViewData.etl in base alla configurazione nel passaggio 2 potrebbe richiedere tempo.

6. Aprire il file etl in PerfView. Il log di traccia SNI è reperibile con i nomi degli eventi Microsoft.Data.SqlClient.EventSource/SNIScope e Microsoft.Data.SqlClient.EventSource/SNITrace.

Risorse esterne

Per un altro set di esempi su come tracciare microsoft.Data.SqlClient multipiattaforma, vedere il wiki di CSS SQL Networking Tools.

Per altre informazioni sul tracing degli eventi, vedere le risorse seguenti.

Risorsa	Descrizione
classe EventSource	Usato per creare eventi ETW.
Classe EventListener	Fornisce metodi per abilitare e disabilitare eventi da origini evento.