Fungsi EnableTrace (evntrace.h)
Pengontrol sesi pelacakan memanggil EnableTrace untuk mengonfigurasi bagaimana penyedia peristiwa ETW mencatat peristiwa ke sesi pelacakan.
Fungsi ini usang. Fungsi EnableTraceEx2 menggantikan fungsi ini.
Sintaks
ULONG WMIAPI EnableTrace(
[in] ULONG Enable,
[in] ULONG EnableFlag,
[in] ULONG EnableLevel,
[in] LPCGUID ControlGuid,
CONTROLTRACE_ID TraceId
);
Parameter
[in] Enable
Atur ke 1 untuk mengaktifkan penerimaan peristiwa dari penyedia atau untuk menyesuaikan pengaturan yang digunakan saat menerima peristiwa dari penyedia (misalnya untuk mengubah tingkat dan kata kunci). Atur ke 0 untuk menonaktifkan penerimaan peristiwa dari penyedia.
[in] EnableFlag
Bitmask kata kunci 32-bit yang menentukan kategori peristiwa yang Anda inginkan untuk ditulis penyedia. Penyedia biasanya menulis peristiwa jika bit kata kunci peristiwa cocok dengan salah satu bit yang ditetapkan dalam nilai ini atau jika peristiwa tidak memiliki bit kata kunci yang ditetapkan, selain memenuhi kriteria EnableLevel .
Catatan
Penyedia berbasis EventRegister mendukung kata kunci 64-bit. Gunakan EnableTraceEx2 untuk mengaktifkan penyedia menggunakan masker MatchAnyKeyword 64-bit.
[in] EnableLevel
Nilai yang menunjukkan tingkat maksimum peristiwa yang Anda inginkan untuk ditulis oleh penyedia. Penyedia biasanya menulis peristiwa jika tingkat peristiwa kurang dari atau sama dengan nilai ini, selain memenuhi kriteria EnableFlag .
Nilai ini harus dalam rentang 1 hingga 255. Microsoft mendefinisikan semantik tingkat 1-5 seperti yang ditunjukkan di bawah ini. Nilai yang lebih rendah menunjukkan peristiwa yang lebih parah. Setiap nilai EnableLevel memungkinkan tingkat yang ditentukan dan semua tingkat yang lebih parah. Misalnya, jika Anda menentukan TRACE_LEVEL_WARNING
, konsumen Anda akan menerima peringatan, kesalahan, dan peristiwa penting.
Nilai | Makna |
---|---|
TRACE_LEVEL_CRITICAL (1) | Peristiwa keluar atau penghentian abnormal |
TRACE_LEVEL_ERROR (2) | Peristiwa kesalahan parah |
TRACE_LEVEL_WARNING (3) | Peristiwa peringatan seperti kegagalan alokasi |
TRACE_LEVEL_INFORMATION (4) | Peristiwa informasi non-kesalahan |
TRACE_LEVEL_VERBOSE (5) | Peristiwa diagnostik terperinci |
Konstanta TRACE_LEVEL
didefinisikan dalam evntrace.h. Konstanta yang WINMETA_LEVEL
setara didefinisikan dalam winmeta.h.
[in] ControlGuid
GUID kontrol (ID penyedia) penyedia peristiwa yang ingin Anda aktifkan atau nonaktifkan.
TraceId
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_PARAMETER
Salah satu hal berikut ini benar:
- ControlGuid adalah NULL.
- TraceHandle adalah NULL.
ERROR_INVALID_FUNCTION
Anda tidak dapat mengubah bendera dan tingkat aktif ketika penyedia tidak terdaftar.
ERROR_WMI_GUID_NOT_FOUND
Penyedia tidak terdaftar. Terjadi ketika KB307331 atau Windows 2000 Service Pack 4 diinstal dan penyedia tidak terdaftar. Untuk menghindari kesalahan ini, penyedia harus terlebih dahulu didaftarkan.
ERROR_NO_SYSTEM_RESOURCES
Melebihi jumlah sesi pelacakan yang dapat mengaktifkan penyedia.
ERROR_ACCESS_DENIED
Hanya pengguna dengan hak administratif, pengguna dalam
Performance Log Users
grup, dan layanan yang berjalan sebagaiLocalSystem
,LocalService
, atauNetworkService
dapat mengaktifkan penyedia peristiwa ke sesi lintas proses. Untuk memberi pengguna terbatas kemampuan untuk mengaktifkan penyedia peristiwa, tambahkan mereka kePerformance Log Users
grup atau lihat EventAccessControl.Windows XP dan Windows 2000: Siapa pun dapat mengaktifkan penyedia peristiwa.
Keterangan
Pengontrol pelacakan peristiwa memanggil fungsi ini untuk mengonfigurasi penyedia peristiwa yang menulis peristiwa ke sesi. Misalnya, pengontrol mungkin memanggil fungsi ini untuk mulai mengumpulkan peristiwa dari penyedia, untuk menyesuaikan tingkat atau kata kunci peristiwa yang dikumpulkan dari penyedia, atau berhenti mengumpulkan peristiwa dari penyedia.
Fungsi ini usang. Untuk fungsionalitas tambahan, kode baru harus menggunakan EnableTraceEx2.
Dua panggilan fungsi berikut setara:
// Obsolete:
Status = EnableTrace(
Enable,
EnableFlag,
EnableLevel,
ControlGuid,
TraceHandle);
// Updated equivalent code:
Status = EnableTraceEx2(
TraceHandle,
ControlGuid,
Enable, // ControlCode
EnableLevel,
EnableFlag, // MatchAnyKeyword
0, // MatchAllKeyword
0, // Timeout
NULL); // EnableParameters
Untuk detail tambahan tentang semantik mengonfigurasi penyedia untuk sesi, lihat dokumentasi untuk EnableTraceEx2.
Persyaratan
Persyaratan | Nilai |
---|---|
Klien minimum yang didukung | Windows 2000 Professional [aplikasi desktop | Aplikasi UWP] |
Server minimum yang didukung | Windows 2000 Server [aplikasi desktop | Aplikasi UWP] |
Target Platform | Windows |
Header | evntrace.h |
Pustaka | Advapi32.lib |
DLL | Advapi32.dll |