Povolení trasování událostí v SqlClient

Platí pro: .NET Framework .NET Standard

Trasování událostí pro Windows (ETW) je efektivní trasovací zařízení na úrovni jádra, které umožňuje protokolovat události definované ovladačem pro účely ladění a testování. SqlClient podporuje zachytávání událostí etW na různých informačních úrovních. Aby klientské aplikace začaly zaznamenávat trasování událostí, měly by naslouchat událostem z implementace EventSource SqlClientu:

Microsoft.Data.SqlClient.EventSource

Aktuální implementace podporuje následující klíčová slova událostí:

Název klíčového slova	Hodnota	Description
ExecutionTrace	1	Zapne zachytávání událostí Start/Stop před a po spuštění příkazu.
Trasování	2	Zapne zachytávání základních událostí trasování toku aplikací.
Scope	4	Zapne zachytávání událostí vstupu a ukončení.
NotificationTrace	8	Zapne zachytávání `SqlNotification` událostí trasování.
NotificationScope	16	Zapne zachytávání `SqlNotification` událostí vstupu do oboru a jeho opuštění.
PoolerTrace	32	Zapne zachytávání událostí trasování toku při sdružování připojení.
PoolerScope	64	Zapne zachytávání trasovacích událostí pro obor sdružování připojení.
AdvancedTrace	128	Zapne zachytávání pokročilých událostí trasování toku.
AdvancedTraceBin	256	Zapne zachytávání pokročilých událostí trasování toku s dalšími informacemi.
CorrelationTrace	512	Zapne zaznamenávání událostí trasování korelačního toku.
StateDump	1024	Zapne zachytávání úplného výpisu stavu `SqlConnection`
SNITrace	2048	Zapne zachytávání událostí sledování toku ze spravované síťové implementace (platí pouze pro .NET Core).
SNIScope	4096	Zapne zachytávání událostí rozsahu z implementace spravovaných sítí (platí pouze v .NET Core).

Example

Následující příklad umožňuje trasování událostí pro datovou operaci v ukázkové databázi AdventureWorks a zobrazí události v okně konzoly.

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

Podpora trasování událostí v nativním SNI

Microsoft.Data.SqlClient poskytuje podporu trasování událostí v Microsoft.Data.SqlClient.SNI a Microsoft.Data.SqlClient.SNI.runtime počínaje verzí 2.1. Události lze shromažďovat z nativních knihoven DLL pomocí nástrojů Xperf a PerfView .

Od Microsoft.Data.SqlClient v3.0 je možné povolit trasování událostí bez jakýchkoli úprav v klientské aplikaci pomocí nástrojů pro shromažďování událostí.

S Microsoft.Data.SqlClient verze 2.1 je potřeba povolit trasování událostí konfigurací naslouchacího zařízení pro zdroj událostí EventCommand. Platné EventCommand hodnoty platné pro nativní SNI jsou:

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

Následující příklad umožňuje trasování událostí v nativních knihovnách DLL SNI.

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

Použijte Xperf ke shromažďování trasování

Spusťte trasování pomocí následujícího příkazu.

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

Spuštěním nativního příkladu trasování SNI se připojte k SQL Serveru.
Ukončete trasování pomocí následujícího příkazového řádku.
```
xperf -stop trace
```
Pomocí perfView otevřete soubor myTrace.etl zadaný v kroku 1. Protokol trasování SNI lze nalézt se Microsoft.Data.SqlClient.EventSource/SNIScope a Microsoft.Data.SqlClient.EventSource/SNITrace názvy událostí.

Pomocí nástroje PerfView lze shromažďovat trasování

Spusťte nástroj PerfView a spusťte Collect > Collect ho z řádku nabídek.
Nakonfigurujte název trasovacího souboru, výstupní cestu a název zprostředkovatele.
Spusťte sběr.
Spuštěním nativního příkladu trasování SNI se připojte k SQL Serveru.
Zastavte sběr dat z PerfView. Vygenerování souboru PerfViewData.etl podle konfigurace v kroku 2 chvíli trvá.
Otevřete etl soubor v nástroji PerfView. Protokol trasování SNI lze nalézt se Microsoft.Data.SqlClient.EventSource/SNIScope a Microsoft.Data.SqlClient.EventSource/SNITrace názvy událostí.

Shromažďování trasování pomocí dotnet-trace

Na Linuxu, macOS nebo Windows lze k zachycení sledování použít dotnet-trace. Nástroj dotnet-trace slouží ke shromažďování sledování pro aplikace .NET. Další informace o dotnet-trace naleznete v nástroji pro analýzu výkonu dotnet-trace Trasování vytvořené pomocí dotnet-trace lze zobrazit v nástroji PerfView.

Pokud ještě není nainstalovaná, nainstalujte na klientský počítač sadu .NET SDK .
Nainstalujte dotnet-trace.

Spusťte příkaz dotnet-trace. Parametr --providers vyžaduje zadání názvu zprostředkovatele a klíčových slov pro trasování z Microsoft.Data.SqlClient. Možnost 'klíčová slova' je součet hodnot klíčových slov v tabulce klíčových slov události převedených na šestnáctková čísla. Chcete-li shromáždit všechny události na podrobné úrovni MyApplication od začátku aplikace, je součet klíčových slov 8191 a 1FFF v šestnáctkové soustavě. Úroveň podrobností je v tomto příkazu určena pomocí 5.

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

Výstup je:


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

Pokud chcete shromáždit všechny události na úrovni informací spuštěné aplikace, nejprve vyhledejte ID procesu aplikace. Pak spusťte v procesu dotnet-trace. Úroveň informací je určena parametrem 4.

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

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

Spusťte aplikaci samostatně a nechte ji běžet tak dlouho, jak je potřeba k reprodukci problému. Pokud se jedná o problém s vysokým využitím procesoru, obvykle stačí 5 až 10 sekund.

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.

Název trasovacího souboru končí na .nettrace. Pokud neprobíhá trasování v systému Windows, zkopírujte soubor do systému Windows. Zobrazte trasovací soubor v nástroji PerfView.

Externí zdroje

Další sadu příkladů, jak trasovat Microsoft.Data.SqlClient napříč platformami, najdete na wiki CSS SQL Networking Tools.

Další informace o trasování událostí najdete v následujících zdrojích informací.

Resource	Description
Třída EventSource	Slouží k vytváření ETW událostí.
EventListener – třída	Poskytuje metody pro povolení a zakázání událostí ze zdrojů událostí.

Váš názor

Byla tato stránka užitečná?

Last updated on 2025-12-04