Makro TraceLoggingWriteActivity (traceloggingprovider.h)

Artikel
08/26/2023

Memancarkan peristiwa TraceLogging dengan ID aktivitas tertentu.

Sintaks

void TraceLoggingWriteActivity(
  [in]            hProvider,
  [in]            eventName,
  [in, optional]  pActivityId,
  [in, optional]  pRelatedActivityId,
  [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 harfiah dan bukan variabel. Ini tidak boleh memiliki karakter yang disematkan '\0' .

[in, optional] pActivityId

ID aktivitas untuk peristiwa, atau NULL untuk menggunakan default.

[in, optional] pRelatedActivityId

ID aktivitas terkait untuk peristiwa, atau NULL tanpa ID aktivitas terkait.

[in, optional] __VA_ARGS__

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

Penting

ProviderId, Level, dan Keyword adalah sarana utama untuk memfilter peristiwa. Jenis pemfilteran lain 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 TraceLoggingWriteActivity diperluas ke kode yang diperlukan untuk menulis peristiwa ke ETW melalui handel penyedia yang ditentukan.

TraceLoggingWriteActivity memeriksa apakah penyedia yang ditentukan terdaftar. Jika penyedia tidak terdaftar, TraceLoggingWriteActivity tidak melakukan apa pun.
TraceLoggingWriteActivity memeriksa apakah ada konsumen yang mendengarkan peristiwa tersebut, seolah-olah dengan memanggil TraceLoggingProviderEnabled. Jika tidak ada konsumen yang mendengarkan peristiwa tersebut, TraceLoggingWriteActivity tidak melakukan apa pun.
Jika tidak, TraceLoggingWriteActivity mengevaluasi ekspresi runtime yang ditentukan dalam argumen, menyimpan hasilnya, mengemas data yang diperlukan ke dalam 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 .
ID aktivitas peristiwa akan berasal dari parameter pActivityId . Jika pActivityId ADALAH NULL, peristiwa mode pengguna akan menggunakan ID aktivitas implisit utas dan peristiwa mode kernel akan menggunakan GUID_NULL.
ID aktivitas terkait peristiwa akan berasal dari parameter pRelatedActivityId . Jika pRelatedActivityId adalah NULL, peristiwa tidak akan memiliki ID aktivitas terkait.
Tingkat peristiwa akan berasal dari argumen TraceLoggingLevel . Jika tidak ada argumen TraceLoggingLevel yang ada, 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 (NONE). Jika ada lebih dari satu argumen TraceLoggingKeyword, nilainya akan disatukan OR. Untuk mengaktifkan pemfilteran peristiwa yang efektif, selalu tetapkan kata kunci non-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:

TraceLoggingWriteActivity(
    g_hProvider,
    "MyEvent1",
    &myActivityGuid,
    NULL, // no related activity ID
    TraceLoggingLevel(WINEVENT_LEVEL_WARNING), // Levels defined in <winmeta.h>
    TraceLoggingKeyword(MyNetworkingKeyword), // Provider-defined categories
    TraceLoggingHResult(hr, "NetStatus")); // Adds a "NetStatus" field.

Pemanggilan TraceLoggingWriteActivity(hProvider, "EventName", aid, rid, 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, aid, rid, N, data);
}

Catatan

Setiap makro TraceLoggingWriteActivity 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 yang kompleks, Anda mungkin mendapatkan kesalahan kompilator yang menunjukkan bahwa garis terlalu panjang atau bahwa kompilator kehabisan ruang tumpukan. Ini terjadi ketika makro TraceLoggingWriteActivity meluas ke garis yang lebih panjang dari yang dapat didukung oleh pengkompilasi. Jika ini terjadi, Anda harus menyederhanakan acara Anda.

Makro TraceLoggingWriteActivity 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. TraceLoggingWriteActivity 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.

Lihat EventWriteTransfer untuk informasi tentang semantik parameter ActivityId dan RelatedActivityId .

Lihat EventActivityIdControl untuk informasi tentang aktivitas penulisan di ETW.

Lihat TraceLoggingActivity untuk kelas C++ yang membantu mengelola aktivitas TraceLogging ETW.

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

EventActivityIdControl

EventWriteTransfer

TraceLoggingActivity

TraceLoggingWrite

Makro Pembungkus TraceLogging