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

Статья
09/28/2024

Область применения: платформа .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.

Использование dotnet-trace для сбора трассировок

В Linux, macOS или Windows можно использовать dotnet-trace для записи трассировок. Средство готовой трассировки используется для сбора трассировок для приложений .NET. Дополнительные сведения о dotnet-trace см. в служебной программе анализа производительности dotnet-trace. Трассировки, созданные dotnet-trace, можно просмотреть в PerfView.

Если он еще не установлен, установите пакет SDK для .NET на клиентском компьютере.
Установите dotnet-trace.
Запустите dotnet-trace. Параметру --providers требуется указать имя поставщика и ключевые слова для трассировки из Microsoft.Data.SqlClient. Параметр "Ключевые слова" — это сумма значений ключевых слов в таблице ключевых слов событий, преобразованной в шестнадцатеричное значение. Чтобы собрать все события на подробном уровне MyApplication с начала приложения, сумма ключевых слов — 8191 и 1FFF шестнадцатеричная. Подробный уровень указан в этой команде.5
```
dotnet-trace collect --providers Microsoft.Data.SqlClient.EventSource:1FFF:5 -- dotnet MyApplication.dll
```
Результат выглядит так:
```
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'.
```
Чтобы собрать все события на уровне информации в работающем приложении, сначала найдите идентификатор процесса приложения. Затем запустите dotnet-trace в процессе. Уровень информации задается с помощью 4.
```
dotnet-trace ps
8734  MyApplication  /home/appuser/MyApplication/MyApplication

dotnet-trace collect -–process-id 8734 --providers Microsoft.Data.SqlClient.EventSource:1FFF:4
```
Запустите приложение отдельно и разрешите ему работать до тех пор, пока это необходимо для воспроизведения проблемы. Если это высокая проблема ЦП, обычно достаточно 5–10 секунд.
```
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.
```
Имя файла трассировки заканчивается .nettrace. Если не трассировка в Windows, скопируйте файл в систему Windows. Просмотрите файл трассировки в PerfView.

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

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

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

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

Поделиться через