Mulai menggunakan EventSource

Artikel ini berlaku untuk: ✔️ .NET Core 3.1 dan versi yang lebih baru ✔️ .NET Framework 4.5 dan versi yang lebih baru

Panduan ini menunjukkan cara mencatat peristiwa baru dengan System.Diagnostics.Tracing.EventSource, mengumpulkan peristiwa dalam file pelacakan, melihat jejak, dan memahami konsep EventSource dasar.

Nota

Banyak teknologi yang terintegrasi dengan EventSource menggunakan istilah 'Pelacakan' dan 'Jejak' alih-alih 'Logging' dan 'Log'. Maknanya sama di sini.

Mencatat peristiwa

Tujuan dari EventSource adalah untuk memungkinkan pengembang .NET menulis kode seperti ini untuk mencatat peristiwa:

DemoEventSource.Log.AppStarted("Hello World!", 12);

Baris kode ini memiliki objek pengelogan (DemoEventSource.Log), metode yang mewakili peristiwa untuk dicatat (AppStarted), dan secara opsional beberapa parameter peristiwa yang di ketik dengan kuat (HelloWorld! dan 12). Tidak ada tingkat verbositas, ID peristiwa, templat pesan, atau hal lain yang tidak perlu berada di situs panggilan. Semua informasi lain tentang peristiwa ini ditulis dengan mendefinisikan kelas baru yang berasal dari System.Diagnostics.Tracing.EventSource.

Berikut adalah contoh minimal lengkap:

using System.Diagnostics.Tracing;

namespace EventSourceDemo
{
    public static class Program
    {
        public static void Main(string[] args)
        {
            DemoEventSource.Log.AppStarted("Hello World!", 12);
        }
    }

    [EventSource(Name = "Demo")]
    class DemoEventSource : EventSource
    {
        public static DemoEventSource Log { get; } = new DemoEventSource();

        [Event(1)]
        public void AppStarted(string message, int favoriteNumber) => WriteEvent(1, message, favoriteNumber);
    }
}

Kelas DemoEventSource mendeklarasikan metode untuk setiap jenis peristiwa yang ingin Anda catat. Dalam hal ini, satu peristiwa yang disebut 'AppStarted' didefinisikan oleh metode AppStarted(). Setiap kali kode memanggil metode AppStarted, peristiwa AppStarted lain akan direkam dalam pelacakan jika peristiwa diaktifkan. Ini adalah beberapa data yang dapat diambil dengan setiap peristiwa:

• Nama peristiwa - Nama yang mengidentifikasi jenis peristiwa yang dicatat. Nama peristiwa akan identik dengan nama metode, 'AppStarted' dalam kasus ini.
• ID Peristiwa - ID numerik yang mengidentifikasi jenis peristiwa yang dicatat. Ini melayani peran yang sama dengan nama tetapi dapat membantu dalam pemrosesan log otomatis yang cepat. Acara AppStarted memiliki ID 1, yang diidentifikasi dengan EventAttribute.
• Nama sumber - Nama EventSource yang berisi peristiwa. Ini digunakan sebagai namespace (ruang nama) untuk peristiwa. Nama peristiwa dan ID hanya perlu unik dalam cakupan sumbernya. Di sini sumber diberi nama "Demo", ditentukan dalam EventSourceAttribute pada definisi kelas. Nama sumber juga biasa disebut sebagai nama penyedia.
• Argumen - Semua nilai argumen metode diserialisasikan.
• Informasi lain - Peristiwa juga dapat berisi tanda waktu, ID utas, ID prosesor, ID Aktivitas, jejak tumpukan, dan metadata peristiwa seperti templat pesan, tingkat verbositas, dan kata kunci.

Untuk informasi selengkapnya dan praktik terbaik tentang membuat peristiwa, lihat Kode instrumenting untuk membuat peristiwa.

Mengumpulkan dan melihat file pelacakan

Tidak ada konfigurasi yang diperlukan dalam kode yang menjelaskan peristiwa mana yang harus diaktifkan, tempat data yang dicatat harus dikirim, atau format data apa yang harus disimpan. Jika Anda menjalankan aplikasi sekarang, aplikasi tersebut tidak akan menghasilkan file pelacakan apa pun secara default. EventSource menggunakan pola Terbitkan-berlangganan, yang mengharuskan penerima untuk menunjukkan event yang harus diaktifkan dan mengontrol semua serialisasi untuk event yang diterima. EventSource memiliki integrasi untuk berlangganan dari Event Tracing for Windows (ETW) dan EventPipe (hanya.NET Core). Pelanggan kustom juga dapat dibuat menggunakan API System.Diagnostics.Tracing.EventListener.

Demo ini menunjukkan contoh EventPipe untuk aplikasi .NET Core. Untuk mempelajari tentang opsi lainnya, lihat Mengumpulkan dan melihat jejak peristiwa. EventPipe adalah teknologi pelacakan terbuka dan lintas platform yang dibangun ke dalam runtime .NET Core untuk memberikan alat pengumpulan jejak pengembang .NET dan format pelacakan ringkas portabel (file*.nettrace). dotnet-trace adalah alat baris perintah yang mengumpulkan jejak EventPipe.

1. Unduh dan Instal dotnet-trace.
2. Bangun aplikasi konsol di atas. Demo ini mengasumsikan aplikasi diberi nama EventSourceDemo.exe dan berada di direktori saat ini. Jalankan di baris perintah:

>dotnet-trace collect --providers Demo -- EventSourceDemo.exe

Ini akan menunjukkan output yang mirip dengan:

Provider Name                           Keywords            Level               Enabled By
Demo                                    0xFFFFFFFFFFFFFFFF  Verbose(5)          --providers

Launching: EventSourceDemo.exe
Process        : E:\temp\EventSourceDemo\bin\Debug\net6.0\EventSourceDemo.exe
Output File    : E:\temp\EventSourceDemo\bin\Debug\net6.0\EventSourceDemo.exe_20220303_001619.nettrace

[00:00:00:00]   Recording trace 0.00     (B)
Press <Enter> or <Ctrl+C> to exit...

Trace completed.

Perintah ini dijalankan EventSourceDemo.exe dengan semua peristiwa di 'Demo' EventSource diaktifkan dan menghasilkan file jejak keluaran EventSourceDemo.exe_20220303_001619.nettrace. Membuka file di Visual Studio memperlihatkan peristiwa yang dicatat.

Dalam tampilan daftar, Anda dapat melihat peristiwa pertama adalah peristiwa Demo/AppStarted. Kolom teks memiliki argumen yang disimpan, kolom tanda waktu memperlihatkan peristiwa terjadi 27 ms setelah pengelogan dimulai dan di sebelah kanan Anda dapat melihat tumpukan panggilan. Acara lainnya secara otomatis diaktifkan di setiap jejak yang dikumpulkan oleh dotnet-trace, meskipun dapat diabaikan dan disaring dari tampilan di antarmuka pengguna jika mengganggu. Peristiwa tambahan tersebut menangkap beberapa informasi tentang proses dan kode jitted, yang memungkinkan Visual Studio untuk membangun kembali jejak tumpukan peristiwa.

Mempelajari selengkapnya tentang EventSource

• Kode instrumenting untuk membuat peristiwa
• Mengumpulkan dan melihat jejak peristiwa