Fungsi EnableTraceEx (evntrace.h)

  • Artikel

Pengontrol sesi pelacakan memanggil EnableTraceEx untuk mengonfigurasi bagaimana penyedia peristiwa ETW mencatat peristiwa ke sesi pelacakan.

Fungsi ini usang. Fungsi EnableTraceEx2 menggantikan fungsi ini.

Sintaks

ULONG WMIAPI EnableTraceEx(
  [in]           LPCGUID                  ProviderId,
  [in, optional] LPCGUID                  SourceId,
  [in]           TRACEHANDLE              TraceHandle,
  [in]           ULONG                    IsEnabled,
  [in]           UCHAR                    Level,
  [in]           ULONGLONG                MatchAnyKeyword,
  [in]           ULONGLONG                MatchAllKeyword,
  [in]           ULONG                    EnableProperty,
  [in, optional] PEVENT_FILTER_DESCRIPTOR EnableFilterDesc
);

Parameter

[in] ProviderId

ID penyedia (GUID kontrol) penyedia peristiwa yang ingin Anda konfigurasi.

[in, optional] SourceId

GUID yang dapat mengidentifikasi sumber permintaan konfigurasi ini secara unik, atau NULL jika tidak ada identitas sumber yang diperlukan (setara dengan mengatur SourceId ke &GUID_NULL). Jika ditentukan, nilai ini digunakan sebagai parameter SourceId saat memanggil EnableCallback penyedia.

Catatan

Tidak selalu ada pemetaan langsung antara panggilan ke EnableTrace dan panggilan yang sesuai ke EnableCallback penyedia. Misalnya, jika EnableTrace dipanggil untuk penyedia yang belum terdaftar, panggilan ke EnableCallback akan ditangguhkan sampai pendaftaran terjadi, dan jika sesi konsumen jejak dihentikan, ETW akan memanggil EnableCallback meskipun tidak ada panggilan yang sesuai ke EnableTrace. Dalam kasus seperti itu, EnableTrace akan dipanggil dengan SourceId diatur ke GUID_NULL.

[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 .

[in] IsEnabled

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] Level

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 MatchAnyKeyword dan MatchAllKeyword .

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] MatchAnyKeyword

Bitmask kata kunci 64-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 Level dan MatchAllKeyword .

[in] MatchAllKeyword

Bitmask kata kunci 64-bit yang membatasi peristiwa yang Anda inginkan untuk ditulis oleh penyedia. Penyedia biasanya menulis peristiwa jika bit kata kunci peristiwa cocok dengan semua bit yang ditetapkan dalam nilai ini atau jika peristiwa tidak memiliki bit kata kunci yang ditetapkan, selain memenuhi kriteria Level dan MatchAnyKeyword .

Nilai ini sering diatur ke 0.

[in] EnableProperty

Bendera yang menentukan perilaku khusus yang harus diaktifkan runtime ETW saat mengumpulkan peristiwa dari penyedia ini. Untuk mengaktifkan perilaku khusus, tentukan satu atau beberapa bendera berikut. Jika tidak, atur EnableProperty ke 0.

Catatan

Beberapa bendera ini menunjukkan bahwa ETW harus menyertakan informasi tambahan ke dalam setiap peristiwa. Data ditulis ke bagian item data yang diperluas dari peristiwa.

Nilai Makna
EVENT_ENABLE_PROPERTY_SID Sertakan pengidentifikasi keamanan (SID) pengguna dalam data yang diperluas.
EVENT_ENABLE_PROPERTY_TS_ID Sertakan pengidentifikasi sesi terminal dalam data yang diperluas.
EVENT_ENABLE_PROPERTY_IGNORE_KEYWORD_0 Sesi pelacakan tidak boleh merekam peristiwa yang memiliki kata kunci 0.

[in, optional] EnableFilterDesc

Struktur EVENT_FILTER_DESCRIPTOR yang menunjuk ke data filter. Penyedia menggunakan ini untuk memfilter data untuk mencegah peristiwa yang tidak cocok dengan kriteria filter ditulis ke sesi. Penyedia menentukan tata letak data dan cara menerapkan filter ke data peristiwa. Sesi hanya dapat meneruskan satu filter ke penyedia.

Sesi dapat memanggil fungsi TdhEnumerateProviderFilters untuk mencari filter tempat penyedia telah mendaftarkan dukungan.

Nilai kembali

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:

    • ProviderId adalah NULL.
    • TraceHandle adalah NULL.

  • ERROR_INVALID_FUNCTION

    Anda tidak dapat memperbarui tingkat ketika penyedia tidak terdaftar.

  • 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.

Dalam kebanyakan kasus, panggilan ke EnableTraceEx dapat dikonversi ke EnableTraceEx2 sebagai berikut:

// Obsolete:
Status =
EnableTraceEx(
    ProviderId,
    NULL,           // SourceId
    TraceHandle,
    IsEnabled,
    Level,
    MatchAnyKeyword,
    MatchAllKeyword,
    0,              // EnableProperty
    NULL);          // EnableFilterDesc

// Updated equivalent code:
Status = EnableTraceEx2(
    TraceHandle,
    ProviderId,
    IsEnabled,
    Level,
    MatchAnyKeyword,
    MatchAllKeyword,
    0,              // Timeout
    NULL);          // EnableParameters

Dalam skenario yang lebih kompleks, panggilan ke EnableTraceEx dapat dikonversi ke EnableTraceEx2 sebagai berikut:

// Obsolete:
Status =
EnableTraceEx(
    ProviderId,
    SourceId,
    TraceHandle,
    IsEnabled,
    Level,
    MatchAnyKeyword,
    MatchAllKeyword,
    EnableProperty,
    EnableFilterDesc);

// Updated equivalent code:
ENABLE_TRACE_PARAMETERS EnableParameters = {
    ENABLE_TRACE_PARAMETERS_VERSION_2,
    EnableProperty,
    0,                 // ControlFlags
    SourceId ? *SourceId : GUID_NULL,
    EnableFilterDesc,
    EnableFilterDesc ? 1 : 0 };
Status = EnableTraceEx2(
    TraceHandle,
    ProviderId,
    IsEnabled,
    Level,
    MatchAnyKeyword,
    MatchAllKeyword,
    0,                 // Timeout
    &EnableParameters);

Untuk detail tambahan tentang semantik mengonfigurasi penyedia untuk sesi, lihat dokumentasi untuk EnableTraceEx2.

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

Lihat juga

StartTrace

EnableTraceEx2