Abilitare la traccia eventi in SqlClient

Articolo
10/01/2024

Si applica a: .NET Framework .NET .NET Standard

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 tracce

Avviare la traccia usando la riga di comando seguente.

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

Eseguire l'esempio di traccia SNI nativo per connettersi a SQL Server.
Arrestare la traccia usando la riga di comando seguente.
```
xperf -stop trace
```
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 tracce

Avviare PerfView ed eseguire Collect > Collect dalla barra dei menu.
Configurare il nome del file di traccia, il percorso di output e il nome del provider.
Avviare la raccolta.
Eseguire l'esempio di traccia SNI nativo per connettersi a SQL Server.
Arrestare la raccolta da PerfView. La generazione del file PerfViewData.etl in base alla configurazione nel passaggio 2 potrebbe richiedere tempo.
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.

Usare dotnet-trace per raccogliere le tracce

In Linux, macOS o Windows è possibile usare dotnet-trace per acquisire le tracce. Lo strumento donet-trace viene usato per raccogliere tracce per le applicazioni .NET. Per altre informazioni su dotnet-trace, vedere l'utility di analisi delle prestazioni di dotnet-trace Le tracce create da dotnet-trace possono essere visualizzate in PerfView.

Se non è già installato, installare .NET SDK nel computer client.
Installare dotnet-trace.

Eseguire dotnet-trace. Il parametro --providers richiede che vengano specificati il nome del provider e le parole chiave per le tracce di Microsoft.Data.SqlClient. L'opzione parole chiave è una somma dei valori delle parole chiave nella tabella delle parole chiave dell'evento convertita in esadecimale. Per raccogliere tutti gli eventi a livello dettagliato di MyApplication dall'inizio dell'applicazione, la somma delle parole chiave è 8191 e 1FFF in esadecimale. Il livello dettagliato viene specificato in questo comando da 5.

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

L'output è il seguente:


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

Per raccogliere tutti gli eventi a livello di informazioni su un'applicazione in esecuzione, trovare prima l'ID processo dell'applicazione. Eseguire quindi dotnet-trace nel processo. Il livello di informazioni viene specificato da 4.

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

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

Eseguire l'applicazione separatamente e lasciarla eseguire fino a quando necessario per riprodurre il problema. Se si tratta di un problema elevato della CPU, 5-10 secondi è in genere sufficiente.

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.

Il nome del file di traccia termina con .nettrace. Se non si esegue la traccia in Windows, copiare il file in un sistema Windows. Visualizzare il file di traccia in PerfView.

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.

Condividi tramite