Makro TraceLoggingWrite (traceloggingprovider.h)

Artikel
03/08/2023

Memancarkan peristiwa TraceLogging.

Sintaks

void TraceLoggingWrite(
  [in]            hProvider,
  [in]            eventName,
  [in, optional]  __VA_ARGS__
);

Parameter

[in] hProvider

Handel penyedia TraceLogging yang digunakan untuk menulis peristiwa.

[in] eventName

Nama pendek dan unik yang digunakan untuk mengidentifikasi peristiwa. Ini harus berupa string literal dan bukan variabel. Ini tidak boleh memiliki karakter yang disematkan '\0' .

[in, optional] __VA_ARGS__

Hingga 99 parameter tambahan untuk mengonfigurasi atau menambahkan bidang ke peristiwa. Setiap parameter harus salah satu Makro Pembungkus TraceLogging, seperti TraceLoggingLevel, TraceLoggingKeyword, atau TraceLoggingValue.

Penting

ProviderId, Level, dan Keyword adalah sarana utama untuk memfilter peristiwa. Jenis pemfilteran lainnya dimungkinkan tetapi memiliki overhead yang jauh lebih tinggi. Selalu tetapkan tingkat non-nol dan kata kunci untuk setiap peristiwa.

Menampilkan nilai

Tidak ada

Keterangan

Setiap pemanggilan makro TraceLoggingWrite diperluas ke kode yang diperlukan untuk menulis peristiwa ke ETW melalui handel penyedia yang ditentukan.

TraceLoggingWrite memeriksa apakah penyedia yang ditentukan terdaftar. Jika penyedia tidak terdaftar, TraceLoggingWrite tidak melakukan apa pun.
TraceLoggingWrite memeriksa apakah ada konsumen yang mendengarkan peristiwa tersebut, seolah-olah dengan memanggil TraceLoggingProviderEnabled. Jika tidak ada konsumen yang mendengarkan peristiwa tersebut, TraceLoggingWrite tidak melakukan apa pun.
Jika tidak, TraceLoggingWrite mengevaluasi ekspresi runtime yang ditentukan dalam argumen, menyimpan hasilnya, mengemas data yang diperlukan ke dalam suatu peristiwa, dan memanggil EventWriteTransfer untuk mengirim peristiwa ke ETW.

Peristiwa yang dihasilkan akan dibangun sebagai berikut:

ID penyedia peristiwa, nama penyedia, dan grup penyedia akan berasal dari parameter hProvider .
Nama peristiwa akan berasal dari parameter eventName .
Dalam mode pengguna, ID aktivitas peristiwa akan berasal dari ID aktivitas implisit utas. Dalam mode kernel, ID aktivitas peristiwa akan GUID_NULL.
Peristiwa tidak akan memiliki ID aktivitas terkait.
Tingkat peristiwa akan berasal dari argumen TraceLoggingLevel . Jika tidak ada argumen TraceLoggingLevel, tingkat peristiwa akan menjadi 5 (WINEVENT_LEVEL_VERBOSE). Jika ada lebih dari satu argumen TraceLoggingLevel, argumen terakhir akan digunakan. Untuk mengaktifkan pemfilteran peristiwa yang efektif, selalu tetapkan tingkat non-nol yang bermakna untuk setiap peristiwa.
Kata kunci peristiwa akan berasal dari argumen TraceLoggingKeyword . Jika tidak ada argumen TraceLoggingKeyword, kata kunci peristiwa akan menjadi 0 (TIDAK ADA). Jika ada lebih dari satu argumen TraceLoggingKeyword, nilai akan disatukan OR. Untuk mengaktifkan pemfilteran peristiwa yang efektif, selalu tetapkan kata kunci bukan nol yang bermakna untuk setiap peristiwa.
Atribut peristiwa lainnya dapat diatur oleh argumen seperti TraceLoggingOpcode, TraceLoggingDescription, TraceLoggingEventTag, atau TraceLoggingChannel.
Bidang peristiwa dapat dikelompokkan menggunakan TraceLoggingStruct.
Bidang peristiwa ditambahkan oleh argumen bidang seperti TraceLoggingValue, TraceLoggingInt32, TraceLoggingHResult, TraceLoggingString, dll. Lihat Makro Pembungkus TraceLogging untuk detailnya.

Contohnya:

TraceLoggingWrite(
    g_hProvider,
    "MyEvent1",
    TraceLoggingLevel(WINEVENT_LEVEL_WARNING), // Levels defined in <winmeta.h>
    TraceLoggingKeyword(MyNetworkingKeyword),
    TraceLoggingString(operationName), // Adds an "operationName" field.
    TraceLoggingHResult(hr, "NetStatus")); // Adds a "NetStatus" field.

Pemanggilan TraceLoggingWrite(hProvider, "EventName", args...) dapat dianggap sebagai memperluas ke kode seperti berikut:

if (TraceLoggingProviderEnabled(hProvider, eventLevel, eventKeyword))
{
    static const metadata = { GetMetadataFromArgs(args...) };
    EVENT_DATA_DESCRIPTOR data[N] = { GetDataFromArgs(args...) };
    EventWriteTransfer(etwHandle, metadata.desc, NULL, NULL, N, data);
}

Catatan

Setiap makro TraceLoggingWrite secara otomatis memeriksa TraceLoggingProviderEnabled sehingga peristiwa hanya akan ditulis jika konsumen mendengarkan peristiwa dari penyedia. Akibatnya, biasanya tidak perlu langsung memanggil TraceLoggingProviderEnabled. Ekspresi runtime apa pun di args... akan dievaluasi jika dan hanya jika peristiwa diaktifkan. Ekspresi runtime tidak akan dievaluasi lebih dari sekali.

Jika menghasilkan peristiwa kompleks, Anda mungkin mendapatkan kesalahan pengkompilasi yang menunjukkan bahwa garis terlalu panjang atau pengkompilasi kehabisan ruang tumpukan. Ini terjadi ketika makro TraceLoggingWrite meluas ke garis yang lebih panjang dari yang dapat didukung oleh pengkompilasi. Jika ini terjadi, Anda harus menyederhanakan acara Anda.

Makro TraceLoggingWrite menggunakan array EVENT_DATA_DESCRIPTOR untuk mentransfer data ke ETW. Jumlah maksimum deskriptor yang diterima oleh ETW adalah 128. Karena setiap parameter mungkin memerlukan penggunaan 0, 1, atau 2 deskriptor, dimungkinkan untuk mencapai batas deskriptor data (128) sebelum mencapai batas argumen (99).

Penting

Cobalah untuk menghindari peristiwa besar. ETW terutama dirancang untuk menangani peristiwa kecil. TraceLoggingWrite akan secara diam-diam menghilangkan peristiwa apa pun yang terlalu besar. Ukuran peristiwa didasarkan pada total header peristiwa (ditambahkan oleh runtime ETW), metadata (yaitu nama penyedia, nama peristiwa, nama bidang, jenis bidang), dan data (nilai bidang). Jika ukuran total peristiwa lebih besar dari 65535 atau jika sesi konsumen menggunakan ukuran buffer yang lebih kecil dari ukuran peristiwa, peristiwa tidak akan direkam.

Panggilan ke TraceLoggingWrite sama dengan panggilan ke TraceLoggingWriteActivity dengan NULL untuk parameter pActivityId dan pRelatedActivityId . Gunakan TraceLoggingWriteActivity jika Anda perlu menentukan ID aktivitas untuk suatu peristiwa.

Contoh

#include <windows.h> // or <wdm.h> for kernel-mode.
#include <winmeta.h> // For event level definitions.
#include <TraceLoggingProvider.h>

TRACELOGGING_DEFINE_PROVIDER( // defines g_hProvider
    g_hProvider,  // Name of the provider handle
    "MyProvider", // Human-readable name of the provider
    // ETW Control GUID: {b3864c38-4273-58c5-545b-8b3608343471}
    (0xb3864c38,0x4273,0x58c5,0x54,0x5b,0x8b,0x36,0x08,0x34,0x34,0x71));

int main(int argc, char* argv[]) // or DriverEntry for kernel-mode.
{
    TraceLoggingRegister(g_hProvider);

    TraceLoggingWrite(
        g_hProvider,
        "MyEvent1",
        TraceLoggingLevel(WINEVENT_LEVEL_WARNING), // Levels defined in <winmeta.h>
        TraceLoggingKeyword(MyEventCategories), // Provider-defined categories
        TraceLoggingString(argv[0], "arg0"), // field name is "arg0"
        TraceLoggingInt32(argc)); // field name is implicitly "argc"

    TraceLoggingUnregister(g_hProvider);
    return 0;
}

Persyaratan


Klien minimum yang didukung	Windows Vista [aplikasi desktop \| Aplikasi UWP]
Server minimum yang didukung	Windows Server 2008 [aplikasi desktop \| Aplikasi UWP]
Target Platform	Windows
Header	traceloggingprovider.h
Pustaka	Advapi32.lib

Lihat juga

EventWriteTransfer

TraceLoggingWriteActivity

Makro Pembungkus Pelacakan

Bagikan melalui