Aktivieren der Ereignisablaufverfolgung in SqlClient

Gilt für: .NET Framework .NET .NET Standard

Herunterladen von ADO.NET

Die Ereignisablaufverfolgung für Windows (ETW) ist eine effiziente Funktion für die Ablaufverfolgung auf Kernelebene, mit der Sie vom Treiber definierte Ereignisse zu Debug- und Testzwecken protokollieren können. SqlClient unterstützt das Erfassen von ETW-Ereignissen auf verschiedenen Informationsebenen. Clientanwendungen sollten auf Ereignisse aus der EventSource-Implementierung von SqlClient lauschen, um die Erfassung von Ereignisablaufverfolgungen zu starten.

Microsoft.Data.SqlClient.EventSource

Die aktuelle Implementierung unterstützt die folgenden Schlüsselwörter für Ereignisse:

Beispiel

Im folgenden Beispiel wird die Ereignisablaufverfolgung für einen Datenvorgang für die AdventureWorks-Beispieldatenbank aktiviert, und die Ereignisse werden im Konsolenfenster angezeigt.

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

Unterstützung der Ereignisverfolgung in Native SNI

Microsoft.Data.SqlClient bietet ab Version 2.1 Unterstützung für Ereignisablaufverfolgung in Microsoft.Data.SqlClient.SNI und Microsoft.Data.SqlClient.SNI.runtime. Ereignisse können mithilfe der Tools Xperf und PerfView von den nativen DLLs erfasst werden.

Ab Microsoft.Data.SqlClient-Version 3.0 kann die Ereignisablaufverfolgung mithilfe von Ereignissammlungstools ohne Änderungen in der Clientanwendung aktiviert werden.

Mit Microsoft.Data.SqlClient v2.1 muss die Ereignisverfolgung aktiviert werden, indem EventCommand mit einem Ereignisquellenlistener konfiguriert wird. Die gültigen EventCommand-Werte für native SNI-Dateien sind:

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

Im folgenden Beispiel wird die Ereignisablaufverfolgung in nativen SNI-DLLs aktiviert.

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

Verwenden Sie Xperf, um Ablaufverfolgungsdaten zu erfassen.

1. Starten Sie die Ablaufverfolgung mit dem folgenden Befehl.

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

2. Führen Sie das Beispiel der nativen SNI-Ablaufverfolgung aus, um eine Verbindung mit SQL Server herzustellen.

3. Beenden Sie die Nachverfolgung mit dem folgenden Befehlszeilenbefehl.

   xperf -stop trace
   

4. Öffnen Sie mithilfe von PerfView die in Schritt 1 angegebene Datei „myTrace.etl“. Das SNI-Ablaufverfolgungsprotokoll kann anhand der Ereignisnamen Microsoft.Data.SqlClient.EventSource/SNIScope und Microsoft.Data.SqlClient.EventSource/SNITrace gefunden werden.

   

Verwenden Sie PerfView, um Traces zu sammeln

1. Starten Sie PerfView und wählen Sie in der Menüleiste Collect > Collect aus.

2. Konfigurieren Sie den Namen der Ablaufverfolgungsdatei, den Ausgabepfad und den Anbieternamen.

   

3. Starten Sie die Sammlung.

4. Führen Sie das Beispiel der nativen SNI-Ablaufverfolgung aus, um eine Verbindung mit SQL Server herzustellen.

5. Beenden Sie die Datensammlung in PerfView. Das Generieren der Datei „PerfViewData.etl“ wird je nach Konfiguration in Schritt 2 eine Weile dauern.

6. Öffnen Sie die etl-Datei in PerfView. Das SNI-Ablaufverfolgungsprotokoll kann anhand der Ereignisnamen Microsoft.Data.SqlClient.EventSource/SNIScope und Microsoft.Data.SqlClient.EventSource/SNITrace gefunden werden.

Verwenden Sie dotnet-trace, um Ablaufverfolgungen zu erfassen

Unter Linux, macOS oder Windows kann dotnet-trace zum Aufzeichnen von Traces verwendet werden. Das Tool dotnet-trace wird verwendet, um Ablaufverfolgungen von .NET-Anwendungen zu erfassen. Weitere Informationen zu dotnet-Ablaufverfolgung finden Sie im Leistungsanalyse-Dienstprogramm dotnet-Ablaufverfolgung. Die von dotnet-Ablaufverfolgung erstellten Ablaufverfolgungen können in PerfView angezeigt werden.

1. Falls noch nicht installiert, installieren Sie das .NET SDK auf dem Client-Computer.

2. Installieren von dotnet-trace.

3. Führen Sie dotnet-trace aus. Der --providers-Parameter erfordert, dass der Name des Anbieters und die Schlüsselwörter für Ablaufverfolgungen bei Microsoft.Data.SqlClient angegeben werden. Die Option „Schlüsselwörter“ ist eine Summe der Schlüsselwortwerte in der Ereignisstichwörtertabelle, die in eine Hexadezimalzahl konvertiert wird. Um ab dem Start der Anwendung alle Ereignisse mit der Ausführlichkeitsstufe MyApplication zu sammeln, beträgt die Summe der Schlüsselwörter 8191 bzw. 1FFF in hexadezimaler Schreibweise. Der Ausführlichkeitsgrad wird in diesem Befehl mit 5 festgelegt.

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

   Die Ausgabe lautet:

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

   Um alle Ereignisse auf Informationsebene für eine ausgeführte Anwendung zu sammeln, suchen Sie zuerst die Prozess-ID der Anwendung. Führen Sie dann dotnet-trace für den Prozess aus. Die Informationsstufe wird durch 4 festgelegt.

   dotnet-trace ps
   8734  MyApplication  /home/appuser/MyApplication/MyApplication
   
   dotnet-trace collect --process-id 8734 --providers Microsoft.Data.SqlClient.EventSource:1FFF:4
   

   Führen Sie die Anwendung separat aus, und lassen Sie sie so lange laufen, wie zum Reproduzieren des Problems erforderlich. Wenn es sich um ein Problem mit hoher CPU-Auslastung handelt, sollten 5-10 Sekunden genügen.

   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.
   

   Der Name der Ablaufverfolgungsdatei endet in .nettrace. Wenn keine Nachverfolgung unter Windows durchgeführt wird, kopieren Sie die Datei auf ein Windows-System. Zeigen Sie die Ablaufverfolgungsdatei in PerfView an.

Verwandte Inhalte

• CSS SQL Networking Tools Wiki
• EventSource-Klasse
• EventListener-Klasse