Share via

Fungsi EventActivityIdControl (evntprov.h)

  • Artikel

Membuat, mengkueri, dan mengatur pengidentifikasi aktivitas untuk digunakan dalam peristiwa ETW.

Sintaks

ULONG EVNTAPI EventActivityIdControl(
  [in]      ULONG  ControlCode,
  [in, out] LPGUID ActivityId
);

Parameter

[in] ControlCode

Kode kontrol yang menentukan operasi yang akan dilakukan.

  • EVENT_ACTIVITY_CTRL_GET_ID

    Mengatur parameter ActivityId ke nilai ID aktivitas utas saat ini.

  • EVENT_ACTIVITY_CTRL_SET_ID

    Mengatur ID aktivitas utas saat ini ke nilai parameter ActivityId .

  • EVENT_ACTIVITY_CTRL_CREATE_ID

    Mengatur parameter ActivityId ke nilai ID aktivitas unik lokal yang baru dibuat.

  • EVENT_ACTIVITY_CTRL_GET_SET_ID

    Menukar nilai parameter ActivityId dan ID aktivitas utas saat ini. (Menyimpan nilai ID aktivitas utas saat ini, lalu mengatur ID aktivitas utas saat ini ke nilai parameter ActivityId , lalu mengatur parameter ActivityId ke nilai tersimpan.)

  • EVENT_ACTIVITY_CTRL_CREATE_SET_ID

    Mengatur parameter ActivityId ke nilai ID aktivitas utas saat ini, lalu mengatur ID aktivitas utas saat ini ke nilai ID aktivitas unik lokal yang baru dibuat.

[in, out] ActivityId

Pointer ke buffer yang berisi ID aktivitas 128-bit. Buffer ini mungkin baca-dari dan/atau ditulis-ke, tergantung pada nilai parameter ControlCode .

Mengembalikan nilai

Mengembalikan ERROR_SUCCESS jika berhasil.

Keterangan

Peristiwa ETW yang ditulis menggunakan salah satu API EventWrite akan berisi bidang "ID aktivitas" 128-bit dan dapat secara opsional berisi bidang "ID aktivitas terkait" 128-bit. Alat pemrosesan jejak dapat menggunakan nilai bidang ini untuk mengatur peristiwa ke dalam grup yang disebut aktivitas.

  • Semua peristiwa dengan ID aktivitas nol (yaitu GUID_NULL) diasumsikan tidak menjadi bagian dari aktivitas apa pun.
  • Semua peristiwa yang memiliki ID aktivitas non-nol tertentu diasumsikan sebagai bagian dari aktivitas yang sama.
  • Untuk menunjukkan awal aktivitas, penyedia harus mengatur Opcode ke WINEVENT_OPCODE_START untuk peristiwa pertama dengan ID aktivitas non-nol tertentu (peristiwa mulai ). Jika aktivitas secara logis disarangkan dalam aktivitas lain, penyedia harus mengatur bidang ID aktivitas terkait peristiwa mulai ke ID aktivitas induk.
  • Untuk menunjukkan akhir aktivitas, penyedia harus mengatur Opcode ke WINEVENT_OPCODE_STOP untuk peristiwa terakhir dengan ID aktivitas non-nol tertentu (peristiwa berhenti ).

Agar ID aktivitas berguna, ID aktivitas yang baru dibuat harus unik secara lokal, yaitu ID yang sama tidak boleh dihasilkan dua kali dalam jejak.

Anda dapat membuat ID aktivitas menggunakan EventActivityIdControl, yang menghasilkan ID unik lokal yang dijamin unik di semua proses pada sistem lokal hingga sistem di-boot ulang. Anda juga dapat menggunakan GUID (pengidentifikasi unik global) sebagai ID aktivitas. Anda dapat membuat GUID menggunakan API seperti UuidCreate.

Utas mode pengguna memiliki nilai ID aktivitas 128-bit thread-local (ID aktivitas utas). ID aktivitas utas diinisialisasi ke 0 (yaitu GUID_NULL) saat utas dibuat. ID aktivitas utas dapat dibaca atau diperbarui menggunakan EventActivityIdControl. ID aktivitas utas akan digunakan sebagai ID aktivitas untuk semua peristiwa yang ditulis oleh EventWrite dan untuk semua peristiwa yang ditulis oleh EventWriteTransfer atau EventWriteEx di mana parameter ActivityId adalah NULL.

Penting

Fungsi yang mengubah ID aktivitas utas harus berhati-hati untuk memulihkan ID aktivitas asli sebelum keluar. Jika tidak, perubahan fungsi pada ID aktivitas utas akan mengganggu aktivitas komponen yang memanggil fungsi.

Menggunakan ID aktivitas yang ditentukan secara eksplisit

Dalam kasus di mana aktivitas Anda tidak terbatas pada satu utas atau di mana Anda ingin menghindari kemungkinan gangguan dari komponen lain yang menimpa ID aktivitas utas Anda, Anda mungkin ingin secara eksplisit menentukan aktivitas peristiwa melalui bidang ActivityIdeventWriteTransfer atau EventWriteEx alih-alih menggunakan ID aktivitas utas otomatis.

Jika menggunakan manifes dan Pengkompilasi Pesan untuk menulis peristiwa, makro yang dihasilkan dengan MC.exe -um menggunakan ID aktivitas utas saat makro yang dihasilkan oleh MC.exe -km mendukung parameter ID aktivitas. Awalnya, -um makro hanya berfungsi dalam mode pengguna, dan -km makro hanya berfungsi dalam mode kernel, sehingga kode mode pengguna hanya dapat menggunakan ID aktivitas utas saat ini. Namun, dimulai dengan MC.exe versi 10.0.17741, makro yang dihasilkan oleh MC.exe -km dapat digunakan untuk mode pengguna dan mode kernel, sehingga Anda dapat menggunakan MC.exe -km untuk menghasilkan makro yang menerima parameter ID aktivitas. (Kode yang dihasilkan MC tidak mendukung pengaturan ID aktivitas terkait peristiwa.)

Jika menggunakan TraceLoggingProvider.h untuk menulis peristiwa, makro TraceLoggingWrite menggunakan ID aktivitas utas, sementara TraceLoggingWriteActivity menerima parameter untuk ID aktivitas dan ID aktivitas terkait. Atau, Anda dapat menggunakan kelas C++ di TraceLoggingActivity.h untuk aktivitas TraceLogging Anda.

Persyaratan

Persyaratan Nilai
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 evntprov.h
Pustaka Advapi32.lib
DLL Advapi32.dll

Lihat juga

EventWriteTransfer