Aktifkan pelacakan kejadian di SqlClient

Berlaku untuk: .NET Framework .NET .NET Standard

Pelacakan Peristiwa untuk Windows (ETW) adalah fasilitas pelacakan yang efisien dan tingkat kernel yang memungkinkan Anda mencatat peristiwa yang ditentukan driver untuk tujuan penelusuran kesalahan dan pengujian. SqlClient mendukung pengambilan peristiwa ETW pada tingkat informasi yang berbeda. Untuk mulai mengambil jejak peristiwa, aplikasi klien harus mendengarkan peristiwa dari implementasi EventSource SqlClient:

Microsoft.Data.SqlClient.EventSource

Implementasi saat ini mendukung Kata Kunci Peristiwa berikut:

Nama kata kunci	Nilai	Deskripsi
ExecutionTrace	1	Mengaktifkan pengambilan peristiwa Mulai/Hentikan sebelum dan sesudah eksekusi perintah.
Trace	2	Mengaktifkan pengambilan peristiwa pelacakan alur aplikasi dasar.
Cakupan	4	Mengaktifkan pengambilan peristiwa masuk dan keluar
NotificationTrace	8	Mengaktifkan pengambilan `SqlNotification` peristiwa pelacakan
NotificationScope	16	Mengaktifkan pengambilan `SqlNotification` lingkup peristiwa masuk dan keluar
PoolerTrace	32	Mengaktifkan pengambilan peristiwa pelacakan aliran pengumpulan koneksi.
PoolerScope	64	Mengaktifkan pengambilan peristiwa pelacakan cakupan pengumpulan koneksi.
AdvancedTrace	128	Mengaktifkan pengambilan peristiwa pelacakan aliran tingkat lanjut.
AdvancedTraceBin	256	Mengaktifkan pengambilan peristiwa pelacakan alur tingkat lanjut dengan informasi tambahan.
CorrelationTrace	512	Mengaktifkan pengambilan peristiwa pelacakan aliran korelasi.
StateDump	1024	Mengaktifkan penangkapan cadangan status penuh dari `SqlConnection`
SNITrace	2048	Mengaktifkan pengambilan peristiwa pelacakan alur dari implementasi Jaringan Terkelola (hanya berlaku di .NET Core)
Cakupan SNI	4096	Mengaktifkan pengambilan peristiwa cakupan dari implementasi Jaringan Terkelola (hanya berlaku di .NET Core)

Contoh

Contoh berikut memungkinkan pelacakan peristiwa untuk operasi data pada database sampel AdventureWorks dan menampilkan peristiwa di jendela konsol.

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

Dukungan pelacakan peristiwa di SNI Asli

Microsoft.Data.SqlClient menyediakan dukungan pelacakan peristiwa di Microsoft.Data.SqlClient.SNI dan Microsoft.Data.SqlClient.SNI.runtime dimulai dengan v2.1. Peristiwa dapat dikumpulkan dari DLL asli menggunakan alat Xperf dan PerfView .

Dimulai dengan Microsoft.Data.SqlClient v3.0, pelacakan peristiwa dapat diaktifkan tanpa modifikasi apa pun di aplikasi klien menggunakan alat pengumpulan peristiwa.

Dengan Microsoft.Data.SqlClient v2.1, pelacakan peristiwa perlu diaktifkan dengan mengonfigurasi EventCommand dengan pendengar sumber peristiwa. Nilai yang valid EventCommand yang berlaku untuk SNI Asli adalah:

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

Contoh berikut memungkinkan pelacakan peristiwa di DLL SNI asli.

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

Menggunakan Xperf untuk mengumpulkan jejak

Mulai lacak menggunakan perintah berikut.

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

Jalankan contoh pelacakan SNI asli untuk menyambungkan ke SQL Server.
Hentikan pelacakan menggunakan baris perintah berikut.
```
xperf -stop trace
```
Gunakan PerfView untuk membuka file myTrace.etl yang ditentukan di Langkah 1. Log pelacakan SNI dapat ditemukan dengan Microsoft.Data.SqlClient.EventSource/SNIScope nama peristiwa dan Microsoft.Data.SqlClient.EventSource/SNITrace .

Menggunakan PerfView untuk mengumpulkan jejak

Mulai PerfView dan jalankan Collect > Collect dari bilah menu.
Konfigurasikan nama file pelacakan, jalur output, dan nama penyedia.
Mulai koleksi.
Jalankan contoh pelacakan SNI asli untuk menyambungkan ke SQL Server.
Hentikan pengumpulan dari PerfView. Dibutuhkan beberapa saat untuk menghasilkan file PerfViewData.etl sesuai dengan konfigurasi di Langkah 2.
etl Buka file di PerfView. Log pelacakan SNI dapat ditemukan dengan Microsoft.Data.SqlClient.EventSource/SNIScope nama peristiwa dan Microsoft.Data.SqlClient.EventSource/SNITrace .

Gunakan dotnet-trace untuk mengumpulkan jejak

Di Linux, macOS, atau Windows, dotnet-trace dapat digunakan untuk mengambil jejak. Alat dotnet-trace digunakan untuk mengumpulkan jejak untuk aplikasi .NET. Untuk informasi selengkapnya tentang dotnet-trace, lihat utilitas analisis performa dotnet-trace Jejak yang dibuat oleh dotnet-trace dapat dilihat di PerfView.

Jika belum diinstal, instal .NET SDK pada komputer klien.
Pasang dotnet-trace.

Jalankan dotnet-trace. Parameter --providers mengharuskan nama penyedia dan kata kunci ditentukan untuk jejak dari Microsoft.Data.SqlClient. Opsi kata kunci adalah jumlah nilai kata kunci dalam tabel kata kunci peristiwa yang dikonversi menjadi heksadesimal. Untuk mengumpulkan semua peristiwa di tingkat MyApplication verbose dari awal aplikasi, jumlah kata kunci adalah 8191 dan 1FFF dalam heksadesimal. Tingkat verbose ditentukan dalam perintah ini oleh 5.

dotnet-trace collect --providers Microsoft.Data.SqlClient.EventSource:1FFF:5 -- dotnet MyApplication.dll

Outputnya adalah:


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'.

Untuk mengumpulkan semua peristiwa di tingkat informasi pada aplikasi yang sedang berjalan, pertama-tama temukan ID proses aplikasi. Kemudian jalankan dotnet-trace pada proses. Tingkat informasi ditentukan oleh 4.

dotnet-trace ps
8734  MyApplication  /home/appuser/MyApplication/MyApplication

dotnet-trace collect -–process-id 8734 --providers Microsoft.Data.SqlClient.EventSource:1FFF:4

Jalankan aplikasi secara terpisah dan biarkan berjalan selama yang diperlukan untuk mereprodurasi masalah. Jika masalah CPU tinggi, 5-10 detik biasanya cukup.

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.

Nama file pelacakan berakhiran .nettrace. Jika tidak dilacak pada Windows, salin file ke sistem Windows. Lihat file pelacakan di PerfView.

Sumber daya eksternal

Untuk serangkaian contoh lain tentang cara melacak lintas platform Microsoft.Data.SqlClient, lihat wiki Alat Jaringan CSS SQL.

Untuk informasi selengkapnya tentang pelacakan peristiwa, lihat sumber daya berikut ini.

Sumber daya	Deskripsi
Kelas EventSource	Digunakan untuk membuat peristiwa ETW.
Kelas EventListener	Menyediakan metode untuk mengaktifkan dan menonaktifkan peristiwa dari sumber peristiwa.

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2025-12-04