Gebeurtenistracering inschakelen in SqlClient

Van toepassing op: .NET Framework .NET Standard

ADO.NET downloaden

Event Tracing voor Windows (ETW) is een efficiënte traceringsfaciliteit op kernelniveau waarmee u door stuurprogramma's gedefinieerde gebeurtenissen kunt vastleggen voor foutopsporing en testdoeleinden. SqlClient biedt ondersteuning voor het vastleggen van ETW-gebeurtenissen op verschillende informatieniveaus. Om te beginnen met het vastleggen van gebeurtenistraceringen, moeten clienttoepassingen luisteren naar gebeurtenissen uit de EventSource-implementatie van SqlClient:

Microsoft.Data.SqlClient.EventSource

De huidige implementatie ondersteunt de volgende gebeurtenistrefwoorden:

Naam van trefwoord	Waarde	Description
ExecutionTrace	1	Hiermee schakelt u het registreren van Start/Stop-gebeurtenissen vóór en na de uitvoering van de opdracht in.
Trace	2	Hiermee schakelt u het vastleggen van eenvoudige traceringsgebeurtenissen voor de toepassingsstroom in.
Scope	4	Hiermee schakelt u het vastleggen van enter- en afsluitgebeurtenissen in
NotificationTrace	8	Hiermee schakelt u het vastleggen van traceringsevenementen SqlNotification in
NotificationScope	16	Hiermee schakelt u het vastleggen van gebeurtenissen voor het betreden en verlaten van een SqlNotification scope in.
PoolerTrace	32	Hiermee schakelt u het vastleggen van traceergebeurtenissen in de connectiepooling in.
PoolerScope	64	Hiermee schakelt u het vastleggen van traceringsgebeurtenissen voor verbindingsgroepen in.
AdvancedTrace	128	Hiermee schakelt u het vastleggen van geavanceerde stroomtraceergebeurtenissen in.
AdvancedTraceBin	256	Hiermee schakelt u het vastleggen van geavanceerde stroomtraceringsgebeurtenissen in met aanvullende informatie.
CorrelationTrace	512	Hiermee schakelt u het vastleggen van traceringsgebeurtenissen voor correlatiestromen in.
StateDump	1024	Hiermee schakelt u het vastleggen van een volledige statusdump van SqlConnection in.
SNITrace	2048	Schakelt het vastleggen van stroomtraceringsgebeurtenissen uit de implementatie van beheerde netwerken in (alleen van toepassing in .NET Core)
SNIScope	4096	Hiermee schakelt u het vastleggen van scope-gebeurtenissen vanuit de Managed Networking-implementatie in (alleen van toepassing op .NET Core)

Example

In het volgende voorbeeld wordt gebeurtenistracering ingeschakeld voor een gegevensbewerking in de Voorbeelddatabase AdventureWorks en worden de gebeurtenissen weergegeven in het consolevenster.

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

Ondersteuning voor gebeurtenistracering in systeemeigen SNI

Microsoft.Data.SqlClient biedt ondersteuning voor gebeurtenistracering in Microsoft.Data.SqlClient.SNI en Microsoft.Data.SqlClient.SNI.runtime vanaf v2.1. Gebeurtenissen kunnen worden verzameld uit de systeemeigen DLL's met behulp van de hulpprogramma's Xperf en PerfView .

Vanaf Microsoft.Data.SqlClient v3.0 kan gebeurtenistracering worden ingeschakeld zonder wijzigingen in de clienttoepassing met behulp van hulpprogramma's voor gebeurtenisverzameling.

Met Microsoft.Data.SqlClient v2.1 moet gebeurtenistracering worden ingeschakeld door de EventCommand gebeurtenisbronlistener te configureren. De geldige EventCommand waarden die van toepassing zijn op systeemeigen SNI zijn:

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

In het volgende voorbeeld wordt gebeurtenistracering ingeschakeld in systeemeigen SNI-DLL's.

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

Xperf gebruiken om traceringen te verzamelen

1. Start tracering met behulp van de volgende opdracht.

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

2. Voer het systeemeigen SNI-traceringsvoorbeeld uit om verbinding te maken met SQL Server.

3. Stop het traceren met behulp van de volgende opdrachtregel.

   xperf -stop trace
   

4. Gebruik PerfView om het bestand myTrace.etl te openen dat is opgegeven in stap 1. Het SNI-traceringslogboek vindt u met Microsoft.Data.SqlClient.EventSource/SNIScope en Microsoft.Data.SqlClient.EventSource/SNITrace gebeurtenisnamen.

   

PerfView gebruiken om traceringen te verzamelen

1. Start PerfView en voer deze uit Collect > Collect vanuit de menubalk.

2. Configureer de naam van het traceringsbestand, het uitvoerpad en de providernaam.

   

3. Verzameling starten.

4. Voer het systeemeigen SNI-traceringsvoorbeeld uit om verbinding te maken met SQL Server.

5. Verzameling van PerfView stoppen. Het duurt even voordat het PerfViewData.etl-bestand wordt gegenereerd volgens de configuratie in stap 2.

6. Open het etl bestand in PerfView. Het SNI-traceringslogboek vindt u met Microsoft.Data.SqlClient.EventSource/SNIScope en Microsoft.Data.SqlClient.EventSource/SNITrace gebeurtenisnamen.

Dotnet-trace gebruiken om traceringen te verzamelen

In Linux, macOS of Windows kan dotnet-trace worden gebruikt om traceringen vast te leggen. Het dotnet-trace-hulpprogramma wordt gebruikt voor het verzamelen van traceringen voor .NET-toepassingen. Voor meer informatie over dotnet-trace, zie het hulpprogramma dotnet-trace performance analysis. De sporen die door dotnet-trace zijn gemaakt, kunnen in PerfView worden bekeken.

1. Als deze nog niet is geïnstalleerd, installeert u de .NET SDK op de clientcomputer.

2. Installeer dotnet-trace.

3. Voer dotnet-trace uit. Voor de --providers parameter moeten de providernaam en trefwoorden worden opgegeven voor traceringen van Microsoft.Data.SqlClient. De trefwoordoptie is een som van de trefwoordwaarden in de tabel met gebeurtenistrefwoorden die zijn geconverteerd naar hexadecimaal. Als u alle gebeurtenissen wilt verzamelen op het uitgebreide niveau van MyApplication vanaf het begin van de toepassing, is de som van trefwoorden 8191 en 1FFF in hexadecimaal. Het uitgebreide niveau wordt opgegeven in deze opdracht door 5.

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

   De uitvoer is:

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

   Als u alle gebeurtenissen op informatieniveau voor een actieve toepassing wilt verzamelen, zoekt u eerst de proces-id van de toepassing. Voer vervolgens dotnet-trace uit op het proces. Het informatieniveau wordt opgegeven door 4.

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

   Voer de toepassing afzonderlijk uit en laat deze zo lang draaien als nodig is om het probleem te reproduceren. Als het een hoog CPU-probleem is, is 5-10 seconden meestal voldoende.

   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.
   

   De naam van het traceringsbestand eindigt op .nettrace. Als u niet aan het traceren bent op Windows, kopieert u het bestand naar een Windows-systeem. Bekijk het traceringsbestand in PerfView.

Externe middelen

Zie de wiki CSS SQL Networking Tools voor een andere set voorbeelden over het cross-platform traceren van Microsoft.Data.SqlClient.

Zie de volgende bronnen voor meer informatie over gebeurtenistracering.

Hulpbron	Description
EventSource-klasse	Wordt gebruikt om ETW-gebeurtenissen te maken.
EventListener-klasse	Biedt methoden voor het in- en uitschakelen van gebeurtenissen uit gebeurtenisbronnen.