Fungsi EventWriteString (evntprov.h)

Artikel
08/23/2023

Menulis peristiwa ETW yang berisi string sebagai datanya. Fungsi ini tidak boleh digunakan.

Sintaks

ULONG EVNTAPI EventWriteString(
  [in] REGHANDLE RegHandle,
  [in] UCHAR     Level,
  [in] ULONGLONG Keyword,
  [in] PCWSTR    String
);

Parameter

[in] RegHandle

Handel pendaftaran penyedia. Handel berasal dari EventRegister. Peristiwa yang dihasilkan akan menggunakan ProviderId yang terkait dengan handel.

[in] Level

Angka 8-bit yang digunakan untuk menjelaskan tingkat keparahan atau kepentingan peristiwa.

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 bukan nol dan kata kunci untuk setiap peristiwa.

Lihat EVENT_DESCRIPTOR untuk detail tentang tingkat peristiwa.

[in] Keyword

Bitmask 64-bit yang digunakan untuk menunjukkan keanggotaan peristiwa dalam serangkaian kategori peristiwa.

Penting

Lihat EVENT_DESCRIPTOR untuk detail tentang kata kunci peristiwa.

[in] String

String yang dihentikan NUL untuk ditulis sebagai data peristiwa.

Menampilkan nilai

Mengembalikan ERROR_SUCCESS jika berhasil atau kode kesalahan. Kemungkinan kode kesalahan meliputi yang berikut ini:

ERROR_INVALID_PARAMETER: Satu atau beberapa parameter tidak valid.
ERROR_INVALID_HANDLE: Handel pendaftaran penyedia tidak valid.
ERROR_ARITHMETIC_OVERFLOW: Ukuran peristiwa lebih besar dari maksimum yang diizinkan (64KB - header).
ERROR_MORE_DATA: Ukuran buffer sesi terlalu kecil untuk peristiwa tersebut.
ERROR_NOT_ENOUGH_MEMORY: Terjadi ketika buffer yang diisi mencoba memerah ke disk, tetapi IO disk tidak terjadi cukup cepat. Ini terjadi ketika disk lambat dan lalu lintas peristiwa padat. Akhirnya, tidak ada lagi buffer gratis (kosong) dan acara dihilangkan.
STATUS_LOG_FILE_FULL: File pemutaran real-time penuh. Peristiwa tidak dicatat ke sesi sampai konsumen real-time mengonsumsi peristiwa dari file pemutaran.

Kode kesalahan terutama ditujukan untuk digunakan dalam skenario penelusuran kesalahan dan diagnostik. Sebagian besar kode produksi harus terus berjalan dan terus melaporkan peristiwa bahkan jika peristiwa ETW tidak dapat ditulis, sehingga build rilis biasanya harus mengabaikan kode kesalahan.

Keterangan

API ini tidak berguna dan tidak boleh digunakan.

Sebagian besar alat analisis ETW tidak mendukung peristiwa khusus string dengan benar tanpa manifes.
Tanpa manifes, informasi penting tentang peristiwa (misalnya nama penyedia, id peristiwa, dan nama peristiwa) tidak tersedia sehingga peristiwa yang dihasilkan sulit digunakan bahkan ketika alat analisis mendukung peristiwa khusus string.
Dengan manifes, fungsi ini ber perilaku hampir persis seperti kode dari peristiwa berbasis manifes dengan satu bidang string. Namun, peristiwa berbasis manifes lebih didukung oleh alat analisis pelacakan. Selain itu, kode yang dihasilkan oleh MC.exe untuk peristiwa dengan bidang string tunggal lebih efisien daripada fungsi EventWriteString .

Alih-alih menggunakan API ini, pertimbangkan alternatif berikut:

Gunakan TraceLoggingProvider.h untuk menulis peristiwa yang didukung dengan baik oleh alat analisis ETW, bekerja tanpa manifes, dan menyertakan metadata seperti nama penyedia dan nama peristiwa.
Tulis manifes instrumentasi. Buat peristiwa sederhana dengan satu nilai string yang dihentikan NUL. Anda dapat menulis dan mengumpulkan peristiwa bahkan tanpa manifes. Anda hanya akan memerlukan manifes untuk mendekode jejak yang dikumpulkan.

EventWriteString menulis peristiwa dengan payload data yang terdiri dari string yang ditentukan. API ini hampir setara dengan kode berikut:

EVENT_DESCRIPTOR eventDescriptor;
EVENT_DATA_DESCRIPTOR dataDescriptor;
EventDescCreate(&eventDescriptor, 0, 0, 0, Level, 0, 0, Keyword);
EventDataDescCreate(&dataDescriptor, String, (wcslen(String) + 1) * sizeof(WCHAR));
return EventWrite(RegHandle, &eventDescriptor, 1, &dataDescriptor);

Peristiwa yang dihasilkan sama dengan peristiwa lain yang dihasilkan oleh EventWrite kecuali bahwa peristiwa yang dihasilkan memiliki set bendera EVENT_HEADER_FLAG_STRING_ONLY (lihat EVENT_HEADER untuk informasi tentang bendera peristiwa).

Perhatikan bahwa peristiwa ditulis dengan ID, Versi, Opcode, Tugas, dan Saluran diatur ke 0.

Perhatikan bahwa peristiwa menggunakan ID aktivitas utas saat ini.

Alat analisis ETW yang mengetahui bendera EVENT_HEADER_FLAG_STRING_ONLY dapat mengekstrak nilai string bahkan ketika dekoder tidak dapat menemukan informasi pendekodean lainnya untuk penyedia peristiwa. Namun, tanpa manifes, alat tidak akan dapat menentukan nama penyedia peristiwa.

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	evntprov.h
Pustaka	Advapi32.lib
DLL	Advapi32.dll

Lihat juga

EventWrite

TraceLoggingProvider.h

Bagikan melalui