Fungsi TraceEventInstance (evntrace.h)

Artikel
08/23/2023

Penyedia peristiwa berbasis RegisterTraceGuids ("Klasik") menggunakan fungsi TraceEventInstance untuk mengirim peristiwa terstruktur ke sesi pelacakan peristiwa dengan pengidentifikasi instans.

Peristiwa ini menggunakan pengidentifikasi instans untuk mengaitkan peristiwa dengan transaksi. Fungsi ini juga dapat digunakan untuk melacak hubungan hierarkis antara peristiwa terkait.

Sintaks

ULONG WMIAPI TraceEventInstance(
  [in] TRACEHANDLE            TraceHandle,
  [in] PEVENT_INSTANCE_HEADER EventTrace,
  [in] PEVENT_INSTANCE_INFO   InstInfo,
  [in] PEVENT_INSTANCE_INFO   ParentInstInfo
);

Parameter

[in] TraceHandle

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

[in] EventTrace

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

Ukuran
Bendera
RegHandle

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

Class.Type
Class.Level

Untuk melacak hubungan hierarkis antara peristiwa terkait, atur juga anggota ParentRegHandle .

[in] InstInfo

Penunjuk ke struktur EVENT_INSTANCE_INFO , yang berisi handel pendaftaran untuk kelas pelacakan peristiwa ini dan pengidentifikasi instans. Gunakan fungsi CreateTraceInstanceId untuk menginisialisasi struktur.

[in] ParentInstInfo

Arahkan ke struktur EVENT_INSTANCE_INFO , yang berisi handel pendaftaran untuk kelas pelacakan peristiwa induk dan pengidentifikasi instansnya. Gunakan fungsi CreateTraceInstanceId untuk menginisialisasi struktur. Atur ke NULL jika Anda tidak melacak hubungan hierarkis.

Menampilkan nilai

Jika fungsi berhasil, nilai yang dikembalikan adalah ERROR_SUCCESS.

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

ERROR_INVALID_FLAGS

Anggota BenderaEVENT_INSTANCE_HEADER tidak berisi WNODE_FLAG_TRACED_GUID.
ERROR_OUTOFMEMORY

Memori tidak cukup untuk menyelesaikan panggilan fungsi. Penyebab kode kesalahan ini dijelaskan di bagian Keterangan berikut.
ERROR_INVALID_PARAMETER

Salah satu hal berikut ini benar:
- EventTrace adalah NULL.
- pInstInfo adalah NULL.
- Anggota pInstInfo adalah NULL.
- TraceHandle adalah NULL.
- Anggota UkuranEVENT_INSTANCE_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.

Windows 2000 dan Windows XP: Tidak didukung.
ERROR_OUTOFMEMORY

Kejadian ini 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 acara.
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_INSTANCE_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 mendukung 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 sendiri dan kelas pelacakan peristiwa.
Harus memanggil fungsi CreateTraceInstanceId untuk membuat pengidentifikasi instans untuk kelas pelacakan peristiwa terdaftar.
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 jejak ditulis dalam urutan terjadinya.

Untuk melacak peristiwa yang tidak terkait, gunakan fungsi TraceEvent .

Windows XP: Tidak berfungsi dengan benar.

Contoh

Untuk contoh pembuatan set peristiwa terkait menggunakan CreateTraceInstanceId dan TraceEventInstance, lihat Melacak Instans 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