Включение трассировки событий в SqlClient

Статья
05/23/2023

Применимо: платформа .NET Framework .NET Standard

Средство трассировки событий для Windows (ETW) является эффективным средством трассировки на уровне ядра, которое позволяет записывать в журнал события, определяемые драйвером, в целях отладки и тестирования. SqlClient поддерживает запись событий ETW на разных информационных уровнях. Чтобы начать сбор трассировок событий, клиентские приложения должны прослушивать события от реализации EventSource для SqlClient.

Microsoft.Data.SqlClient.EventSource

Текущая реализация поддерживает следующие ключевые слова событий.

Имя ключевого слова	значение	Описание
ExecutionTrace	1	Включает запись событий запуска и приостанавливается до и после выполнения команды.
Трассировка	2	Включает запись основных событий трассировки потока приложений.
Область	4	Включает запись событий входа и выхода.
NotificationTrace	8	Включает запись событий трассировки `SqlNotification`.
NotificationScope	16	Включает запись событий входа в область `SqlNotification` и выхода из нее.
PoolerTrace	32	Включает запись событий трассировки потока для пула соединений.
PoolerScope	64	Включает запись событий трассировки области пула соединений.
AdvancedTrace	128	Включает запись событий расширенной трассировки потока.
AdvancedTraceBin	256	Включает запись событий расширенной трассировки потока с дополнительными сведениями.
CorrelationTrace	512	Включает запись событий трассировки потока корреляции.
StateDump	1024	Включает запись дампа полного состояния `SqlConnection`.
SNITrace	2048	Включает запись событий трассировки потока из реализации управляемой сети (применимо только в .NET Core).
SNIScope	4096	Включает запись событий области из реализации управляемой сети (применимо только в .NET Core).

Пример

В следующем примере включается трассировка событий для операции с данными в образце базы данных AdventureWorks и отображаются события в окне консоли.

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

Поддержка трассировки событий в нативной библиотеке SNI

Начиная с версии 2.1 Microsoft.Data.SqlClient расширяет поддержку трассировки событий, реализованную в Microsoft.Data.SqlClient.SNI и Microsoft.Data.SqlClient.SNI.Runtime. События можно собирать из собственных библиотек DLL с помощью средств Xperf и PerfView.

Начиная с Microsoft.Data.SqlClient версии 3.0 трассировку событий можно включить без изменений в клиентском приложении с помощью средств сбора данных о событиях.

В Microsoft.Data.SqlClient версии 2.1 необходимо включить трассировку событий, указав для EventCommand прослушиватель источника событий. Допустимые EventCommand значения, применимые к Собственному SNI:


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

В следующем примере включается трассировка событий в собственных библиотеках SNI DLL.

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

Запустите трассировку с помощью следующей команды.
```
xperf -start trace -f myTrace.etl -on *Microsoft.Data.SqlClient.EventSource
```
Запустите собственный пример трассировки SNI и подключитесь к SQL Server.
Остановите трассировку с помощью следующей командной строки.
```
xperf -stop trace
```
С помощью PerfView откройте файл myTrace.etl, указанный на шаге 1. Журнал трассировки SNI можно найти с помощью имен событий Microsoft.Data.SqlClient.EventSource/SNIScope и Microsoft.Data.SqlClient.EventSource/SNITrace.

Использование PerfView для сбора журнала трассировки

Запустите PerfView и запустите Collect > Collect из строки меню.
Настройте имя файла трассировки, выходной путь и имя поставщика.
Запустите коллекцию.
Запустите собственный пример трассировки SNI и подключитесь к SQL Server.
Остановите сбор в PerfView. Для создания файла PerfViewData.etl требуется некоторое время в соответствии с конфигурацией на шаге 2.
Откройте файл etl в PerfView. Журнал трассировки SNI можно найти с помощью имен событий Microsoft.Data.SqlClient.EventSource/SNIScope и Microsoft.Data.SqlClient.EventSource/SNITrace.

Внешние ресурсы

Другой набор примеров трассировки кроссплатформенных средств Microsoft.Data.SqlClient см. в вики-сайте CSS SQL Networking Tools.

Дополнительные сведения о трассировке событий см. в следующих ресурсах.

Ресурс	Description
EventSource	Используется для создания событий ETW.
Класс EventListener	Предоставляет методы для включения и отключения событий из источников событий.

Share via