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:

Name des Schlüsselworts	Wert	BESCHREIBUNG
ExecutionTrace	1	Dieses Schlüsselwort aktiviert die Erfassung von Start/Stop-Ereignissen vor und nach der Befehlsausführung.
Trace	2	Dieses Schlüsselwort aktiviert die Erfassung einfacher Ereignisse der Anwendungsflowablaufverfolgung.
`Scope`	4	Dieses Schlüsselwort aktiviert die Erfassung von Enter- und Exit-Ereignissen.
NotificationTrace	8	Dieses Schlüsselwort aktiviert die Erfassung von SqlNotification-Ablaufverfolgungsereignissen.
NotificationScope	16	Dieses Schlüsselwort aktiviert Enter- und Exit-Ereignisse im SqlNotification-Bereich.
PoolerTrace	32	Dieses Schlüsselwort aktiviert Ablaufverfolgungsereignisse des Verbindungspoolingflows.
PoolerScope	64	Dieses Schlüsselwort aktiviert Ablaufverfolgungsereignisse des Verbindungspoolingbereichs.
AdvancedTrace	128	Dieses Schlüsselwort aktiviert die Erfassung erweiterter Flowablaufverfolgungsereignisse.
AdvancedTraceBin	256	Dieses Schlüsselwort aktiviert die Erfassung erweiterter Flowablaufverfolgungsereignisse mit zusätzlichen Informationen.
CorrelationTrace	512	Dieses Schlüsselwort aktiviert die Erfassung von Ablaufverfolgungsereignissen für Korrelationsflows.
StateDump	1024	Dieses Schlüsselwort aktiviert die Erfassung einer vollständigen Statussicherung von SqlConnection.
SNITrace	2048	Dieses Schlüsselwort aktiviert die Erfassung von Flowablaufverfolgungsereignissen in der Implementierung von verwalteten Netzwerken (gilt nur für .NET Core).
SNIScope	4096	Dieses Schlüsselwort aktiviert die Erfassung von Bereichsablaufverfolgungsereignissen in der Implementierung von verwalteten Netzwerken (gilt nur für .NET Core).

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 Ereignisablaufverfolgung in nativer SNI-Datei

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.

In Version 2.1 von Microsoft.Data.SqlClient muss die Ereignisablaufverfolgung durch die Konfiguration von EventCommand mit dem Ereignisquelllistener aktiviert werden. 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();
        }
    }
}

Erfassen der Ablaufverfolgung mit Xperf

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 Ablaufverfolgung über die folgende Befehlszeile.

   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.

   

Erfassen der Ablaufverfolgung mit PerfView

1. Starten Sie PerfView, und führen Sie über die Menüleiste Collect > Collect aus.

2. Konfigurieren Sie den Namen der Ablaufverfolgungsdatei, Ausgabepfad und 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 Sammlung 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.

Externe Ressourcen

Weitere Beispiele zur plattformübergreifenden Ablaufverfolgung von Microsoft.Data.SqlClient finden Sie im Wiki zu CSS-SQL-Netzwerktools.

Weitere Informationen zur Ereignisablaufverfolgung finden Sie in den folgenden Ressourcen.

Resource	BESCHREIBUNG
EventSource-Klasse	Dient zum Erstellen von ETW-Ereignissen.
EventListener-Klasse	Diese Klasse stellt Methoden zum Aktivieren und Deaktivieren von Ereignissen aus Ereignisquellen bereit.