Fungsi EnableTrace (evntrace.h)

  • Artikel

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,
  [in] TRACEHANDLE TraceHandle
);

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.

[in] TraceHandle

Tangani sesi pelacakan peristiwa tempat Anda mengonfigurasi penyedia. Fungsi StartTrace mengembalikan handel ini saat pelacakan baru dimulai. Untuk mendapatkan handel pelacakan yang ada, gunakan ControlTrace untuk mengkueri properti pelacakan berdasarkan nama pelacakan lalu dapatkan handel dari bidang Wnode.HistoricalContext dari data yang dikembalikan EVENT_TRACE_PROPERTIES .

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 Paket Layanan 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 sebagai LocalSystem, LocalService, atau NetworkService dapat mengaktifkan penyedia peristiwa ke sesi lintas proses. Untuk memberi pengguna terbatas kemampuan untuk mengaktifkan penyedia peristiwa, tambahkan mereka ke Performance 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

   
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

Lihat juga

StartTrace

EnableTraceEx2