SqlClient でのイベントのトレースの有効化

適用対象: .NET Framework .NET Core .NET Standard

ADO.NET のダウンロード

Windows イベント トレーシング (ETW) は、効率的なカーネル レベルのトレース機能で、デバッグとテストの目的でドライバー定義イベントをログに記録することができます。 SqlClient では、さまざまな情報レベルでの ETW イベントのキャプチャがサポートされています。 イベント トレースのキャプチャを開始するには、クライアント アプリケーションで SqlClient の EventSource 実装からのイベントをリッスンする必要があります。

Microsoft.Data.SqlClient.EventSource

現在の実装では、次のイベント キーワードがサポートされています。

キーワード名	値	[説明]
ExecutionTrace	1	コマンドの実行前と実行後の Start/Stop イベントのキャプチャをオンにします。
Trace	2	基本的なアプリケーション フロー トレース イベントのキャプチャをオンにします。
Scope	4	enter イベントと exit イベントのキャプチャをオンにします
NotificationTrace	8	SqlNotification トレース イベントのキャプチャをオンにします
NotificationScope	16	SqlNotification スコープの enter イベントと exit イベントのキャプチャをオンにします
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 を使用してトレース ログを収集する

1. 次のコマンドを使ってトレースを開始します。

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

2. ネイティブ SNI のトレースの例を実行して、SQL Server に接続します。

3. 次のコマンド ラインを使用してトレースを停止します。

   xperf -stop trace
   

4. PerfView を使用して、ステップ 1 で指定した myTrace.etl ファイルを開きます。 SNI トレース ログは、Microsoft.Data.SqlClient.EventSource/SNIScope および Microsoft.Data.SqlClient.EventSource/SNITrace のイベント名で見つけることができます。

   

PerfView を使用してトレース ログを収集する

1. PerfView を開始し、メニュー バーから Collect > Collect を実行します。

2. トレース ファイル名、出力パス、プロバイダー名を構成します。

   

3. 収集を開始します。

4. ネイティブ SNI のトレースの例を実行して、SQL Server に接続します。

5. PerfView から収集を停止します。 手順 2 の構成に従って PerfViewData.etl ファイルを生成するには、しばらく時間がかかります。

6. PerfView で etl ファイルを開きます。 SNI トレース ログは、Microsoft.Data.SqlClient.EventSource/SNIScope および Microsoft.Data.SqlClient.EventSource/SNITrace のイベント名で見つけることができます。

外部リソース

Microsoft.Data.SqlClient クロスプラットフォームをトレースする方法の別の例については、CSS SQL Networking Tools wiki を参照してください。

イベント トレースの詳細については、次のリソースを参照してください。

リソース	説明
EventSource クラス	ETW イベントを作成するために使用されます。
EventListener クラス	イベント ソースからのイベントを有効または無効にするメソッドを提供します。