Fungsi StartTraceA (evntrace.h)

  • Artikel

Fungsi StartTrace mendaftar dan memulai sesi pelacakan peristiwa.

Penting

Sesi pelacakan peristiwa lintas proses adalah sumber daya sistem terbatas. Pengembang harus menghindari memulai sesi pelacakan peristiwa di komputer pelanggan. Ketika sesi pelacakan peristiwa diperlukan, sesi harus dibatasi pada cakupan sekecil mungkin: gunakan sesi sesegera mungkin, gunakan sesi hanya dalam proses jika memungkinkan (EVENT_TRACE_PRIVATE_LOGGER_MODE | EVENT_TRACE_PRIVATE_IN_PROC), hanya mulai jejak ketika koleksi secara khusus diperlukan untuk skenario, hentikan jejak segera setelah skenario selesai, batasi jumlah memori yang digunakan oleh sesi, dan gunakan filter peristiwa yang ketat sehingga Anda tidak mengumpulkan peristiwa yang tidak perlu.

Sintaks

ULONG WMIAPI StartTraceA(
  [out]     PTRACEHANDLE            TraceHandle,
  [in]      LPCSTR                  InstanceName,
  [in, out] PEVENT_TRACE_PROPERTIES Properties
);

Parameter

[out] TraceHandle

Menerima handel ke sesi pelacakan peristiwa untuk penggunaan berikutnya dengan API seperti ControlTrace.

Jangan gunakan handel ini jika fungsi gagal. Jangan bandingkan handel sesi dengan INVALID_HANDLE_VALUE. Handel sesi adalah 0 jika handel tidak valid.

[in] InstanceName

String yang dihentikan null yang berisi nama sesi pelacakan peristiwa. Nama sesi dibatasi hingga 1.024 karakter, tidak peka huruf besar/kecil, dan harus unik.

Penting

Gunakan nama deskriptif untuk sesi Anda sehingga kepemilikan dan penggunaan sesi dapat ditentukan dari nama sesi. Jangan gunakan GUID atau nilai non-deterministik atau non-deskriptif lainnya. Jangan tambahkan digit acak untuk membuat nama sesi Anda unik. Sesi ETW adalah sumber daya terbatas sehingga komponen Anda tidak boleh memulai beberapa sesi. Jika sesi komponen Anda sudah berjalan saat komponen Anda dimulai, komponen Anda harus membersihkan sesi tanpa induk daripada membuat sesi kedua.

Fungsi ini menyalin nama sesi yang Anda berikan ke offset yang dirujuk oleh anggota LoggerNameOffset properti.

[in, out] Properties

Arahkan ke struktur EVENT_TRACE_PROPERTIES yang menentukan perilaku sesi. Berikut ini adalah anggota kunci struktur yang akan diatur:

  • Wnode.BufferSize
  • Wnode.Guid
  • Wnode.ClientContext
  • Wnode.Flags
  • LogFileMode
  • LogFileNameOffset
  • LoggerNameOffset

Bergantung pada jenis file log yang Anda pilih untuk dibuat, Anda mungkin juga perlu menentukan nilai untuk MaximumFileSize. Lihat bagian Keterangan untuk informasi selengkapnya tentang mengatur parameter Properti dan perilaku sesi.

Dimulai dengan Windows 10, versi 1703: Untuk performa yang lebih baik dalam skenario lintas proses, Anda sekarang dapat meneruskan pemfilteran ke StartTrace saat memulai pencatat privat lebar sistem. Anda harus meneruskan struktur EVENT_TRACE_PROPERTIES_V2 baru untuk menyertakan informasi pemfilteran. Lihat Mengonfigurasi dan Memulai Sesi Pencatat Privat untuk detail selengkapnya.

Mengembalikan 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_BAD_LENGTH

    Salah satu hal berikut ini benar:

    • Anggota Properti Wnode.BufferSizemenentukan ukuran yang salah.
    • Properti tidak memiliki cukup ruang yang dialokasikan untuk menyimpan salinan InstanceName.

  • ERROR_INVALID_PARAMETER

    Salah satu hal berikut ini benar:

    • Properti adalah NULL.
    • TraceHandle adalah NULL.
    • Anggota LogFileNameOffsetproperti tidak valid.
    • Anggota LoggerNameOffsetproperti tidak valid.
    • Anggota Properti LogFileMode menentukan kombinasi bendera yang tidak valid.
    • Anggota Wnode.Guid adalah SystemTraceControlGuid, tetapi parameter InstanceName tidak KERNEL_LOGGER_NAME.

  • ERROR_ALREADY_EXISTS

    Sesi dengan nama atau GUID yang sama sudah berjalan.

  • ERROR_BAD_PATHNAME

    Anda dapat menerima kesalahan ini karena salah satu alasan berikut:

    • Sesi lain sudah menggunakan nama file yang ditentukan oleh anggota LogFileNameOffset dari struktur Properti .
    • LogFileMode dan LogFileNameOffset adalah nol.

  • ERROR_DISK_FULL

    Tidak cukup ruang kosong pada kandar untuk file log. Ini terjadi jika:

    • MaximumFileSize bukan nol dan tidak ada byte MaximumFileSize yang tersedia untuk file log
    • drive adalah drive sistem dan tidak ada tambahan 200 MB yang tersedia
    • MaximumFileSize adalah nol dan tidak ada tambahan 200 MB yang tersedia

    Pilih drive dengan lebih banyak ruang, atau kurangi ukuran yang ditentukan dalam MaximumFileSize (jika digunakan).

  • ERROR_ACCESS_DENIED

    Hanya pengguna dengan hak istimewa administratif, pengguna di grup Pengguna Log Performa, dan layanan yang berjalan sebagai LocalSystem, LocalService, NetworkService yang dapat mengontrol sesi pelacakan peristiwa. Untuk memberi pengguna terbatas kemampuan untuk mengontrol sesi pelacakan, tambahkan mereka ke grup Pengguna Log Performa. Hanya pengguna dengan hak administratif dan layanan yang berjalan sebagai LocalSystem yang dapat mengontrol sesi NT Kernel Logger.

    Jika pengguna adalah anggota grup Pengguna Log Performa, mereka mungkin tidak memiliki izin untuk membuat file log di folder yang ditentukan.

  • ERROR_NO_SYSTEM_RESOURCES

    Salah satu hal berikut ini benar:

    • Sesi pengelogan menggunakan bendera EVENT_TRACE_SYSTEM_LOGGER_MODE dan jumlah maksimum pencatat sistem (8) telah tercapai.

    • Jumlah maksimum sesi pengelogan pada sistem telah tercapai. Tidak ada pencatat baru yang dapat dibuat sampai sesi pengelogan dihentikan. Pada sebagian besar sistem, jumlah maksimum sesi pengelogan adalah 64.

      Anda dapat mengubah jumlah maksimum sesi pengelogan untuk sistem dengan mengedit kunci REG_DWORD di HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\WMI@EtwMaxLoggers. Nilai yang diizinkan adalah 32 hingga 256, inklusif. Reboot diperlukan agar perubahan apa pun berlaku.

      Perhatikan bahwa Pencatat menggunakan sumber daya sistem. Meningkatkan jumlah pencatat pada sistem akan dikenakan biaya performa jika slot tersebut terisi. Batas ini ada untuk mencegah penggunaan sumber daya sistem yang berlebihan.

      Penting

      Batas hanya boleh disesuaikan secara manual oleh administrator sistem untuk mengaktifkan skenario tertentu. Pengaturan EtwMaxLoggers tidak boleh dimodifikasi secara otomatis oleh program atau driver.

      Sebelum Windows 10, versi 1709, ini adalah batas tetap 64 pencatat untuk pencatat non-privat.

Keterangan

Pengontrol pelacakan peristiwa memanggil fungsi ini.

Sesi tetap aktif sampai sesi dihentikan, komputer dimulai ulang, kesalahan I/O terjadi, atau ukuran file maksimum tercapai untuk log non-melingkar. Untuk menghentikan sesi pelacakan peristiwa, panggil fungsi ControlTrace dan atur parameter ControlCode ke EVENT_TRACE_CONTROL_STOP.

Anda tidak dapat memulai lebih dari satu sesi dengan GUID sesi yang sama (seperti yang ditentukan oleh Properties.Wnode.Guid). Dalam kebanyakan kasus, Anda akan mengatur Properties.Wnode.Guid ke all-zero (yaitu GUID_NULL) untuk memungkinkan sistem ETW menghasilkan GUID baru untuk sesi tersebut.

Untuk menentukan sesi pencatat privat, atur anggota Properti Wnode.Guidke GUID kontrol penyedia, bukan GUID kontrol sesi pencatat privat. Penyedia harus telah mendaftarkan GUID sebelum Anda memanggil StartTrace.

Anda tidak menggunakan fungsi ini untuk memulai sesi pencatat global (tidak digunakan lagi). Untuk detail tentang memulai sesi pencatat global, lihat Mengonfigurasi dan Memulai Sesi Pencatat Global.

Pencatat Sistem

Agar pencatat menjadi pencatat sistem dan menerima peristiwa dari SystemTraceProvider atau penyedia sistem lainnya, salah satu hal berikut ini harus benar:

  • Anggota PropertiLogFileMode menyertakan bendera EVENT_TRACE_SYSTEM_LOGGER_MODE (lebih disukai ).
  • Anggota PropertiWnode.Guid diatur ke SystemTraceControlGuid atau GlobalLoggerGuid (tidak digunakan lagi - tidak boleh digunakan untuk kode baru karena akan bertentangan dengan komponen lain yang juga mencoba menggunakan GUID ini).
  • InstanceName diatur ke KERNEL_LOGGER_NAME (tidak digunakan lagi - tidak boleh digunakan untuk kode baru karena akan berkonflik dengan komponen lain yang juga mencoba menggunakan nama ini).

Catatan

 Pencatat sistem harus mengatur anggota EnableFlags dari struktur EVENT_TRACE_PROPERTIES untuk menunjukkan peristiwa SystemTraceProvider mana yang harus disertakan dalam jejak.

Karena pencatat sistem menerima peristiwa kernel khusus, mereka tunduk pada batasan tambahan:

  • Tidak boleh ada lebih dari 8 pencatat sistem yang aktif pada sistem yang sama.
  • Pencatat sistem tidak dapat dibuat dalam kontainer Windows Server.
  • Pencatat sistem tidak dapat menggunakan bendera EVENT_TRACE_USE_PAGED_MEMORY .
  • Sebelum Windows 10, versi 1703, tidak lebih dari 2 jenis jam yang berbeda dapat digunakan secara bersamaan oleh pencatat sistem apa pun. Misalnya, jika satu pencatat sistem aktif menggunakan jenis jam "penghitung siklus CPU", dan pencatat sistem aktif lainnya menggunakan jenis jam "Penghitung kinerja kueri", maka setiap upaya untuk memulai pencatat sistem menggunakan jenis jam "Waktu sistem" akan gagal karena akan memerlukan aktivasi jenis jam ketiga. Karena keterbatasan ini, Microsoft sangat menyarankan agar pencatat sistem tidak menggunakan jenis jam "Waktu sistem".
  • Dimulai dengan Windows 10, versi 1703, pembatasan jenis jam telah dihapus. Ketiga jenis jam sekarang dapat digunakan secara bersamaan oleh pencatat sistem.

Untuk menentukan sesi Pencatat Kernel NT (tidak digunakan lagi), atur InstanceName ke KERNEL_LOGGER_NAME dan anggota Properti Wnode.GuidkeSystemTraceControlGuid. Jika Anda tidak menentukan GUID sebagai SystemTraceControlGuid, ETW akan mengambil alih nilai GUID dan mengaturnya ke SystemTraceControlGuid.

Contoh

Untuk contoh yang menggunakan StartTrace, lihat Mengonfigurasi dan Memulai Sesi Pelacakan Peristiwa.

Catatan

Header evntrace.h mendefinisikan StartTrace sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta pra-prosesor UNICODE. Mencampur penggunaan alias encoding-netral dengan kode yang tidak mengodekan-netral dapat menyebabkan ketidakcocokan yang mengakibatkan kesalahan kompilasi atau runtime. Untuk informasi selengkapnya, lihat Konvensi untuk Prototipe Fungsi.

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 Sechost.lib di Windows 8.1 dan Windows Server 2012 R2; Advapi32.lib di Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista
DLL Sechost.dll di Windows 8.1 dan Windows Server 2012 R2; Advapi32.dll di Windows 8, Windows Server 2012, Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista

Lihat juga

ControlTrace

EVENT_TRACE_PROPERTIES