在 SqlClient 中啟用事件追蹤

發行項
05/23/2023

適用於：.NET Framework .NET .NET Standard

Windows 事件追蹤 (ETW) 是一種有效率的核心等級追蹤設施，可讓您記錄驅動程式定義的事件以進行偵錯及測試。 SqlClient 支援在不同資訊層級上擷取 ETW 事件。若要開始擷取事件追蹤，用戶端應用程式應接聽 SqlClient EventSource 實作的事件：

Microsoft.Data.SqlClient.EventSource

目前的實作支援下列事件關鍵字：

關鍵字名稱	值	描述
ExecutionTrace	1	開啟/停止擷取命令執行前後的事件。
追蹤	2	開啟擷取基本應用程式流程追蹤事件。
影響範圍	4	開啟擷取輸入和結束事件
NotificationTrace	8	開啟擷取 `SqlNotification` 追蹤事件
NotificationTrace	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 中的事件追蹤支援

Microsoft.Data.SqlClient 從 v2.1 開始，在 Microsoft.Data.SqlClient.SNI 與 Microsoft.Data.SqlClient.SNI.runtime 中提供了事件追蹤支援。您可以使用 Xperf (部分機器翻譯) 與 PerfView (英文) 工具，從原生 DLL 收集事件。

從 Microsoft.Data.SqlClient v3.0 開始，可以在用戶端應用程式中使用事件收集工具來啟用事件追蹤，而不需進行任何修改。

使用 Microsoft.Data.SqlClient v2.1 時，必須使用事件來源接聽程式來設定 EventCommand，以啟用事件追蹤。適用於原生 SNI 的有效 EventCommand 值如下：


// 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 來開啟步驟 1 中所指定的 myTrace.etl 檔案。您可以使用 Microsoft.Data.SqlClient.EventSource/SNIScope 與 Microsoft.Data.SqlClient.EventSource/SNITrace 的事件名稱來找到 SNI 追蹤記錄。

使用 PerfView 來收集追蹤記錄

從功能表列啟動 PerfView 並執行 Collect > Collect。
設定追蹤檔案名稱、輸出路徑與提供者名稱。
開始收集。
執行原生 SNI 追蹤範例，以連線到 SQL Server。
從 PerfView 停止收集。根據步驟 2 中的設定產生 PerfViewData.etl 檔案需要一些時間。
在 PerfView 中開啟 etl 檔案。您可以使用 Microsoft.Data.SqlClient.EventSource/SNIScope 與 Microsoft.Data.SqlClient.EventSource/SNITrace 的事件名稱來找到 SNI 追蹤記錄。

外部資源

如需如何跨平台追蹤 Microsoft.Data.SqlClient 的另一組範例，請參閱 CSS SQL 網路工具 Wiki (英文)。

如需事件追蹤的詳細資訊，請參閱下列資源。

資源	說明
EventSource 類別	用來建立 ETW 事件。
EventListener 類別	提供啟用和停用事件來源事件的方法。

共用方式為