Abilitare la traccia eventi in SqlClient

Si applica a: il .NET Framework il .NET lo 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 le tracce di eventi, le applicazioni client devono rimanere in ascolto degli eventi dell'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 la raccolta di eventi di traccia di base del flusso dell'applicazione.
Ambito	4	Attiva l'acquisizione degli eventi di ingresso e uscita
NotificationTrace	8	Attiva l'acquisizione di eventi di traccia di `SqlNotification`
Ambito di notifica	16	Attiva l'acquisizione degli eventi di entrata e uscita dell'`SqlNotification`ambito
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 degli eventi avanzati di traccia del flusso
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 per il tracciamento eventi in Native SNI

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

Avvia la traccia usando il 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.
Interrompere il tracciamento utilizzando il 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.
Interrompere la raccolta dati in 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 dotnet-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 acquisire tutti gli eventi al livello verbose di MyApplication fin dall'avvio dell'applicazione, la somma delle parole chiave è 8191, ovvero 1FFF in esadecimale. Il livello di dettaglio è specificato in questo comando tramite 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 in esecuzione per il tempo necessario a 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 effettua il tracciamento su Windows, copiare il file in un sistema Windows. Visualizzare il file di traccia in PerfView.

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2026-08-24