次の方法で共有


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

適用対象: .NET Framework .NET .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.SNIMicrosoft.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 を使用して SNI のトレース ファイルを表示する

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

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

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

    収集の前に Perfview を構成する

  3. 収集を開始します。

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

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

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

dotnet-trace を使用してトレースを収集する

Linux、macOS、または Windows では、dotnet-trace を使用してトレースをキャプチャできます。 donet-trace ツールは、.NET アプリケーションのトレースを収集するために使用されます。 dotnet-trace の詳細については、「dotnet-trace パフォーマンス分析ユーティリティ」を参照してください。dotnet-trace によって作成されたトレースは、PerfView で表示できます。

  1. まだインストールされていない場合は、クライアント マシンに .NET SDK をインストールします

  2. dotnet-trace をインストールします

  3. dotnet-trace を実行します。 --providers パラメーターでは、Microsoft.Data.SqlClient からのトレースにプロバイダー名とキーワードを指定する必要があります。 キーワード オプションは、16 進数に変換されたイベント キーワード テーブル内のキーワード値の合計です。 アプリケーションの開始時から MyApplication の詳細レベルで、すべてのイベントを収集するには、キーワードの合計は 8191 で、16 進数で 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'.
    

    実行中のアプリケーションの情報レベルで、すべてのイベントを収集するには、まずアプリケーションのプロセス ID を見つけます。 次に、プロセスで 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
    

    アプリケーションを個別に実行し、この問題を再現するために必要な時間だけ実行します。 CPU の問題が高い場合は、通常、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 wiki を参照してください。

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

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