Fungsi TraceEvent (evntrace.h)

Artikel
08/23/2023

Penyedia peristiwa berbasis RegisterTraceGuids ("Klasik") menggunakan fungsi TraceEvent untuk mengirim peristiwa terstruktur ke sesi pelacakan peristiwa.

Sintaks

ULONG WMIAPI TraceEvent(
  [in] TRACEHANDLE         TraceHandle,
  [in] PEVENT_TRACE_HEADER EventTrace
);

Parameter

[in] TraceHandle

Tangani ke sesi pelacakan peristiwa yang merekam peristiwa. Penyedia memperoleh handel ketika memanggil fungsi GetTraceLoggerHandle dalam implementasi ControlCallback-nya .

[in] EventTrace

Arahkan ke struktur EVENT_TRACE_HEADER . Data khusus peristiwa secara opsional ditambahkan ke struktur. Peristiwa terbesar yang dapat Anda catat sedikit kurang dari 64K. Anda harus menentukan nilai untuk anggota struktur EVENT_TRACE_HEADER berikut.

Ukuran
Guid atau GuidPtr
Bendera

Bergantung pada kompleksitas informasi yang disediakan penyedia Anda, Anda juga harus mempertimbangkan untuk menentukan nilai untuk anggota berikut.

Class.Type
Class.Level

Menampilkan nilai

Jika fungsi berhasil, nilai yang dikembalikan ERROR_SUCCESS.

Jika fungsi gagal, nilai yang dikembalikan adalah salah satu kode kesalahan sistem. Berikut ini adalah beberapa kesalahan umum dan penyebabnya.

ERROR_INVALID_FLAG_NUMBER

Anggota Bendera dari struktur EVENT_TRACE_HEADER salah.
ERROR_INVALID_HANDLE

TraceHandle tidak valid atau menentukan handel sesi NT Kernel Logger.
ERROR_NOT_ENOUGH_MEMORY

Sesi kehabisan buffer gratis untuk ditulis. Ini dapat terjadi selama tingkat peristiwa tinggi karena subsistem disk kelebihan beban atau jumlah buffer terlalu kecil. Daripada memblokir hingga lebih banyak buffer tersedia, TraceEvent membuang peristiwa.

Pertimbangkan untuk meningkatkan jumlah dan ukuran buffer untuk sesi, atau mengurangi jumlah peristiwa yang ditulis atau ukuran peristiwa.

Windows 2000: Tidak didukung.
ERROR_OUTOFMEMORY

Peristiwa dibuang karena, meskipun kumpulan buffer belum mencapai ukuran maksimumnya, memori yang tersedia tidak cukup untuk mengalokasikan buffer tambahan dan tidak ada buffer yang tersedia untuk menerima peristiwa.
ERROR_INVALID_PARAMETER

Salah satu hal berikut ini benar:
- TraceHandle adalah NULL.
- EventTrace adalah NULL.
- Anggota Ukuran struktur EVENT_TRACE_HEADER salah.
ERROR_MORE_DATA

Data dari satu peristiwa tidak dapat menjangkau beberapa buffer. Peristiwa pelacakan terbatas pada ukuran buffer sesi pelacakan peristiwa dikurangi ukuran struktur EVENT_TRACE_HEADER .

Keterangan

Penyedia ETW berbasis MOF memanggil fungsi ini.

Catatan

Sebagian besar pengembang tidak akan memanggil fungsi ini. API ini mendukung ETW berbasis MOF, tetapi ETW berbasis MOF tidak digunakan lagi demi ETW berbasis manifes. Selain itu, sebagian besar penyedia berbasis MOF menggunakan fungsi pembungkus yang dihasilkan oleh MC.exe alih-alih langsung memanggil API ETW.

Sebelum penyedia dapat memanggil fungsi ini, penyedia

Harus memanggil fungsi RegisterTraceGuids untuk mendaftarkan dirinya dan kelas pelacakan peristiwa.
Harus diaktifkan. Pengontrol memanggil fungsi EnableTrace untuk mengaktifkan penyedia.

Peristiwa ini ditulis ke file log, dikirim ke konsumen pelacakan peristiwa secara real time, atau keduanya. Anggota LogFileMode dari struktur EVENT_TRACE_PROPERTIES yang diteruskan ke StartTrace menentukan tempat peristiwa dikirim.

Peristiwa pelacakan ditulis dalam urutan di mana peristiwa tersebut terjadi.

Untuk melacak serangkaian peristiwa terkait, gunakan fungsi TraceEventInstance .

Pada Windows Vista, Anda harus menggunakan fungsi EventWrite untuk mencatat peristiwa.

Contoh

Untuk contoh yang menggunakan TraceEvent, lihat Melacak Peristiwa.

Persyaratan


Klien minimum yang didukung	Windows 2000 Professional [hanya aplikasi desktop]
Server minimum yang didukung	Windows 2000 Server [hanya aplikasi desktop]
Target Platform	Windows
Header	evntrace.h
Pustaka	Advapi32.lib
DLL	Advapi32.dll